fix(docs): tighten onBrokenLinks to throw and fix surfaced broken links

Previously docusaurus.config.ts had `onBrokenLinks: 'warn'`, so broken
internal links produced advisory warnings during build but didn't gate
merges. Tightening to `throw` surfaces every broken internal route at
build time. Three classes of issue fell out:

1. Stale `/docs/...` and `/docs/6.0.0/...` references in the 6.0.0
   versioned snapshot. The user-facing docs section was renamed
   `docs` → `user-docs` (routeBasePath) at some point after 6.0.0 was
   cut, but the snapshot's links still pointed at the old prefix. The
   live site redirects /docs/* → /user-docs/* at runtime, but
   Docusaurus's onBrokenLinks checker doesn't honor redirects.
   Bulk-rewrote /docs/* → /user-docs/* across the snapshot (and one
   /docs/api → /developer-docs/api).

2. Bare-relative MDX links like `[Label](./mcp)` (no .md/.mdx
   extension). Docusaurus renders an absolute href in SSR HTML, so
   static crawlers see correct links — BUT React Router's `<Link>`
   component on the client side resolves the bare path relative to
   the current URL on click, so when the page URL has a trailing
   slash (e.g. /extensions/overview/), `./mcp` becomes
   /extensions/overview/mcp (404). This is exactly the broken-flow a
   user reported on /developer-docs/extensions/overview/. Added the
   `.md`/`.mdx` extension to all 44 such links across 17 files; this
   makes Docusaurus resolve them to the canonical doc URL at the
   <Link> level, so SPA navigation works regardless of trailing slash.

3. Miscellaneous content fixes:
   - 4 `/configuration/feature-flags` references in 6.0.0 snapshot
     pointed at a page that doesn't exist in that version (the
     dedicated feature-flags page was added later). Repointed to the
     `#feature-flags` anchor inside `configuring-superset.mdx`.
   - 3 references to `superset-core/src/superset_core/rest_api/decorators.py`
     in extensions docs were rendered as relative URLs, resolving to
     /developer-docs/extensions/superset-core/... (404). Converted to
     absolute GitHub URLs.
   - 1 `/storybook/?path=...` link in extensions/components/index.mdx
     pointed at a non-existent route. Repointed to the existing
     `/developer-docs/testing/storybook` page that explains how to
     run Storybook locally.
   - 4 unclosed-paren markdown links in 6.0.0 installation-methods.mdx
     (pre-existing source bugs).

Build now passes with `onBrokenLinks: 'throw'`. Note that
`onBrokenAnchors` is still `'warn'` (default); a separate effort
should tighten that and fix the surviving anchor warnings (currently
~60 instances of `/community#superset-community-calendar`).
This commit is contained in:
Claude Code
2026-05-13 18:08:46 -07:00
committed by Evan Rusackas
parent d1e9a5df06
commit 04451766e7
37 changed files with 151 additions and 151 deletions

View File

@@ -10,7 +10,7 @@ version: 1
## Jinja Templates
SQL Lab and Explore supports [Jinja templating](https://jinja.palletsprojects.com/en/2.11.x/) in queries.
To enable templating, the `ENABLE_TEMPLATE_PROCESSING` [feature flag](/docs/6.0.0/configuration/configuring-superset#feature-flags) needs to be enabled in
To enable templating, the `ENABLE_TEMPLATE_PROCESSING` [feature flag](/user-docs/6.0.0/configuration/configuring-superset#feature-flags) needs to be enabled in
`superset_config.py`. When templating is enabled, python code can be embedded in virtual datasets and
in Custom SQL in the filter and metric controls in Explore. By default, the following variables are
made available in the Jinja context: