fixup! docs/decisions

Author: lundybernard

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

@@ -1,10 +1,8 @@
 # ADR 0001 — Migrate build system from Hugo to MyST-MD
 
 Date: 2026-05-11
-Accepted: 2026-05-18
 Status: Accepted
 Branch: lb/myst-migration
-Issue: scientific-python/scientific-python.org#846
 
 ## Context
 
@@ -22,16 +20,43 @@ package (pip/conda) that bundles Node internally.
 Replace Hugo with **`mystmd` Python package** (`pip install mystmd`,
 `myst build --html`) as the build tool.
 
-## Options considered
+- Python-centric install (pip/conda-forge) [pro]
+- Bundles Node internally — no separate Node needed [pro]
+- Same `myst.yml` config as Node CLI (no extra abstraction layer) [pro]
+- Proven by `tools.scientific-python.org` PR #81 [pro]
+- Works on all considered deploy platforms [pro]
+- Node bundled internally — slightly opaque [con]
+- PyPI/conda releases may lag npm by 1–7 days [con]
 
-| Option                                             | Pros                                                                                                                                                                                                                                                   | Cons                                                                                                                                                                                                                                                    |
-| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Stay on Hugo**                                   | Theme parity with sibling SP sites; no content changes needed                                                                                                                                                                                          | Hugo is not Python; MyST content conversion still desirable long-term                                                                                                                                                                                   |
-| **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` |
-| **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                                                                                                                                                       |
-| **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                                                                                                                                                                  |
+## Other options considered
 
-## Rationale for proposed decision
+### Stay on Hugo
+
+- Theme parity with sibling SP sites [pro]
+- No content changes needed [pro]
+- Hugo is not Python [con]
+- MyST content conversion still desirable long-term [con]
+
+### jupyter-book 2.x
+
+- Pure Python (`pip install jupyter-book`) [pro]
+- SP ecosystem familiar with JB; conda-forge package [pro]
+- Handles notebook execution natively [pro]
+- Wraps `mystmd` under the hood — extra abstraction [con]
+- Config format (`_config.yml`, `_toc.yml`) is not portable to plain
+  `myst.yml` if JB is dropped later [con]
+- JB 2.x released late 2024 — docs and community experience thin [con]
+- Feature lag vs direct `mystmd` [con]
+
+### mystmd — Node CLI (`npm install mystmd`)
+
+- Native runtime; latest npm releases immediately [pro]
+- Same `myst.yml` config [pro]
+- Active ExecutableBooks development [pro]
+- Requires Node.js in every build environment (Netlify, RTD, CI) [con]
+- Unfamiliar to Python contributors [con]
+
+## Rationale
 
 **Why not jupyter-book:** `learn.scientific-python.org` contains no Jupyter
 notebooks; JB's primary value (notebook execution, Sphinx integration) does not
@@ -54,7 +79,7 @@ one-line change.
 ## Installation
 
 For Netlify builds and RTD: `pip install mystmd` (no Node configuration needed
-in `netlify.toml`; see ADR 0007).
+in `netlify.toml`; see ADR 0006).
 
 Local dev: install via any preferred method (pip, conda, npm — developer's
 choice). The repo does not mandate a specific local environment.
@@ -65,7 +90,8 @@ choice). The repo does not mandate a specific local environment.
 - `pip install mystmd` is the chosen delivery method; no Node toolchain required
   in CI or `netlify.toml`
 - The `scientific-python-hugo-theme` submodule is removed (see ADR 0003)
-- `netlify.toml` is updated to use `mystmd` (see PLAN.md Phase 6)
+- `netlify.toml` is updated to use `mystmd` (see ADR 0006)
 - Nine content files require shortcode conversion (see ADR 0002)
-- Footer/quicklinks are not yet supported in MyST default templates (see ADR 0005)
-- Other SP repos remain on Hugo until they choose to migrate (see ADR 0006)
+- Footer/quicklinks come from the shared `scientific-python-myst-theme`
+  (see ADR 0007)
+- Other SP repos remain on Hugo until they choose to migrate (see ADR 0005)

docs/decisions/0001-myst-migration/0002-shortcode-mapping.md

@@ -1,22 +1,32 @@
 # ADR 0002 — Hugo shortcode → MyST directive mapping
 
 Date: 2026-05-11
-Status: Proposed
+Status: Accepted
 Branch: lb/myst-migration
 
 ## Context
 
-Nine content files use Hugo shortcodes that MyST does not understand:
+Nine content files use Hugo shortcodes that MyST does not understand
+(pre-Phase-2 names):
 
-| Shortcode type              | Files affected (pre-Phase-2 names)                                                                                                                                                                               |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `{{< grid >}}` / `[[item]]` | `_index.md` (root), `contributors/_index.md`, `documentation/_index.md`                                                                                                                                          |
-| `{{< admonition >}}`        | `maintainers/_index.md`, `maintainers/interacting-with-new-contributors.md`, `maintainers/managing-conflict.md`, `maintainers/meeting_types.md`, `contributors/first-contribution.md`, `community/onboarding.md` |
+`{{< grid >}}` / `[[item]]`
+
+- `_index.md` (root)
+- `contributors/_index.md`
+- `documentation/_index.md`
+
+`{{< admonition >}}`
+
+- `maintainers/_index.md`
+- `maintainers/interacting-with-new-contributors.md`
+- `maintainers/managing-conflict.md`
+- `maintainers/meeting_types.md`
+- `contributors/first-contribution.md`
+- `community/onboarding.md`
 
 ## Decision
 
-Convert shortcodes in two **type-batched commits** (one per shortcode type,
-not one per file), using the following canonical mappings:
+Convert shortcodes, using the following canonical mappings:
 
 ```
 {{< grid columns="1 2 2 3" >}}   →   ::::{grid} 1 2 2 3
@@ -38,18 +48,13 @@ not one per file), using the following canonical mappings:
                                        :::
 ```
 
-## Options considered
+## Other options considered
 
 - **Custom MyST plugin** to interpret Hugo TOML shortcode syntax — high effort,
   no value once content is converted.
-- **Per-file commits** — nine files but ten shortcode occurrences (one file
-  has two grid blocks); reviewers re-read the same mapping repeatedly.
-- **Type-batched commits** — two diffs total; reviewers evaluate the mapping
-  pattern once per type.
 
 ## Consequences
 
-- Two commits in Phase 3 of the migration (see [PLAN.md](PLAN.md))
 - Reviewers can verify correctness by comparing rendered output against the
   Hugo-built site for these nine pages
 - `grep -rE '\{\{<' content/` returns zero matches after these commits

docs/decisions/0001-myst-migration/0003-remove-hugo-theme-submodule.md

@@ -1,7 +1,7 @@
 # ADR 0003 — Remove scientific-python-hugo-theme submodule
 
 Date: 2026-05-11
-Status: Proposed
+Status: Accepted
 Branch: lb/myst-migration
 
 ## Context
@@ -17,20 +17,19 @@ submodule has no consumer here.
 
 ## Decision
 
-Remove the submodule from this repo in Phase 7 of the migration.
+Remove the submodule from this repo.
 
 ```bash
 git submodule deinit -f themes/scientific-python-hugo-theme
 git rm themes/scientific-python-hugo-theme
 rm -rf .git/modules/themes/scientific-python-hugo-theme
 ```
 
-## Options considered
+## Other options considered
 
-1. **Remove in this PR** — clean cut; no dead code after Hugo is gone.
-2. **Keep until all four SP repos migrate** — delays cleanup by months or
-   quarters; leaves a submodule that nothing in this repo uses.
-3. **Vendor a snapshot** — no benefit; MyST doesn't use it.
+- **Keep until all four SP repos migrate** — delays cleanup by months or
+  quarters; leaves a submodule that nothing in this repo uses.
+- **Vendor a snapshot** — no benefit; MyST doesn't use it.
 
 ## Consequences
 
@@ -39,4 +38,4 @@ rm -rf .git/modules/themes/scientific-python-hugo-theme
   from their own `.gitmodules` and pin their own SHA
 - The upstream `scientific-python-hugo-theme` repo is not affected
 - A follow-up PR to the sibling repos removes their copies when they migrate
-  (see ADR 0006)
+  (see ADR 0005)

docs/decisions/0001-myst-migration/0004-consume-cookie-myst-build.md

@@ -1,7 +1,7 @@
 # ADR 0004 — Consume the cookie MyST build
 
 Date: 2026-05-11
-Status: Proposed
+Status: Accepted
 Branch: lb/myst-migration
 
 ## Context
@@ -29,21 +29,18 @@ How `learn` invokes cookie's build — which `mystmd` version, installed how —
 a separate concern, deliberately out of scope here so that this decision stays
 stable if the build tooling changes.
 
-## Options considered
-
-1. **Consume cookie's MyST build** — chosen. Cookie owns its build; `learn`
-   consumes the output. No duplicated build logic, no fork, and cookie's
-   independent release cadence is preserved.
-2. **Vendor cookie's content into `learn`** — would collapse the two sites into
-   a single build, removing the submodule and the two-step overlay. Discards
-   cookie's independent release cadence and its own contributor base, and makes
-   `learn` responsible for content it does not own. Rejected.
-3. **Reimplement cookie's build inside `learn`** — drive `mystmd` against
-   cookie's sources directly rather than calling its build script. Duplicates
-   logic cookie already maintains and silently drifts whenever cookie changes
-   its build. Rejected.
-4. **Drop cookie** — would break the `/development/` path; not acceptable
-   without a replacement.
+## Other options considered
+
+- **Vendor cookie's content into `learn`** — would collapse the two sites into
+  a single build, removing the submodule and the two-step overlay. Discards
+  cookie's independent release cadence and its own contributor base, and makes
+  `learn` responsible for content it does not own. Rejected.
+- **Reimplement cookie's build inside `learn`** — drive `mystmd` against
+  cookie's sources directly rather than calling its build script. Duplicates
+  logic cookie already maintains and silently drifts whenever cookie changes
+  its build. Rejected.
+- **Drop cookie** — would break the `/development/` path; not acceptable
+  without a replacement.
 
 ## Consequences
 

docs/decisions/0001-myst-migration/0005-defer-footer-quicklinks.md

@@ -1,20 +1,18 @@
-# ADR 0006 — Sibling SP repos migrate independently
+# ADR 0005 — Sibling SP repos migrate independently
 
 Date: 2026-05-11
-Status: Proposed
+Status: Accepted
 Branch: lb/myst-migration
 
 ## Context
 
 The Scientific Python ecosystem has four Hugo-based sites sharing the same
 theme submodule:
 
-| Repo                                            | Domain                                      |
-| ----------------------------------------------- | ------------------------------------------- |
-| `scientific-python/learn.scientific-python.org` | learn.scientific-python.org ← **this repo** |
-| `scientific-python/scientific-python.org`       | scientific-python.org                       |
-| `scientific-python/blog.scientific-python.org`  | blog.scientific-python.org                  |
-| `scientific-python/tools.scientific-python.org` | tools.scientific-python.org                 |
+- learn.scientific-python.org
+- scientific-python.org
+- blog.scientific-python.org
+- tools.scientific-python.org
 
 Cross-site nav links are plain absolute URLs (not build-time references).
 There is no shared build pipeline coupling the repos.
@@ -23,22 +21,21 @@ There is no shared build pipeline coupling the repos.
 ([#81](https://github.com/scientific-python/tools.scientific-python.org/pull/81),
 brianhawthorne, opened October 2025, stale as of May 2026). It demonstrates
 a working shortcode conversion and a footer implementation using
-`site.parts.footer:` + custom CSS (see ADR 0005 option 3).
+`site.parts.footer:` + custom CSS.
 
 ## Decision
 
 `learn` migrates first. File one tracking issue per sibling repo after this
 PR merges, each linking to this PR as a worked example. Sibling repos adopt
 MyST on their own schedule.
 
-## Options considered
+## Other options considered
 
-1. **Migrate all four in lock-step** — synchronizes visual consistency; blocks
-   `learn` on the slowest-moving repo.
-2. **`learn` first; siblings when ready** — proves the pattern; doesn't block
-   SciPy 2026 deadline.
-3. **Wait for MyST theme parity** — defers everything until ADR 0005 follow-up
-   is resolved; not necessary since content parity is achievable now.
+- **Migrate all four in lock-step** — synchronizes visual consistency; blocks
+  `learn` on the slowest-moving repo.
+- **Wait for MyST theme parity** — defers everything until full footer parity
+  lands in the shared theme (ADR 0007); not necessary since content parity is
+  achievable now.
 
 ## Consequences
 

…migration/0006-sibling-repo-migration.md …migration/0005-sibling-repo-migration.mddocs/decisions/0001-myst-migration/0006-sibling-repo-migration.md renamed to docs/decisions/0001-myst-migration/0005-sibling-repo-migration.md docs/decisions/0001-myst-migration/0006-sibling-repo-migration.md renamed to docs/decisions/0001-myst-migration/0005-sibling-repo-migration.md

@@ -0,0 +1,59 @@
+# ADR 0006 — Update netlify.toml for MyST build
+
+Date: 2026-05-11
+Status: Accepted
+Branch: lb/myst-migration
+
+## Context
+
+Both `scientific-python.org` and `learn.scientific-python.org` deploy via
+Netlify, which auto-deploys on push to `main` and generates PR preview deploys.
+The build command is defined in `netlify.toml`. The current command builds with
+Hugo + Dart Sass.
+
+GitHub Actions runs only a lint workflow (`lint.yml`). There is no gh-pages
+deploy workflow.
+
+## Decision
+
+Update `netlify.toml` in Phase 6 of the migration: remove the Dart Sass and
+Hugo toolchain setup; add `pip install mystmd` before the existing
+`make html-all` call. Build command, publish directory, and
+`netlify-plugin-checklinks` are otherwise unchanged.
+
+## Other options considered
+
+- **Replace Netlify with gh-pages** — larger change; requires creating new
+  GitHub Actions deploy workflows, reconfiguring DNS, and losing Netlify PR
+  previews. Out of scope for this PR.
+- **Keep `netlify.toml` for the checklinks plugin only** — the Netlify
+  checklinks plugin can be replaced by a `lychee`-based GitHub Actions job
+  as a separate improvement; not required for this migration.
+- **Drop Netlify entirely; use CircleCI for builds + circleci-artifacts-
+  redirector-action for PR previews** — demonstrated by
+  `tools.scientific-python.org` PR #81. Viable but introduces CircleCI
+  account dependency and is a larger infrastructure change than needed here.
+- **Migrate to Read the Docs** — RTD has first-class MyST/Sphinx support,
+  built-in PR preview deploys (including for forks), and is already used
+  widely across the Scientific Python ecosystem. Would replace Netlify
+  entirely; requires a `.readthedocs.yaml` config and DNS reconfiguration.
+  Resolves the fork-contributor preview gap (see Future work below)
+  as a side effect. Not pursued in this PR — custom domain setup and RTD
+  account provisioning are out of scope for the migration itself.
+
+## Consequences
+
+- Dart Sass and Hugo version pins removed from `netlify.toml`
+- `pip install mystmd` added before `make html-all` in the build command
+- Build command (`make html-all`), publish dir (`public/`), and
+  `netlify-plugin-checklinks` are unchanged
+- Netlify auto-deploy and PR previews continue unchanged
+
+## Future work (out of scope)
+
+Two follow-up improvements; both filed as issues before this PR merges:
+
+- **gh-pages PR preview**: allows contributors working from a fork to
+  preview builds on their own GitHub Pages without requiring Netlify access.
+- **Replace `netlify-plugin-checklinks` with a `lychee`-based GitHub Actions
+  job**: keeps link checking in CI, removes the Netlify plugin dependency.