QT/superset2
1
0
Fork 0
mirror of https://github.com/apache/superset.git synced 2026-05-25 09:45:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(docs): use .mdx (not .md) for generated component-page links

Browse Source 
CI caught a follow-on bug from the previous commit. The component
files emitted by generate-superset-components.mjs are `.mdx`, but
my generator patch appended `.md` to the link suffix. Result: the
generated index pages (ui/index.mdx, design-system/index.mdx, and
the build-time-generated extension/index.mdx) reference
`./autocomplete.md`, `./dropdowncontainer.md`, etc. — all targets
that don't exist (the real files are `.mdx`). Docusaurus's
`onBrokenMarkdownLinks: 'throw'` correctly bombs the build.

Worth calling out: this is exactly the failure mode the previous
commit was trying to fix — bare relative links 404'd silently; now
that they go through the file resolver, the resolver catches the
extension mismatch instead. The system is working; my fix was just
wrong on this one detail.

Two corrections:

1. generate-superset-components.mjs now emits `.mdx` suffix (not
   `.md`) on the component links it produces, matching the actual
   page file format. Comment updated to make the intent explicit
   for future maintainers.

2. The two committed auto-generated index files
   (developer_docs/components/ui/index.mdx and
   developer_docs/components/design-system/index.mdx) had 46 + 7 =
   53 `.md` link suffixes from the previous commit. Bulk-corrected
   to `.mdx` to match their actual targets. The third generated
   file (components/extension/index.mdx) is produced at build time
   and not committed; the generator fix above handles it.

Verified with a re-audit script: 92/92 markdown-link targets across
the PR's modified files now resolve to real `.md` / `.mdx` files on
disk. lint-docs-links still passes (it only fails on missing
extensions, not on this category of mismatch — that's `onBroken
MarkdownLinks`'s job, and it WAS doing its job here).
This commit is contained in:
Evan Rusackas
2026-05-13 19:33:26 -07:00
parent 10f71bdcd5
commit 209d8e2906
3 changed files with 62 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/scripts/generate-superset-components.mjs
View File

@@ -1260,13 +1260,15 @@ function generateCategoryIndex(category, components) {
};
const componentList = components
.sort((a, b) => a.componentName.localeCompare(b.componentName))
// `.md` suffix on the relative link is required: Docusaurus only
// validates and rewrites *file-based* references (.md/.mdx). Bare
// relative paths bypass the file resolver and get emitted as raw
// HTML hrefs that the browser resolves against the current URL —
// which gives the wrong directory for trailing-slash routes and
// breaks SPA navigation. See docs/scripts/lint-docs-links.mjs.
.map(c => `- [${c.componentName}](./${c.componentName.toLowerCase()}.md)`)
// `.mdx` suffix matches the actual component page files emitted
// by this generator (see the MDX wrappers below). The extension
// is required: Docusaurus only validates and rewrites *file-based*
// references (.md/.mdx). Bare relative paths bypass the file
// resolver and get emitted as raw HTML hrefs that the browser
// resolves against the current URL — which gives the wrong
// directory for trailing-slash routes and breaks SPA navigation.
// See docs/scripts/lint-docs-links.mjs.
.map(c => `- [${c.componentName}](./${c.componentName.toLowerCase()}.mdx)`)
.join('\n');
return `---