Skip to content

Commit 0d88985

Browse files
pre-commit-ci[bot]pre-commit-ci[bot]
committed
[pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
1 parent ad2483e commit 0d88985

11 files changed

Lines changed: 87 additions & 80 deletions

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

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

3-
Date: 2026-05-11
4-
Status: Proposed
5-
Branch: lb/myst-migration
3+
Date: 2026-05-11
4+
Status: Proposed
5+
Branch: lb/myst-migration
66
Issue: scientific-python/scientific-python.org#846
77

88
## Context
99

1010
`learn.scientific-python.org` builds with Hugo via `make html` and deploys via
11-
Netlify (auto-deploy on push to `main`). We want to convert the content files
11+
Netlify (auto-deploy on push to `main`). We want to convert the content files
1212
to MyST syntax.
1313

1414
## Decision
1515

16-
Replace Hugo with **MyST-MD** (`mystmd` CLI, `myst build --html`)
16+
Replace Hugo with **MyST-MD** (`mystmd` CLI, `myst build --html`)
1717
as the single build and deploy tool.
1818

1919
## Options considered
2020

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 |
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 |
2525
| **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 |
2626

2727
## Installation

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
# ADR 0002 — Hugo shortcode → MyST directive mapping
22

3-
Date: 2026-05-11
4-
Status: Proposed
3+
Date: 2026-05-11
4+
Status: Proposed
55
Branch: lb/myst-migration
66

77
## Context
88

99
Nine content files use Hugo shortcodes that MyST does not understand:
1010

11-
| Shortcode type | Files affected (pre-Phase-2 names) |
12-
|---------------|----------------|
13-
| `{{< grid >}}` / `[[item]]` | `_index.md` (root), `contributors/_index.md`, `documentation/_index.md` |
14-
| `{{< 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` |
11+
| Shortcode type | Files affected (pre-Phase-2 names) |
12+
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13+
| `{{< grid >}}` / `[[item]]` | `_index.md` (root), `contributors/_index.md`, `documentation/_index.md` |
14+
| `{{< 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` |
1515

1616
## Decision
1717

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# ADR 0003 — Remove scientific-python-hugo-theme submodule
22

3-
Date: 2026-05-11
4-
Status: Proposed
3+
Date: 2026-05-11
4+
Status: Proposed
55
Branch: lb/myst-migration
66

77
## Context

‎docs/decisions/0001-myst-migration/0004-defer-cookie-jekyll.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# ADR 0004 — Defer migration of external-content/cookie (Jekyll)
22

3-
Date: 2026-05-11
4-
Status: Proposed
3+
Date: 2026-05-11
4+
Status: Proposed
55
Branch: lb/myst-migration
66

77
## Context
@@ -14,7 +14,7 @@ release cadence and contributors independent of `learn`.
1414
## Decision
1515

1616
Leave `external-content/cookie` unchanged in this PR. File a follow-up issue:
17-
*"MyST: migrate external-content/cookie off Jekyll"*.
17+
_"MyST: migrate external-content/cookie off Jekyll"_.
1818

1919
The `make cookie`, `make external`, `cookie_ruby_deps`, `cookie_web_prepare`,
2020
and `prepare` Makefile targets are preserved. `make html-all` continues to

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# ADR 0005 — Defer footer and quicklinks to follow-up
22

3-
Date: 2026-05-11
4-
Status: Proposed
3+
Date: 2026-05-11
4+
Status: Proposed
55
Branch: lb/myst-migration
66

77
## Context
@@ -19,7 +19,7 @@ social links or quicklinks.
1919
## Decision
2020

2121
Ship this PR with the MyST default footer. File a follow-up issue:
22-
*"MyST: footer + quicklinks parity with Hugo theme"*.
22+
_"MyST: footer + quicklinks parity with Hugo theme"_.
2323

2424
Add a comment block at the bottom of `myst.yml` pointing at the follow-up
2525
issue number so the gap is immediately discoverable.

‎docs/decisions/0001-myst-migration/0006-sibling-repo-migration.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
# ADR 0006 — Sibling SP repos migrate independently
22

3-
Date: 2026-05-11
4-
Status: Proposed
3+
Date: 2026-05-11
4+
Status: Proposed
55
Branch: lb/myst-migration
66

77
## Context
88

99
The Scientific Python ecosystem has four Hugo-based sites sharing the same
1010
theme submodule:
1111

12-
| Repo | Domain |
13-
|------|--------|
12+
| Repo | Domain |
13+
| ----------------------------------------------- | ------------------------------------------- |
1414
| `scientific-python/learn.scientific-python.org` | learn.scientific-python.org ← **this repo** |
15-
| `scientific-python/scientific-python.org` | scientific-python.org |
16-
| `scientific-python/blog.scientific-python.org` | blog.scientific-python.org |
17-
| `scientific-python/tools.scientific-python.org` | tools.scientific-python.org |
15+
| `scientific-python/scientific-python.org` | scientific-python.org |
16+
| `scientific-python/blog.scientific-python.org` | blog.scientific-python.org |
17+
| `scientific-python/tools.scientific-python.org` | tools.scientific-python.org |
1818

1919
Cross-site nav links are plain absolute URLs (not build-time references).
2020
There is no shared build pipeline coupling the repos.

‎docs/decisions/0001-myst-migration/0007-deploy-strategy.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# ADR 0007 — Update netlify.toml for MyST build
22

3-
Date: 2026-05-11
4-
Status: Proposed
3+
Date: 2026-05-11
4+
Status: Proposed
55
Branch: lb/myst-migration
66

77
## Context

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

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -52,14 +52,14 @@ production code. Output of this phase is the full planning record in
5252

5353
### Recommended answers to the six open questions
5454

55-
| # | Question | Recommendation | One-line rationale |
56-
|---|----------|---------------|--------------------|
57-
| 1 | Footer / quicklinks | **Defer**: file follow-up issue, ship MyST default footer | Custom MyST theme work blocks the migration; visual parity is not a SciPy 2026 must-have. |
58-
| 2 | Cookie / Jekyll | **Defer**: keep the submodule and `make cookie` target unchanged in this PR | External content lives at `/development/`; touching Jekyll doubles the PR scope. |
59-
| 3 | Netlify | **Update `netlify.toml`**: remove Hugo/Dart Sass toolchain setup; add `pip install mystmd`; keep `make html-all` as build command | Netlify is the active deploy target for the live site and PR previews. Minimal change; see ADR 0007. |
60-
| 4 | Preview deploy | **No change needed**: Netlify handles PR previews automatically from `netlify.toml` | Updating the build command in Phase 5 is sufficient; no workflow changes required. |
61-
| 5 | Other SP repos | **Tracking issues only**, filed at end of PR | This PR proves the pattern; sibling repos adopt independently. No code coupling. |
62-
| 6 | Theme submodule | **Remove in this PR** | The submodule is consumed only by Hugo, which is being removed. The other three repos vendor their own submodule and are unaffected. |
55+
| # | Question | Recommendation | One-line rationale |
56+
| --- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
57+
| 1 | Footer / quicklinks | **Defer**: file follow-up issue, ship MyST default footer | Custom MyST theme work blocks the migration; visual parity is not a SciPy 2026 must-have. |
58+
| 2 | Cookie / Jekyll | **Defer**: keep the submodule and `make cookie` target unchanged in this PR | External content lives at `/development/`; touching Jekyll doubles the PR scope. |
59+
| 3 | Netlify | **Update `netlify.toml`**: remove Hugo/Dart Sass toolchain setup; add `pip install mystmd`; keep `make html-all` as build command | Netlify is the active deploy target for the live site and PR previews. Minimal change; see ADR 0007. |
60+
| 4 | Preview deploy | **No change needed**: Netlify handles PR previews automatically from `netlify.toml` | Updating the build command in Phase 5 is sufficient; no workflow changes required. |
61+
| 5 | Other SP repos | **Tracking issues only**, filed at end of PR | This PR proves the pattern; sibling repos adopt independently. No code coupling. |
62+
| 6 | Theme submodule | **Remove in this PR** | The submodule is consumed only by Hugo, which is being removed. The other three repos vendor their own submodule and are unaffected. |
6363

6464
---
6565

@@ -91,6 +91,7 @@ npm, etc.).
9191
- `make html` (Hugo) still works — coexistence proven.
9292

9393
### CI status: still green.
94+
9495
Only `lint.yml` runs at this point; no deploy workflow exists yet.
9596

9697
---
@@ -123,6 +124,7 @@ changes.
123124
intentionally cutting over.
124125

125126
### CI status: **Netlify deploy fails** (Hugo can no longer find section
127+
126128
indices after the rename). Lint passes. This is the first commit where
127129
the deploy is intentionally broken; it remains broken through Phase 5.
128130
All commits on this PR are merged together — local `myst build --html`
@@ -143,6 +145,7 @@ mapping pattern **once per shortcode type**, not nine times.
143145
- `content/contributors/index.md`
144146
- `content/documentation/index.md`
145147
- Mapping (canonical, documented in ADR 0002):
148+
146149
```
147150
{{< grid columns="1 2 2 3" >}} → ::::{grid} 1 2 2 3
148151
:gutter: 2
@@ -155,6 +158,7 @@ mapping pattern **once per shortcode type**, not nine times.
155158
156159
{{< /grid >}} → ::::
157160
```
161+
158162
- Note: `content/contributors/index.md` contains **two** grid blocks;
159163
its diff is larger than the other two files.
160164
- Why: one commit, one pattern. A reviewer reads this diff and learns
@@ -260,6 +264,7 @@ cookie content into `public/`. Netlify can then call `make html-all` unchanged.
260264
- `make html-all` → MyST output plus cookie merged into `public/`.
261265
262266
**Pre-Phase 6 sign-off (R3):** before updating Netlify, confirm:
267+
263268
- Every page in the Hugo build has a counterpart in `_build/html/`.
264269
Hugo is broken on this branch since Phase 2; produce the reference list
265270
by running `make html` from a clean checkout of `main` (Hugo still works
@@ -384,4 +389,3 @@ as a Phase 4 prerequisite and their numbers are already in `myst.yml`.
384389
deferred-work issues.
385390
386391
---
387-

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

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -19,22 +19,22 @@ closest published reference in the ecosystem.
1919

2020
## Planning docs
2121

22-
| File | Purpose |
23-
|------|---------|
22+
| File | Purpose |
23+
| ---------------------------------- | ---------------------------------------------------------- |
2424
| [REQUIREMENTS.md](REQUIREMENTS.md) | What the migration must achieve; testable success criteria |
25-
| [PLAN.md](PLAN.md) | Commit-by-commit implementation sequence |
25+
| [PLAN.md](PLAN.md) | Commit-by-commit implementation sequence |
2626

2727
## ADRs
2828

29-
| # | Title | Status |
30-
|---|-------|--------|
31-
| [0001](0001-migrate-to-mystmd.md) | Migrate build system from Hugo to MyST-MD | Proposed |
32-
| [0002](0002-shortcode-mapping.md) | Hugo shortcode → MyST directive mapping | Proposed |
33-
| [0003](0003-remove-hugo-theme-submodule.md) | Remove scientific-python-hugo-theme submodule | Proposed |
34-
| [0004](0004-defer-cookie-jekyll.md) | Defer migration of external-content/cookie (Jekyll) | Proposed |
35-
| [0005](0005-defer-footer-quicklinks.md) | Defer footer and quicklinks to follow-up | Proposed |
36-
| [0006](0006-sibling-repo-migration.md) | Sibling SP repos migrate independently | Proposed |
37-
| [0007](0007-deploy-strategy.md) | Update netlify.toml for MyST build | Proposed |
29+
| # | Title | Status |
30+
| ------------------------------------------- | --------------------------------------------------- | -------- |
31+
| [0001](0001-migrate-to-mystmd.md) | Migrate build system from Hugo to MyST-MD | Proposed |
32+
| [0002](0002-shortcode-mapping.md) | Hugo shortcode → MyST directive mapping | Proposed |
33+
| [0003](0003-remove-hugo-theme-submodule.md) | Remove scientific-python-hugo-theme submodule | Proposed |
34+
| [0004](0004-defer-cookie-jekyll.md) | Defer migration of external-content/cookie (Jekyll) | Proposed |
35+
| [0005](0005-defer-footer-quicklinks.md) | Defer footer and quicklinks to follow-up | Proposed |
36+
| [0006](0006-sibling-repo-migration.md) | Sibling SP repos migrate independently | Proposed |
37+
| [0007](0007-deploy-strategy.md) | Update netlify.toml for MyST build | Proposed |
3838

3939
**ADR status convention:** `Proposed` means the decision is implemented on
4040
this branch and awaiting maintainer review. `Accepted` means the PR has

0 commit comments

Comments
 (0)