build: add myst.yml at repo root

- myst.yml: new; project.id, inline toc for content/ tree, excludes submodules
-  fixed project.id UUID, exclude submodule dirs (external-content/, themes/)
- .gitignore: add _build/ the MyST output directory
- ADR 0001: Accepted

Author: lundybernard

.gitignore

@@ -2,4 +2,5 @@
 *~
 resources/
 public/
+_build/
 .DS_Store

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

@@ -1,7 +1,8 @@
 # ADR 0001 — Migrate build system from Hugo to MyST-MD
 
 Date: 2026-05-11
-Status: Proposed — **open question for maintainers (see below)**
+Accepted: 2026-05-18
+Status: Accepted
 Branch: lb/myst-migration
 Issue: scientific-python/scientific-python.org#846
 
@@ -16,7 +17,7 @@ Three realistic MyST toolchain options exist. They are not equivalent:
 underlying engine and is available as both a Node package (npm) and a Python
 package (pip/conda) that bundles Node internally.
 
-## Decision (proposed)
+## Decision
 
 Replace Hugo with **`mystmd` Python package** (`pip install mystmd`,
 `myst build --html`) as the build tool.
@@ -50,19 +51,6 @@ RTD, or GitHub Actions (Node is bundled inside the package). The `myst.yml`
 config is identical to the Node CLI — switching delivery method later is a
 one-line change.
 
-## Open question for maintainers
-
-> **Which MyST toolchain should `learn.scientific-python.org` adopt?**
->
-> A. `mystmd` Python package — proposed above (`pip install mystmd`)
-> B. `jupyter-book 2.x` — if the team prefers a unified JB-based approach
-> C. `mystmd` Node CLI — if the team prefers the native Node runtime
->
-> This is the foundational decision for the migration. All downstream ADRs
-> (0002–0007) assume option A. If maintainers choose B, the `myst.yml` /
-> `_toc.yml` structure and config format change significantly. Option C
-> requires Node.js toolchain setup in `netlify.toml` and CI.
-
 ## Installation
 
 For Netlify builds and RTD: `pip install mystmd` (no Node configuration needed

myst.yml

@@ -0,0 +1,45 @@
+version: 1
+
+project:
+  id: 97f4bf9c-5845-4aac-aa8d-1051725d9067 # fixed UUID; MyST regenerates on each build without this, breaking caching
+  title: Learn Scientific Python
+  exclude:
+    - external-content/**
+    - themes/**
+  toc:
+    - file: content/_index.md
+    - file: content/about/_index.md
+      children:
+        - file: content/about/governance.md
+    - file: content/contributors/_index.md
+      children:
+        - file: content/contributors/getting-started.md
+        - file: content/contributors/choosing-a-project.md
+        - file: content/contributors/why-contribute.md
+        - file: content/contributors/ways-to-contribute.md
+        - file: content/contributors/first-contribution.md
+        - title: Setup
+          children:
+            - file: content/contributors/setup/install.md
+            - file: content/contributors/setup/ecosystem.md
+            - file: content/contributors/setup/next-steps.md
+    - file: content/community/_index.md
+      children:
+        - file: content/community/role.md
+        - file: content/community/onboarding.md
+        - file: content/community/skills.md
+        - file: content/community/project-management.md
+        - file: content/community/community-meetings.md
+        - file: content/community/community-outreach.md
+    - file: content/documentation/_index.md
+      children:
+        - file: content/documentation/accessible-documentation.md
+    - file: content/maintainers/_index.md
+      children:
+        - file: content/maintainers/interacting-with-new-contributors.md
+        - file: content/maintainers/managing-conflict.md
+        - file: content/maintainers/meeting_types.md
+    - file: content/roadmap.md
+
+site:
+  title: Learn Scientific Python