Context
In #1787 we added docusaurus-plugin-llms to generate llms.txt + per-page
.md siblings. The plugin (v0.4.0) generates .md files at paths derived
from the source file location and slug: frontmatter, but it doesn't
account for two Docusaurus URL-rewriting behaviors used in this repo:
-
slug: frontmatter — page URL is decoupled from source path.
Example: docs/learn/core-concepts/overview.md with slug: /learn/core-concepts/
renders at /docs/learn/core-concepts/, but the plugin writes the .md to
build/learn/core-concepts.md. Appending .md to the page URL → 404.
-
Filename equals parent directory name — Docusaurus collapses the URL.
Example: docs/governance/cardano-governance/cardano-governance.md renders at
/docs/governance/cardano-governance/, but the plugin writes the .md to
build/docs/governance/cardano-governance/cardano-governance.md.
Appending .md to the page URL → 404.
Affects 13 pages on this site.
Workaround in place
scripts/fix-llms-paths.js runs in package.json's build step after
docusaurus build. It moves the 13 misplaced .md files to their URL-aligned
paths and rewrites the URLs inside llms.txt / llms-full.txt.
Upstream status
Related issues against rachfop/docusaurus-plugin-llms:
Downgrading to v0.3.1 or v0.2.2 makes things worse (verified — v0.3.1 introduces
a double-slash baseUrl bug, v0.2.2 strips /docs/ from all 335 pages).
Action when fixed
When upstream lands a fix that respects routeBasePath, slug:, and the
id-collapse pattern:
- Bump
docusaurus-plugin-llms in package.json.
- Run
yarn build and verify all 13 URLs in scripts/fix-llms-paths.js
return 200 with .md siblings at the URL-aligned location.
- Delete
scripts/fix-llms-paths.js.
- Remove the
&& node scripts/fix-llms-paths.js tail from the build script
in package.json.
- Close this issue.
Context
In #1787 we added
docusaurus-plugin-llmsto generatellms.txt+ per-page.mdsiblings. The plugin (v0.4.0) generates.mdfiles at paths derivedfrom the source file location and
slug:frontmatter, but it doesn'taccount for two Docusaurus URL-rewriting behaviors used in this repo:
slug:frontmatter — page URL is decoupled from source path.Example:
docs/learn/core-concepts/overview.mdwithslug: /learn/core-concepts/renders at
/docs/learn/core-concepts/, but the plugin writes the.mdtobuild/learn/core-concepts.md. Appending.mdto the page URL → 404.Filename equals parent directory name — Docusaurus collapses the URL.
Example:
docs/governance/cardano-governance/cardano-governance.mdrenders at/docs/governance/cardano-governance/, but the plugin writes the.mdtobuild/docs/governance/cardano-governance/cardano-governance.md.Appending
.mdto the page URL → 404.Affects 13 pages on this site.
Workaround in place
scripts/fix-llms-paths.jsruns inpackage.json'sbuildstep afterdocusaurus build. It moves the 13 misplaced.mdfiles to their URL-alignedpaths and rewrites the URLs inside
llms.txt/llms-full.txt.Upstream status
Related issues against
rachfop/docusaurus-plugin-llms:.md paths are invalid and return Not Found(v0.4.0)URLs silently drop baseUrl and break when docsDir has a trailing slash (v0.4.0)Wrong URL - The plugin ignores slug(claimed fixed but regressed)Incorrect generated URLs: Docusaurus path prefix in slug is not removedPreserve original URL paths for markdown files instead of flattening themDowngrading to v0.3.1 or v0.2.2 makes things worse (verified — v0.3.1 introduces
a double-slash baseUrl bug, v0.2.2 strips
/docs/from all 335 pages).Action when fixed
When upstream lands a fix that respects
routeBasePath,slug:, and theid-collapse pattern:
docusaurus-plugin-llmsinpackage.json.yarn buildand verify all 13 URLs inscripts/fix-llms-paths.jsreturn 200 with
.mdsiblings at the URL-aligned location.scripts/fix-llms-paths.js.&& node scripts/fix-llms-paths.jstail from thebuildscriptin
package.json.