Starting a new course - Neuromatch Course Guide

Don’t fork or copy this repository. It is a guide and a set of worked examples, and your course will never merge back into it. Everything a course needs is generated by the kit’s init command, which gives you a fresh repository with its own history.

1. Create the repository¶

Create an empty repository on GitHub (public, so Colab and Kaggle can read the notebooks), clone it, and from its root run:

uv venv && uv pip install neuromatch-course-kit
uv run nma-kit init --title "My Course" --author "Your Name" \
    --github https://github.com/<org>/<repo>

Leave out the flags and init asks for them. It also takes --license (BSD-3-Clause, MIT, Apache-2.0 or CC-BY-4.0) and --preview (turns on the pull request preview job, which needs Cloudflare Pages). init never overwrites existing files.

2. What you get¶

File	Purpose
`myst.yml`	Title, authors, GitHub URL, table of contents, branding. The kit is loaded with `extend:`.
`.github/workflows/course.yml`	Calls the kit’s reusable workflows: checks on pull requests, publishing on `main`.
`tutorials/`	An intro page and one example day with a video, an exercise and a solution.
`projects/`	A stub for the project booklet.
`requirements.txt`	The packages your tutorials import.
`README.md`	A setup checklist for GitHub Pages and the first push.
`LICENSE`, `.gitignore`, `.nvmrc`	Licence of your choice, ignores generated folders, Node version for MyST.

The feedback settings (nma.feedback) are commented out. Feedback widgets post to a datatops project, so ask its owner for your own project and key. Don’t copy the values from this book’s myst.yml.

3. Make it yours¶

Work through the checklist in the generated README.md.
Read the example day, then replace it with your own and update project.toc.
Preview with uv run nma-kit sync-assets && uv run myst start.
Push to main.

Use the days of this book as the reference for each feature: writing pages (Week 1 Day 1), interactive content and exercises (Week 1 Day 2), publishing and branding (Week 1 Day 3), and full converted tutorials (Week 2 Day 1).

Getting kit updates¶

Your course depends on the kit in three places, and all three follow the same release line:

extend: in myst.yml (the MyST plugin),
@v0.1 in .github/workflows/course.yml (the CI workflows, which also install the matching nma-kit),
the neuromatch-course-kit package you use locally.

@v0.1 and @0.1 mean “the newest 0.1.x”, so compatible fixes arrive on your next build. Pin an exact version (for example @v0.1.3) to freeze a finished course. A new minor version can change the rules, so read the kit’s release notes before moving a course to it.

Where this book fits¶

This book is the manual and the showcase. It is built with the same kit as your course, so every page is a working example you can open in the repository and copy from. The tools themselves live in neuromatch/course-kit.