fixup: add myst theme

Author: lundybernard

docs/decisions/0001-myst-migration/0009-myst-theme-integration.md

@@ -7,134 +7,81 @@ Branch: lb/myst-migration
 ## Context
 
 `scientific-python/scientific-python-myst-theme` provides shared MyST styling,
-config, plugins (`team-grid.mjs`), assets (logo, favicon, CSS), and footer
-template for Scientific Python MyST sites. It is distributed as a **copier
-template**, not a pip or npm package. The intended consumption pattern is for
-a site's `myst.yml` to `extends:` a `config/scientific-python.yml` file that
-ships in the template.
-
-The theme is brand-new (created 2026-05-18, 0 tagged releases, 5 forks as of
-2026-05-19). The upstream HEAD on `main` is currently the only available
-pinning target.
-
-This site already uses one git submodule (`external-content/cookie`, Jekyll,
-pinned to `2025.10.01`, see ADR 0004). We need a strategy for pulling theme
-files into `content/` that is reproducible on Netlify CI (`make html-all`),
-on a fresh `git clone` + `myst start`, and across maintainer machines, while
-allowing the theme to evolve upstream.
-
-Constraint: MyST resolves paths in `myst.yml` (including `extends:`, `style:`,
-`logo:`, plugins) relative to the `myst.yml` location, which is `content/`.
-Theme files must end up at predictable paths under `content/`.
+config, plugins (`team-grid.mjs`), assets (logo, favicon, CSS), and a footer
+template. It is distributed as a **copier template**, not a pip/npm package: the
+intended consumption pattern is for a site's `myst.yml` to `extends:` a
+`config/scientific-python.yml` shipped in the template.
+
+The theme is brand-new (created 2026-05-18, 0 tagged releases), so upstream
+`main` HEAD is the only pinning target. We need a strategy for pulling theme
+files into `content/` that is reproducible on Netlify CI (`make html-all`), on a
+fresh `git clone` + `myst start`, and across maintainer machines.
+
+Constraint: MyST resolves `myst.yml` paths (`extends:`, `style:`, `logo:`,
+plugins) relative to the `myst.yml` location, which is `content/`. Theme files
+must land at predictable paths under `content/`.
 
 ## Decision
 
-Adopt **committed theme files, vendored selectively from a copier render**
-(a refinement of Option 2).
+Adopt **committed theme files, vendored selectively from a copier render** (a
+refinement of Option 2).
 
-The upstream template is a _scaffold-a-new-site_ template: a full
-`copier copy` renders `index.md`, `myst.yml`, `about.md`, `news.md`,
-`Makefile`, and `.gitignore` alongside the theme infrastructure. Our
-`content/` already holds a populated site, so a direct
-`copier copy ... content/` would clobber `index.md`/`myst.yml` and add
-unwanted pages. Therefore we render to a throwaway directory and copy in only
-the theme-infrastructure files.
+Upstream is a _scaffold-a-new-site_ template: a full `copier copy` renders
+`index.md`, `myst.yml`, `about.md`, `news.md`, `Makefile`, `.gitignore`
+alongside the theme infrastructure. Our `content/` already holds a populated
+site, so a direct copy would clobber `index.md`/`myst.yml` and add unwanted
+pages. We therefore render to a throwaway dir and copy in only the theme files.
 
 Implementation (as performed):
 
-- Render once to a temp dir:
-  `pixi exec --spec copier copier copy --trust --defaults gh:scientific-python/scientific-python-myst-theme <tmp>`.
-  (`copier` is run ephemerally via `pixi exec`; it is not a project
-  dependency.)
-- Vendor only these files into `content/`, committed to the repo:
-  `config/scientific-python.yml`, `assets/css/scientific-python.css`,
-  `assets/images/logo.svg`, `assets/images/favicon.ico`, `team-grid.mjs`,
-  `footer.md`, and `.copier-answers.yml` (kept for provenance: it records
-  the upstream `_commit`).
-- Add `extends: config/scientific-python.yml` to `content/myst.yml`. The
-  extended config provides `site.template`, `folders`, and the `hide_*`
-  options. `site.options.style` must be respecified locally because `extends`
-  overrides (does not append) it: it is set to a list of the theme CSS plus a
-  local `assets/css/custom.css` override (the former top-level `custom.css`,
-  relocated under `content/assets/css/`).
-- The previously duplicated top-level `assets/` (logo and favicon, byte
-  identical to the theme copies) is removed; `content/assets/` is now the
-  single source.
-- Do not add copier to the Netlify build command or to `make prepare`. CI
-  consumes the committed files as-is.
-
-Update path: because our `index.md`/`myst.yml` have diverged from the
-template, `copier update` cannot be run cleanly against `content/` (it would
-conflict on the scaffold files). Updates are instead done by re-rendering to a
-temp dir and diffing the vendored files by hand. Revisit Option 3 (scheduled
-GitHub Action) and a cleaner `copier update` flow once the upstream theme
-separates "theme core" from "site scaffold" and cuts tagged releases.
+- Render once to a temp dir via `pixi exec --spec copier copier copy --trust
+--defaults gh:scientific-python/scientific-python-myst-theme <tmp>` (copier is
+  run ephemerally; it is not a project dependency).
+- Vendor only these into `content/`, committed: `config/scientific-python.yml`,
+  `assets/css/scientific-python.css`, `assets/images/logo.svg`,
+  `assets/images/favicon.ico`, `team-grid.mjs`, `footer.md`, and
+  `.copier-answers.yml` (provenance: records upstream `_commit`).
+- Add `extends: config/scientific-python.yml` to `content/myst.yml`. `style`
+  must be respecified locally — `extends` overrides (does not append) it — as a
+  list of theme CSS plus a local `assets/css/custom.css` override.
+- Remove the previously duplicated top-level `assets/` (logo/favicon byte
+  identical to theme copies); `content/assets/` is now the single source.
+- Do not add copier to the Netlify build or `make prepare`; CI consumes the
+  committed files as-is.
+
+Update path: `copier update` cannot run cleanly (it conflicts on the diverged
+scaffold files), so updates are done by re-rendering to a temp dir and diffing
+the vendored files by hand. Revisit Option 3 once upstream separates "theme
+core" from "site scaffold" and cuts tagged releases.
 
 Known upstream gap: `config/scientific-python.yml` sets
-`site.parts.primary_sidebar_footer: sidebar-footer.md`, but the template ships
-no such file. The build emits a non-fatal warning
-(`Part file does not exist: sidebar-footer.md`). Tracked to be raised with the
-theme maintainer separately; not stubbed locally.
+`primary_sidebar_footer: sidebar-footer.md`, which the template does not ship; the
+build emits a non-fatal warning. To be raised upstream, not stubbed.
 
-`external-content/cookie` is unaffected and remains a git submodule per
-ADR 0004. The two integrations differ in kind: cookie is a separately-built
-Jekyll site whose output is overlaid on `public/development/`; the theme is
-config plus static assets consumed by the MyST build itself.
+`external-content/cookie` is unaffected (ADR 0004): it is a separately-built
+Jekyll site overlaid on `public/development/`, whereas the theme is config plus
+assets consumed by the MyST build itself.
 
 ## Options considered
 
-1. **Git submodule** (mirror cookie pattern) — add
-   `external-content/scientific-python-myst-theme`, have `make prepare` copy
-   files into `content/`. Consistent with cookie, but introduces transient
-   copied files, dual source of truth (submodule + working copy), and forces
-   a copy step into every fresh `myst start`. Also: the theme is a copier
-   template, not a runnable artifact, so cloning the source repo as a
-   submodule is a structural mismatch.
-2. **Copier copy, committed files** — `copier copy` once, commit rendered
-   files, maintainers run `copier update` manually. Files in the repo,
-   zero new build-time deps, `myst start` works on fresh clone. Tradeoff:
-   manual update cadence; theme drift possible if maintainers neglect updates.
-3. **Scheduled GitHub Action + copier update** — cron-triggered workflow runs
-   `copier update --defaults` and opens a PR on diff. Automatic; files still
-   committed. Adds a workflow file and a maintenance surface (handling
-   merge conflicts in auto-PRs). Premature while upstream has no releases.
-4. **Pre-commit hook running copier update** — slows every commit, doesn't
-   help CI on a fresh checkout, and surprises contributors who don't have
-   copier installed. Rejected.
-5. **Rethink cookie integration** — cookie is a separately-built Jekyll site
-   with its own Ruby toolchain, release tags, and an independent contributor
-   community. Submodule + Makefile remains the right shape for it. The
-   theme decision does not alter ADR 0004.
+1. **Git submodule** (mirror cookie) — introduces transient copied files, dual
+   source of truth, and a copy step on every `myst start`; a copier template is
+   not a runnable artifact, so a source submodule is a structural mismatch.
+2. **Copier copy, committed files** (chosen) — zero new build-time deps,
+   `myst start` works on fresh clone. Tradeoff: manual update cadence, drift risk.
+3. **Scheduled GitHub Action + copier update** — cron PR on diff; automatic but
+   adds a workflow and auto-PR conflict maintenance. Premature with no releases.
+4. **Pre-commit hook running copier update** — slows every commit, doesn't help
+   CI on fresh checkout, surprises contributors without copier. Rejected.
+5. **Rethink cookie integration** — cookie's Ruby toolchain and release tags keep
+   submodule + Makefile right for it; this decision does not alter ADR 0004.
 
 ## Consequences
 
-- `content/config/scientific-python.yml`,
-  `content/assets/css/scientific-python.css`,
-  `content/assets/css/custom.css`, `content/assets/images/logo.svg`,
-  `content/assets/images/favicon.ico`, `content/team-grid.mjs`,
-  `content/footer.md`, and `content/.copier-answers.yml` are committed to the
-  repo.
-- `content/myst.yml` gains `extends: config/scientific-python.yml`, points
-  `logo`/`favicon` at the content-local theme assets, and respecifies `style`
-  as a list (theme CSS plus local `custom.css`).
-- The former top-level `assets/` directory is removed: its `logo.svg` and
-  `favicon.ico` were byte identical to the theme copies, and its unused
-  `custom.css` Lato override was relocated to `content/assets/css/custom.css`
-  and wired into `myst.yml`.
-- Netlify config (`netlify.toml`) is unchanged. `make prepare` is unchanged.
-  `make html-all` continues to work because all theme files are already on
-  disk after `git clone`.
-- Fresh clone developer experience: `git clone && cd content && myst start`
-  works with no extra setup beyond mystmd itself.
-- The committed build path is the `Makefile` (`make html` / `make html-all`,
-  used by Netlify), which already runs the build inside `content/`. The
-  `pixi.toml` `build`/`serve` tasks are a local-only convenience (`pixi.toml`
-  is in `.git/info/exclude`); they were fixed to run with `cwd = content` so
-  they work from the repo root.
-- Theme updates are manual (re-render and diff). Risk: drift from upstream.
-  Mitigation: revisit Option 3 once upstream separates theme core from site
-  scaffold and cuts a tagged release.
-- The lack of upstream tags is recorded here; when the theme publishes its
-  first release, pin `.copier-answers.yml` to that tag.
-- A non-fatal `sidebar-footer.md` warning remains pending an upstream fix.
-- Cookie submodule strategy (ADR 0004) is unaffected.
+- `netlify.toml` and `make prepare` are unchanged; `make html-all` (the
+  Netlify build path) works because all theme files are on disk after `git
+clone`. Fresh clone `git clone && cd content && myst start` needs no setup.
+- `pixi.toml` `build`/`serve` tasks (local-only, git-excluded) were fixed to run
+  with `cwd = content`.
+- Manual updates risk upstream drift; pin `.copier-answers.yml` to the first
+  tagged release when available, and revisit Option 3 then.