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,81 @@
+---
+
+# ADR 0008 — URL structure: MyST flat slugs vs Hugo hierarchical paths
+
+Date: 2026-05-19
+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.
+
+MyST 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`.
+
+This behaviour is not user-configurable; 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 broken internal
+links because content was authored for Hugo-style hierarchical URLs
+(`/about/governance`, `/contributors/`, etc.) that no longer exist in the
+MyST 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. **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: honest fix, works within MyST's model, flat URLs are simpler.
+   - Cons: URL structure changes permanently; external links to the Hugo site
+     break without redirects; flat URLs lose the section context for users
+     reading the URL.
+
+2. **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.
+
+3. **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 safety net.
+
+4. **File a MyST feature request for directory-based URL generation**
+   - Request that MyST support an option to derive page URLs from the directory
+     path rather than the filename alone.
+   - Pros: correct fix at the right layer; no workarounds needed.
+   - Cons: timeline unknown; blocks the PR on upstream response.
+
+## Decision
+
+_Pending team discussion._
+
+## Consequences
+
+- Until resolved, `netlify-plugin-checklinks` will fail on every Netlify deploy.
+- Option 1 (rename + redirects) is the most honest long-term fix and aligns with
+  MyST's design; it should be the default choice unless a MyST fix lands quickly.
+- This ADR should be inserted before the Phase 3 commits in the final commit
+  history, since the URL structure decision affects how shortcode links are
+  written.
+- If option 1 is chosen, Phase 3 (shortcode conversion) commits will need a
+  follow-up fixup to update card `:link:` values and inline markdown links.