Skip to content

Commit af02bd3

Browse files
lundybernardlundybernard
committed
fixup: planning
1 parent 4f6f3c4 commit af02bd3

2 files changed

Lines changed: 53 additions & 43 deletions

File tree

‎docs/decisions/0001-myst-migration/0001-migrate-to-mystmd.md‎

Lines changed: 53 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# ADR 0001 — Migrate build system from Hugo to MyST-MD
22

33
Date: 2026-05-11
4-
Status: Proposed
4+
Status: Proposed — **open question for maintainers (see below)**
55
Branch: lb/myst-migration
66
Issue: scientific-python/scientific-python.org#846
77

@@ -11,35 +11,73 @@ Issue: scientific-python/scientific-python.org#846
1111
Netlify (auto-deploy on push to `main`). We want to convert the content files
1212
to MyST syntax.
1313

14-
## Decision
14+
Three realistic MyST toolchain options exist. They are not equivalent:
15+
`jupyter-book` is a higher-level tool built on top of `mystmd`; `mystmd` is the
16+
underlying engine and is available as both a Node package (npm) and a Python
17+
package (pip/conda) that bundles Node internally.
1518

16-
Replace Hugo with **MyST-MD** (`mystmd` CLI, `myst build --html`)
17-
as the single build and deploy tool.
19+
## Decision (proposed)
20+
21+
Replace Hugo with **`mystmd` Python package** (`pip install mystmd`,
22+
`myst build --html`) as the build tool.
1823

1924
## Options considered
2025

21-
| Option | Pros | Cons |
22-
| -------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
23-
| **Stay on Hugo** | Theme parity with sibling SP sites; no content changes needed | Hugo is not Python; MyST content conversion still desirable long-term |
24-
| **jupyter-book** | Python-native; fits SP ecosystem conventions; familiar to SP contributors | Wraps `mystmd` under the hood — adds a layer; less direct than the CLI |
25-
| **MyST-MD** (`mystmd` CLI) | Single tool; native MyST markdown; first-class cards/grids/admonitions; active ExecutableBooks development | Node-based toolchain; theme/footer customisation less mature than Hugo |
26+
| Option | Pros | Cons |
27+
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
28+
| **Stay on Hugo** | Theme parity with sibling SP sites; no content changes needed | Hugo is not Python; MyST content conversion still desirable long-term |
29+
| **jupyter-book 2.x** | Pure Python (`pip install jupyter-book`); SP ecosystem familiar with JB; conda-forge package; handles notebook execution natively | Wraps `mystmd` under the hood — extra abstraction; config format (`_config.yml`, `_toc.yml`) is not portable to plain `myst.yml` if JB is dropped later; JB 2.x released late 2024 — docs and community experience thin; feature lag vs direct `mystmd` |
30+
| **mystmd — Node CLI** (`npm install mystmd`) | Native runtime; latest npm releases immediately; same `myst.yml` config; active ExecutableBooks development | Requires Node.js in every build environment (Netlify, RTD, CI); unfamiliar to Python contributors |
31+
| **mystmd — Python package** (`pip install mystmd`) | Python-centric install (pip/conda-forge); bundles Node internally — no separate Node needed; same `myst.yml` config as Node CLI (no extra abstraction layer); proven by `tools.scientific-python.org` PR #81; works on all considered deploy platforms | Node bundled internally — slightly opaque; PyPI/conda releases may lag npm by 1–7 days |
32+
33+
## Rationale for proposed decision
34+
35+
**Why not jupyter-book:** `learn.scientific-python.org` contains no Jupyter
36+
notebooks; JB's primary value (notebook execution, Sphinx integration) does not
37+
apply here. JB 2.x uses `mystmd` as its build engine, so the team would get
38+
`mystmd` indirectly with an extra config layer on top. The JB config format
39+
(`_config.yml`, `_toc.yml`) is not portable — if JB were dropped later, the
40+
config would need to be rewritten to `myst.yml` from scratch.
41+
42+
**Why not the Node CLI:** Requires Node.js in every build environment. SP
43+
contributors and maintainers work in Python environments; npm is unfamiliar and
44+
adds friction for new contributors. The Python package provides identical
45+
functionality without any Node setup.
46+
47+
**Why the Python package:** Fits SP's Python-centric workflow; `conda install
48+
-c conda-forge mystmd` works for conda users. No Node.js needed in Netlify,
49+
RTD, or GitHub Actions (Node is bundled inside the package). The `myst.yml`
50+
config is identical to the Node CLI — switching delivery method later is a
51+
one-line change.
52+
53+
## Open question for maintainers
54+
55+
> **Which MyST toolchain should `learn.scientific-python.org` adopt?**
56+
>
57+
> A. `mystmd` Python package — proposed above (`pip install mystmd`)
58+
> B. `jupyter-book 2.x` — if the team prefers a unified JB-based approach
59+
> C. `mystmd` Node CLI — if the team prefers the native Node runtime
60+
>
61+
> This is the foundational decision for the migration. All downstream ADRs
62+
> (0002–0007) assume option A. If maintainers choose B, the `myst.yml` /
63+
> `_toc.yml` structure and config format change significantly. Option C
64+
> requires Node.js toolchain setup in `netlify.toml` and CI.
2665
2766
## Installation
2867

29-
`mystmd` is a Node-based tool also available as a Python package
30-
(`pip install mystmd`) that bundles the Node CLI. For Netlify builds,
31-
`pip install mystmd` is the chosen method — simplest path requiring no
32-
additional Node configuration in `netlify.toml`.
68+
For Netlify builds and RTD: `pip install mystmd` (no Node configuration needed
69+
in `netlify.toml`; see ADR 0007).
3370

3471
Local dev: install via any preferred method (pip, conda, npm — developer's
3572
choice). The repo does not mandate a specific local environment.
3673

3774
## Consequences
3875

3976
- `myst build --html` replaces `make html` (Hugo)
77+
- `pip install mystmd` is the chosen delivery method; no Node toolchain required
78+
in CI or `netlify.toml`
4079
- The `scientific-python-hugo-theme` submodule is removed (see ADR 0003)
41-
- `netlify.toml` is updated to use `mystmd`; install via `pip install mystmd`
42-
(see PLAN.md Phase 6)
80+
- `netlify.toml` is updated to use `mystmd` (see PLAN.md Phase 6)
4381
- Nine content files require shortcode conversion (see ADR 0002)
4482
- Footer/quicklinks are not yet supported in MyST default templates (see ADR 0005)
4583
- Other SP repos remain on Hugo until they choose to migrate (see ADR 0006)

‎docs/decisions/0001-myst-migration/REQUIREMENTS.md‎

Lines changed: 0 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -150,34 +150,6 @@ opened, even if the decision is "defer."
150150

151151
---
152152

153-
## Open questions (for maintainer discussion)
154-
155-
All six questions have a proposed answer in the ADR set (`Status: Proposed`).
156-
These are recommendations, not settled decisions — maintainers may accept,
157-
modify, or reject any of them.
158-
159-
1. **Footer/quicklinks** — MyST has no built-in footer config. Do we want a
160-
custom theme, static HTML, or defer?
161-
_Proposed: defer — ADR 0005._
162-
2. **Cookie/Jekyll** — Keep, convert, or defer?
163-
_Proposed: defer; keep `make cookie` working — ADR 0004._
164-
3. **Netlify** — Netlify is the active deploy target. Update `netlify.toml`:
165-
remove Hugo/Dart Sass toolchain setup; add `pip install mystmd`; keep
166-
`make html-all` as the build command.
167-
_Resolved: see ADR 0007._
168-
4. **Preview deploy** — Netlify handles PR previews automatically from
169-
`netlify.toml`. Only the toolchain setup needs to change.
170-
_No open question — updating `netlify.toml` is sufficient._
171-
5. **Other SP repos** — Should this PR include tracking issues for
172-
scientific-python.org, blog, and tools, or is that out of scope?
173-
_Proposed: file tracking issues at end of PR; sibling repos migrate
174-
independently — ADR 0006._
175-
6. **Theme submodule** — When is it safe to remove? Only after all four repos
176-
migrate, or can learn.scientific-python.org remove it independently?
177-
_Proposed: remove in this PR; sibling repos pin their own copies — ADR 0003._
178-
179-
---
180-
181153
## Success criteria
182154

183155
- `myst build --html` produces a complete site with no warnings about missing

0 commit comments

Comments
 (0)