Contributing¶

One of the wonderful aspects of both the neuroimaging and Python scientific computing communities is the strong commitment to developing and sharing knowledge and tools within the broader community. The goal of the dartbrains project is to build on this work and provide a resource for people to learn about how to analyze neuroimaging data. We try to incorporate as much open content as we can find that contributes to this goal. Please let us know if we have inadvertently omitted credit for any content generated by others. Though this project is based on a neuroimaging analysis course taught at Dartmouth College, we welcome contributions from anyone in the broader imaging community.

Getting Started¶

The DartBrains project is hosted on GitHub. If you have any questions, comments, or suggestions, please open an issue. If you notice any mistakes or have an idea for new content, please either open an issue or submit a pull request for us to review.

How the website is built¶

DartBrains is built with marimo-book, a static-site generator that turns a directory of marimo notebooks (.py files) and Markdown pages into a polished documentation site on top of Material for MkDocs. Every chapter is either:

A marimo notebook (content/<Chapter>.py) authored interactively with marimo edit, or
A Markdown page (content/<Page>.md) for prose-only content.

The table of contents, theme, launch buttons, and per-chapter render mode all live in book.yml at the repo root.

Editing a chapter locally¶

# 1. Clone and install the dev environment (one-time setup)
git clone https://github.com/ljchang/dartbrains.git
cd dartbrains
uv sync

# 2. Edit a marimo notebook interactively
uv run marimo edit content/GLM.py

# 3. Preview the whole book with live reload
uv run marimo-book serve
# → open http://127.0.0.1:8000/

# 4. One-shot build (what CI runs)
uv run marimo-book build

When marimo-book serve won't pick up changes after a CSS or book.yml edit, kill and restart it — the in-memory mkdocs cache only invalidates on content file changes.

Adding a new chapter¶

Drop a content/<Chapter>.py (marimo) or content/<Chapter>.md (Markdown) into the content/ directory.
Add an entry under the appropriate toc: section in book.yml:

- file: content/My_New_Chapter.py
  title: My Optional Display Title   # falls back to the first `# Heading` in the file

Run uv run marimo-book serve and check the page renders correctly.
Open a pull request against the v2-marimo-migration branch.

Render modes¶

Most chapters render statically — cells are executed at build time and the outputs are baked into the page (fast, no Python in the browser). For chapters that need full interactive reactivity (sliders driving downstream Python compute), opt into WASM mode per chapter:

- file: content/My_Interactive_Chapter.py
  mode: wasm     # ships marimo's runtime + Pyodide; ~30 MB first paint

For lightweight reactivity (discrete sliders / dropdowns where every value's output can be precomputed at build time), the book-wide precompute.enabled: true flag in book.yml handles it automatically — no per-chapter opt-in needed. See the marimo-book docs for the full set of options.

License for this book¶

All content in this book (i.e., any files and content in the content/ folder) is licensed under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.