Skip to main content

Bug Report BR-068: Docusaurus strict MDX cannot resolve monorepo markdown links — production build fails

Status: COMPLETE
Priority: HIGH
Severity: HIGH — portal/ npm run build fails under strict link/MDX rules; browsable docs site cannot be regenerated reliably while the corpus uses cross-root relative links common in GitHub-native authoring.
Created: 2026-04-19
Last updated: 2026-04-19
Version: v0.5.9.11+5
Code: BR-068

Implementing Task: E5:S09:T11

Problem Statement​

The documentation portal (portal/) uses @docusaurus/preset-classic with path: '../docs' (repository docs/ only). With onBrokenLinks: 'throw', onBrokenMarkdownLinks: 'throw', and onBrokenAnchors: 'throw', MDX compilation fails when a Markdown file under docs/ contains a relative link to a path outside that plugin root.

The repository’s authoring model predates this boundary: Kanban, FR/BR, ADRs, and user-docs routinely link to:

  1. INSTALL_IN_YOUR_PROJECT.md at repository root (not under docs/), via patterns such as ../../../INSTALL_IN_YOUR_PROJECT.md from nested docs/ paths.
  2. Framework packages, e.g. packages/frameworks/workflow mgt/docs/..., via relative traversals from docs/ that leave the docs-plugin corpus.

Result: npm run build (see Observed behavior) exits with errors such as “Markdown link with URL ../../../INSTALL_IN_YOUR_PROJECT.md … couldn't be resolved … within the current plugin” — for many files, not a single typo.

Strict FR-067 / T08 / T10 “throw” behavior is working as configured; the defect is that the combined policy (strict gates + monorepo link graph) is incompatible, so the published site pipeline is effectively broken until links are normalized, stubbed, or explicitly exempted.

Expected Behavior​

  • npm run build in portal/ completes green on dev with the same Markdown corpus intended for publication (or an explicitly documented subset via exclude: / split site).
  • Authors have a single, documented pattern for linking to:
    • repo-root install entry (INSTALL_IN_YOUR_PROJECT.md),
    • framework packages under packages/,
    • and other out-of-docs/ artifacts, without breaking MDX resolution.
  • CI (if present) matches local build strictness so main / publish branch cannot drift into a broken publish state.

Observed Behavior​

  • cd portal && npm run build → failure (non-zero exit).

  • Representative MDX errors (paraphrased from compiler output):

    • Unresolved ../../../INSTALL_IN_YOUR_PROJECT.md from e.g. docs/documentation/user-docs/*.md, docs/architecture/standards-and-adrs/ADR-003-*.md, docs/project-management/kanban/fr-br/FR-080-*.md.
    • Unresolved ../../../../packages/frameworks/... from Kanban / FR documents.
    • Additional unresolved intra-repo paths where relative navigation leaves docs/.

  • GitHub-native browsing of the same files often works (different base path); Docusaurus does not accept those relative targets inside the docs plugin.

Scope / Affected Areas​

AreaRole
portal/docusaurus.config.jsDocs path, exclude, strict hooks
portal/sidebars.jsAutogenerated sections only — no fix without link/corpus strategy
Repository docs/**/*.mdMany relative links to root / packages/
Root INSTALL_IN_YOUR_PROJECT.mdCanonical adopter entry outside docs/

Acceptance Criteria​

  • npm run build succeeds with policy-aligned link strategy (documented in portal README or maintenance doc).
  • Linking policy for out-of-docs/ targets (INSTALL, framework paths) is recorded — e.g. stubs under docs/guides/, approved absolute GitHub URLs, pathname://, symlink, or controlled exclude — with no silent regression of FR-067 strict intent.
  • Spot-check: pages that previously failed MDX (INSTALL pointer from user-docs; packages/ links from fr-br) render or link per policy.
  • Optional: CI workflow runs portal build on relevant paths — satisfied by .github/workflows/docusaurus-build.yml (FR-069 / E5:S09:T05).

Resolution​

Delivered: 2026-04-19 — v0.5.9.11+5 (RW E5:S09:T11 --art, Wave 4 traceability).

  • FR-067 — production corpus triage; enabled strict checks.
  • Story 009 – Docusaurus Documentation Portal — T08 / T10 strict links & anchors (COMPLETE historically; this BR is post-completion regression class).
  • BR-066 — planning artifacts filing (related portal surface).
  • FR-070 — GitHub Pages deployment depends on green build.

Intake Decision​

Intake Status: ACCEPTED (filed from maintainer decision: BR tracks Docusaurus/build defect vs monorepo link graph)
Intake Date: 2026-04-19