Notebook export: contribute to mystmd PR #1882 (myst build --ipynb)

[mmcky]

Summary

jupyter-book/mystmd#1882 adds native myst build --ipynb support via a new myst-to-ipynb package. This is the correct path forward for building downloadable notebooks from MyST source files. The PR is in Draft status and needs contributions to be production-ready.

QuantEcon is cc'd on this PR (mmcky commented), kp992 has contributed tests via #1915, and we need this for lecture-python-programming.myst (QuantEcon/lecture-python-programming.myst#345).

PR #1882 Status

PR	jupyter-book/mystmd#1882 — "Add ipynb as export format"
Status	Draft (not merged)
Branch	myst-to-ipynb on jupyter-book/mystmd
Authors	rowanc1 (initial), kp992 (tests), agoose77 (review)
Changes	+871 −5 across 21 files
TODO	"Fix redundant +++ markers in Markdown cells"

Bugs Found in PR

#	Issue	Location
1	frontmatter parameter accepted but never used — should populate metadata.kernelspec and metadata.language_info	myst-to-ipynb/src/index.ts
2	Language hardcoded to 'python' — should derive from frontmatter kernelspec	myst-to-ipynb/src/index.ts
3	Log message says "Exported MD" instead of "Exported IPYNB"	myst-cli/src/build/ipynb/index.ts
4	Redundant +++ markers leak into markdown cells (stated TODO)	myst-to-md interaction
5	package.json homepage URL points to myst-to-md not myst-to-ipynb	myst-to-ipynb/package.json

Missing Functionality

#	Gap	Priority
1	No cell metadata — tags like hide-input, hide-output, remove-cell are lost	High
2	No output preservation — outputs: [] always empty; executed notebook outputs are discarded	High
3	No kernel metadata from frontmatter — kernelspec not populated from page/project config	Medium
4	~20+ test cases commented out in basic.yml (thematic break, blockquote, lists, link, image reference, code variants, etc.)	Medium
5	No multi-article/book export — only single-page export	Low

Critical Issue: MyST-Flavored Markdown in Notebook Cells

myst-to-ipynb delegates markdown cell generation to myst-to-md, which outputs MyST directive syntax, not plain CommonMark:

Content	Output in notebook	Plain equivalent
Admonition	:::{note}\ntext\n:::	> **Note:** text
Figure	:::{figure} path\n:::	
Math block	```{math}\nE=mc^2\n```	$$E=mc^2$$
Tabs, cards, grids	:::{tab-set}\n::: etc.	No equivalent

This means users need jupyterlab-myst installed to render the notebooks properly. jupyterlab-myst is not bundled by default in JupyterLab. Google Colab does not support it at all.

Options

• Option A: Accept MyST in notebooks, require jupyterlab-myst — simplest, unblocks pipeline
• Option B: Contribute a --plain-markdown flag to myst-to-ipynb — needed for Colab compatibility
• Option C: Post-process ipynb output with a script to simplify markdown cells

Recommendation: Start with Option A to unblock, then pursue Option B upstream for Colab compatibility.

Recommended Contributions

1. Fix frontmatter → kernelspec metadata mapping (bugs Links in Python lectures need to be checked #1 & Possible renaming of three Python lecture series #2)
2. Fix log message (bug Review indices of P #3) — trivial one-line fix
3. Uncomment and fix test cases in basic.yml — need these working for production use
4. Add cell metadata passthrough — map block metadata (tags, etc.) to cell metadata, essential for hide-input / remove-cell patterns
5. Investigate +++ marker issue (bug [Lectures] Remove titles from Index due to addition of index role #4)
6. Test with real QuantEcon lecture content — build the branch locally against lecture-python-programming.myst

CI Pipeline (once PR merges)

steps:
  - run: npm install -g mystmd
  - run: myst build --ipynb          # Build .ipynb from MyST sources
  - run: myst build --typst          # Per-page PDFs (Typst for speed)
  - run: myst build --pdf            # Whole-book PDF (LaTeX)
  - run: myst build --html           # Website with all exports as downloads

Until PR #1882 merges, use a custom build of mystmd from the myst-to-ipynb branch.

Related

• Theme issue: Download button needs to support built ipynb files and window.print() fallback — tracked in quantecon-theme-src review
• QuantEcon/quantecon-theme-src#26 — BinderHub launch support