Skip to content

Swap docs toolchain from MyST to Quarto#304

Merged
MaxGhenis merged 2 commits intomainfrom
docs-quarto-toolchain
Apr 20, 2026
Merged

Swap docs toolchain from MyST to Quarto#304
MaxGhenis merged 2 commits intomainfrom
docs-quarto-toolchain

Conversation

@MaxGhenis
Copy link
Copy Markdown
Contributor

Part 1 of 3 (A: toolchain swap → B: graph + generator → C: docs rewrite) per PR #301's review feedback.

Scope

Swap the docs toolchain from MyST to Quarto. No content changes — all 11 existing .md pages render under Quarto unchanged.

Changes

  • docs/myst.ymldocs/_quarto.yml with the same navigation, grouped into collapsible sidebar sections.
  • docs/examples.md — convert the 8 {literalinclude} directives to Quarto's {.python include="..."} (the only MyST-specific construct in the current tree).
  • Makefilemake docsquarto render docs; make docs-servequarto preview docs.
  • .github/workflows/pr_docs_changes.yaml — install Quarto via the official quarto-dev/quarto-actions/setup@v2 action.
  • docs/.gitignore — track _site / _freeze / .quarto / .quarto_ipynb.

Timing

Local quarto render docs takes 4 seconds for all 11 pages on an M-series laptop (cold Quarto, no cache). CI first-run overhead from the Quarto binary install is ~30 seconds before the action's cache kicks in; overall PR-docs job stays under a minute.

Per earlier review feedback this is acceptable — within a factor of 2 of the MyST time, trading ~15 seconds of CI job time for the multi-output capability Quarto brings.

Why Quarto

  • One source, two outputs (HTML site + PDF) — matters once the methodology paper lands as a chapter of the same tree.
  • Computational blocks execute live Python against the installed package during build, so tutorials stay in sync with releases rather than going stale.
  • Native journal templates, BibTeX citations, cross-references, Observable cells.
  • The main Jupyter Book / MyST maintainer moved to Quarto; JB2's development pace has slowed.

Test plan

  • quarto render docs succeeds locally (11/11 pages)
  • All {literalinclude}{.python include=} conversions produce identical rendered output
  • CI passes

Follow-up PRs

Mechanical swap; no content changes to the 11 .md pages.

- Replace docs/myst.yml with docs/_quarto.yml (same navigation order,
  sidebar grouped under collapsed sections).
- Convert the 8 {literalinclude} directives in docs/examples.md to
  Quarto's {.python include="..."} syntax (the only MyST-specific
  construct in the existing docs).
- Makefile: make docs -> quarto render docs; make docs-serve ->
  quarto preview docs. Drop the mystmd version pin and wrapper.
- CI: install Quarto via quarto-dev/quarto-actions/setup@v2 instead of
  fetching mystmd at job start.
- docs/.gitignore: track _site / _freeze / .quarto / .quarto_ipynb
  instead of _build.

Local render time: 4 seconds for all 11 pages (cold Quarto, 4.6 GHz
M-series). CI first-run overhead from the Quarto binary install is
~30 s (action caches after); overall PR-docs job still under a minute.

Why Quarto:
- One source, two outputs (HTML site + PDF) - matters when the
  methodology paper lands as a chapter of the same tree.
- Computational blocks execute live Python against the installed
  package during build, so tutorials stay in sync with releases.
- Native journal templates, citations via .bib, cross-references.
- The main Jupyter Book / MyST maintainer moved to Quarto; JB2's
  development pace has slowed.
@MaxGhenis MaxGhenis merged commit eca3179 into main Apr 20, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant