ADR-1-8: MyST flat slugs vs Hugo paths

Netlify's link checker is failing
due to a URL structure mismatch between Hugo and MyST.

Author: lundybernard

docs/decisions/0001-myst-migration/0008-url-structure.md

@@ -0,0 +1,105 @@
+# ADR 0008 — URL structure: MyST flat slugs vs Hugo hierarchical paths
+
+Date: 2026-05-18
+Status: Proposed
+Branch: lb/myst-migration
+
+## Context
+
+Hugo derives page URLs from the directory structure: `content/about/governance.md`
+→ `/about/governance/`. The directory hierarchy IS the URL, and `content/` is
+treated as the URL root — it is stripped from every path.
+
+MyST's default behaviour derives URLs from the filename only, ignoring the
+containing directory: `content/about/governance.md` → `/governance`. Files
+named `index.md` in subdirectories collide on the slug `index` and are
+deduplicated as `index-1`, `index-2`, etc.: `content/about/index.md` →
+`/index-1`.
+
+MyST does support directory-based URLs via `site.options.folders: true` in
+`myst.yml`. However, MyST has no concept of a "content root" — it has no
+config option equivalent to Hugo's `content/` stripping. MyST grew from the
+Jupyter notebook world where content lives at the project root alongside
+`myst.yml`; a top-level `content/` subdirectory is a Hugo convention, not a
+MyST one. With `folders: true` and content in `content/`, the output is
+`/content/about/governance/` — the `content/` prefix is preserved.
+
+Verified in MyST 1.9.0: no frontmatter field (`slug`, `url_path`, etc.)
+controls a page's URL. URL generation is internal to MyST.
+
+This was surfaced by `netlify-plugin-checklinks` during the first Netlify
+deploy of the PR. The build succeeds; the link checker finds 12 broken internal
+links because content was authored for Hugo-style hierarchical URLs
+(`/about/governance`, `/contributors/`, etc.) that do not exist under MyST's
+default flat-slug output.
+
+Affected link types:
+
+- Section index cards: `:link: /contributors/`, `:link: /documentation/` etc.
+  in `content/index.md`
+- Inline markdown links: `[Role](/community/role)` in `content/community/index.md`
+- Sidebar navigation links generated by MyST from the toc (use actual slugs,
+  so these are self-consistent but don't match the Hugo URL shape)
+
+## Options considered
+
+1. **Enable `site.options.folders: true` + move content to project root**
+   - Enable `site.options.folders: true` in `myst.yml`.
+   - Move all content from `content/<section>/` to `<section>/` at the project
+     root (e.g. `content/about/governance.md` → `about/governance.md`).
+   - Update all `toc` file paths in `myst.yml` accordingly.
+   - Result: `about/governance.md` → `/about/governance/`, matching Hugo's
+     URL structure exactly.
+   - `<section>/index.md` files become section landing pages
+     (`/contributors/`, `/about/`, etc.) — matching Hugo's behaviour.
+   - Pros: follows MyST's documented design and conventional project structure;
+     preserves URL continuity for external links; no SEO disruption; no
+     redirects needed.
+   - Cons: restructuring all file paths is a significant mechanical change;
+     any tooling or scripts that reference `content/` must be updated.
+
+2. **Rename `index.md` to `section.md` + update all internal links to flat URLs**
+   - Rename each `content/<section>/index.md` to `content/<section>/<section>.md`
+     so MyST generates slug `/<section>` instead of `/index-N`.
+   - Update all cross-page links in content to use flat URLs (`/governance`
+     not `/about/governance`).
+   - Add a Netlify `_redirects` file mapping old Hugo URLs to new flat URLs for
+     external link / bookmark compatibility.
+   - Pros: flat URLs are shorter; avoids project restructure.
+   - Cons: large mechanical content churn; URL structure changes permanently;
+     external links to the Hugo site break without redirects; flat URLs lose
+     section context; SEO impact from changed URLs persists until redirects
+     are indexed.
+
+3. **Netlify `_redirects` shim (keep Hugo-style links, redirect to flat URLs)**
+   - Keep content links as-is; add a `_redirects` file that maps every
+     hierarchical Hugo URL to the corresponding flat MyST slug.
+   - Pros: no content changes; external links preserved.
+   - Cons: fragile — `index-N` numbering shifts if toc order changes;
+     maintenance burden every time a page is added; masks the underlying issue.
+
+4. **Disable `netlify-plugin-checklinks` failure / warn-only**
+   - Configure or remove the plugin so broken links produce warnings, not a
+     build failure. Defers URL fix to a follow-up issue.
+   - Pros: unblocks the PR immediately.
+   - Cons: leaves broken links in the deployed site; removes the link-integrity
+     safety net established by ADR 0007.
+
+## Decision
+
+_Pending team discussion._
+
+Recommendation: Option 1 (`folders: true` + move content to project root). It
+follows MyST's documented design and conventional project structure, preserves
+the existing URL shape without content link edits, and avoids the fragility of
+redirect shims. The file restructure is mechanical and one-time.
+
+## Consequences
+
+- Option 1 requires moving all content files out of `content/` to the project
+  root and updating all `toc` entries in `myst.yml`. No content link edits
+  are needed since URLs are preserved.
+- External links from the Hugo site (`/about/governance/`, `/contributors/`,
+  etc.) continue to work unchanged — no redirects needed.
+- Until resolved, `netlify-plugin-checklinks` will fail on every Netlify deploy
+  with 12 broken internal links.

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

@@ -202,6 +202,11 @@ mapping pattern **once per shortcode type**, not nine times.
 
 ### CI status: Netlify deploy still failing (same reason as Phase 2).
 
+**Note:** Phase 3 card `:link:` values and inline markdown links were authored
+with Hugo-style hierarchical URLs. ADR 0008 must be resolved before or
+alongside Phase 3 commits in the final history — if Option 1 (rename +
+flat URLs) is chosen, Phase 3 link values need a fixup commit.
+
 ---
 
 ## Phase 4 — MyST config completeness

myst.yml

@@ -56,3 +56,4 @@ site:
   options:
     domain: learn.scientific-python.org
     logo: assets/images/logo.svg
+    folders: true