fixup: ADR-1-8

Author: lundybernard

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

@@ -1,8 +1,6 @@
----
-
 # ADR 0008 — URL structure: MyST flat slugs vs Hugo hierarchical paths
 
-Date: 2026-05-19
+Date: 2026-05-18
 Status: Proposed
 Branch: lb/myst-migration
 
@@ -11,18 +9,23 @@ Branch: lb/myst-migration
 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`.
+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`.
 
-This behaviour is not user-configurable; URL generation is internal to MyST.
+MyST does support directory-based URLs via `site.options.folders: true` in
+`myst.yml`, which maps `content/about/governance.md` → `/about/governance/`.
+Index files in subdirectories become section landing pages
+(`content/about/index.md` → `/about/`). This is the documented approach for
+preserving nested folder structure.
 
 This was surfaced by `netlify-plugin-checklinks` during the first Netlify
-deploy of the PR. The build succeeds; the link checker finds broken internal
+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 no longer exist in the
-MyST output.
+(`/about/governance`, `/contributors/`, etc.) that do not exist under MyST's
+default flat-slug output.
 
 Affected link types:
 
@@ -34,48 +37,63 @@ Affected link types:
 
 ## Options considered
 
-1. **Rename `index.md` to `section.md` + update all internal links to flat URLs**
+1. **Enable `site.options.folders: true` in `myst.yml`**
+   - Add one line to `myst.yml`; no content changes required.
+   - MyST generates `content/about/governance.md` → `/about/governance/`,
+     matching the existing Hugo URL structure.
+   - `content/<section>/index.md` files become section landing pages
+     (`/contributors/`, `/about/`, etc.) — matching Hugo's behaviour exactly.
+   - Existing `:link:` values and inline markdown links in content continue
+     to resolve correctly without modification.
+   - Pros: minimal change, follows MyST's documented recommendation, preserves
+     URL continuity for external links, no SEO disruption.
+   - Cons: path conflicts arise if both `<section>.md` and
+     `<section>/index.md` exist (the file wins; the index gets a deduplicated
+     slug). No such conflicts exist in the current content tree.
+
+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: 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.
+   - Pros: flat URLs are shorter; works without `folders` option.
+   - 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.
 
-2. **Netlify `_redirects` shim (keep Hugo-style links, redirect to flat URLs)**
+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.
 
-3. **Disable `netlify-plugin-checklinks` failure / warn-only**
+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 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.
+   - 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 (`site.options.folders: true`). It is the single-line
+fix that follows MyST's documented design for folder-based URLs, preserves the
+existing URL structure without any content edits, and eliminates the 12 broken
+internal links immediately.
+
 ## 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.
+- Option 1 requires one `myst.yml` change and no content edits. The 12 broken
+  internal links are resolved without touching any `.md` files.
+- External links from the Hugo site (`/about/governance/`, `/contributors/`,
+  etc.) continue to work unchanged — no redirects needed.
+- If Option 1 is chosen, Phase 3 card `:link:` values and inline markdown
+  links require no fixup.
+- 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