Skip to content

Remove scripts/fix-llms-paths.js once docusaurus-plugin-llms handles slug + id-collapse paths #1791

Description

@katomm

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:

  1. 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.

  2. 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:

  1. Bump docusaurus-plugin-llms in package.json.
  2. Run yarn build and verify all 13 URLs in scripts/fix-llms-paths.js
    return 200 with .md siblings at the URL-aligned location.
  3. Delete scripts/fix-llms-paths.js.
  4. Remove the && node scripts/fix-llms-paths.js tail from the build script
    in package.json.
  5. Close this issue.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions