Working with MyST in Neurodesk

Citation and Resources¶

This tutorial adapts material from the official MyST quickstart guides:

• mystmd team. Working with MyST in Jupyter — mystmd.org/guide/quickstart-jupyter-lab-myst

• MyST-Parser docs (the Python/Sphinx flavour Jupyter Book uses) — myst-parser.readthedocs.io

• MyST-NB authoring guide — myst-nb.readthedocs.io

• Admonition reference — myst-parser admonitions

1. Introduction¶

NeurodeskEDU is built with Jupyter Book, which renders notebooks via MyST-Parser — an extended Markdown flavour that adds directives, roles, cross-references, math, admonitions, tabs, cards, and more.

If you’re contributing an example notebook or tutorial here, the same MyST syntax works in plain Markdwon in .ipynb. On Neurodesk, the jupyterlab-myst extension is already enabled and markdown cells render directives like :::{note} immediately.

This tutorial walks through the MyST features available in NeurodeskEDU, with examples flavoured for Neurodesk content.

2. Admonitions¶

Admonitions are coloured callout boxes. They have a directive name (note, tip, warning, important, caution, etc.) that controls the colour and icon. Use :::{name} to open and ::: to close.

2.1 The standard admonition types¶

The renderer ships with ten built-in types. Click through the tabs to see each:

2.2 Custom titles¶

Use :::{admonition} <title> for an arbitrary title, and add :class: <type> to keep one of the standard styles:

This admonition combines a custom title with a definition list — the pattern of a term on one line followed by : definition on the next, enabled by the deflist extension.

2.3 Collapsible admonitions¶

Add :class: dropdown to any admonition to make it collapsible. Useful for long content that would otherwise crowd the page:

2.4 Nested admonitions¶

You can nest one admonition inside another by using more colons on the outer block:

The outer block uses :::: (four colons), the inner uses ::: (three). The rule: any nested directive needs fewer colons than its parent.

3. Tables, figures, and code blocks¶

3.1 Tables¶

Use the list-table directive for tables that need a name (so you can cross-reference them) or alignment options:

For quick simple tables, GitHub-style pipe tables also work:

3.2 Figures¶

The figure directive supports captions, labels, and sizing:

Common figure options:

• :name: — label for cross-referencing

• :alt: — alt text for accessibility

• :width: — 300px, 50%, etc.

• :height: — pixels

• :align: — left, center, right

• :figwidth: — width of the entire figure block (caption included)

3.3 Code blocks¶

Plain fenced code blocks render with syntax highlighting:

Bash:

module load fsl/6.0.7.18
flirt -ref $FSLDIR/data/standard/MNI152_T1_2mm_brain \
      -in subject_T1.nii.gz \
      -out subject_in_mni.nii.gz \
      -dof 12

Or Python:

import module
await module.load('fsl/6.0.7.18')
await module.list()

For more control (line numbers, emphasising specific lines, captions), use the code-block directive:

#!/bin/bash
#SBATCH --job-name=preproc
#SBATCH --time=01:00:00
#SBATCH --cpus-per-task=4

module load fsl/6.0.7.18
papermill preproc.ipynb out.ipynb --parameters_raw subject_id 02

3.4 Task lists¶

The tasklist extension turns GitHub-style checkbox lists into rendered task lists — useful for tutorial steps, todo prompts, or progress overviews:

• Load the FSL module

• Run brain extraction

• Register T1 to MNI152

• Generate QC overlay

The static build doesn’t allow toggling them.

3.5 Interactive widgets¶

Notebooks can include ipywidgets for interactive controls — sliders, dropdowns, file pickers, viewers (ipyniivue), and more — and they render in JupyterLab as live components. Here’s a minimal slider:

The variable n bound to the slider can be referenced inside markdown via jupyterlab-myst’s {eval} role. The value below reflects the kernel’s current state at cell-render time — re-execute the cell to refresh after sliding:

4. Math and equations¶

The dollarmath extension is enabled in this book, so LaTeX-style math works with single dollars (inline) and double dollars (block):

• Inline ($...$) — sits inside a sentence at text size. Example: $T_2^*$ renders as $T_2^*$.

• Block — wrap on its own lines with $$...$$. Add (label) after the closing $$ to make the equation cross-referenceable.
  Example with a label:

Now [](#bold-signal) or (1) becomes a link to this equation.

For multi-line equations, use the math directive. This example shows the cost function for sum-of-squared-differences image registration:

4.1 Inline math via Python¶

The IPython display module lets you render LaTeX from a code cell:

5. Cross-references¶

Once a figure, table, equation, or section has a :name: (or label), you can link to it from anywhere in the same book.

5.1 The simple [](#label) syntax¶

Modern MyST-Parser supports [](#label) as the most concise form. Empty link text means the renderer auto-fills it from the target’s caption or label:

• [](#neurodesk-logo) → Figure 1

• [](#modules-table) → Table 1

• [](#bold-signal) → (1)

• [](#registration-cost) → (2)

You can also override the link text: [the Neurodesk logo](#neurodesk-logo) → the Neurodesk logo.

5.2 The explicit role syntax¶

Sphinx-style roles also work and let you control numbering format:

Example: see Table 1 for the modules list, equation (1) for the $T_2^*$-weighted signal equation.

6. Tabs, cards, and grids¶

These come from the sphinx-design extension (already available in Jupyter Book) and let you build richer, screen-responsive layouts.

6.1 Tabs¶

Tabs group related variants of the same content (e.g. instructions for different tools). The same tab-set directive used in §2.1 above also works as a standalone container:

6.2 Cards¶

Cards are bordered, optionally clickable boxes — useful for navigation or feature-highlight blocks:

6.3 Grids¶

Grids arrange multiple cards in a responsive layout:

The four numbers after :::::{grid} set how many columns to show at four screen sizes (small to extra-large). Examples:

• 1 1 1 1 → 1 column at all sizes → 4 stacked rows

• 1 1 2 2 → 2 columns on bigger screens → 2 rows of 2 (used above)

• 1 2 3 4 → more columns the wider the screen → 1 row of 4 on desktop

7. Reference: MyST configuration in this book¶

NeurodeskEDU uses Jupyter Book 2 and the MyST Document Engine. Website options live in books/myst.yml. The build script generates the table of contents from the source directories.

MyST supports math, colon-fenced directives, definition lists, task lists, admonitions, figures, tables, tabs, cards, and cross-references. These no longer require Sphinx extension flags.

For syntax and configuration, see the MyST guide. For custom directives and transforms, see MyST plugins. Sphinx extensions and _config.yml settings do not apply to Jupyter Book 2.

Where to go from here¶

• The MyST-Parser docs are the most thorough reference: myst-parser.readthedocs.io

• The Jupyter Book guide covers book-level configuration: jupyterbook.org

• Browse the existing notebooks in books/examples/ and books/tutorials/ for live patterns you can copy.

• If you don’t work on Neurodesk and you need to enable MyST renderer:

  In JupyterLab, click the Settings ⚙️ → Settings Editor → Document Manager → set Default Viewer for markdown to MyST. Or just install/enable the jupyterlab-myst extension.

Happy authoring! 🧠

Dependencies in Jupyter/Python¶

• Using the package watermark to document system environment and software versions used in this notebook, alongside the Neurodesktop version extracted from the JUPYTER_IMAGE or NEURODESKTOP_VERSION environment variables.