fix(docs): recurse into docs subdirectories when preparing for Docusaurus#32
Merged
Conversation
…urus The Docusaurus prepare step at website/scripts/prepare-docs.js used a non-recursive readdirSync over docs/, so it silently skipped any subdirectory. The recently merged docs/adr/ section therefore never reached the published site, despite the build appearing to succeed. Recurse the source tree, preserving directory structure on the way to website/docs/. For nested files we omit explicit `id` frontmatter so that Docusaurus derives both the id and the route from the file's path, which is the cleanest way to give nested docs unique URLs without hitting Docusaurus's "id cannot include slash" rule. Top-level docs keep their explicit id and existing URL, so this is a backward- compatible change. Verified locally with `npm run build` in website/: docs/adr/README.md now renders at /docs/adr and docs/adr/0001-aws-identity-center.md at /docs/adr/aws-identity-center.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
website/scripts/prepare-docs.jsused a non-recursivereaddirSyncand only copied top-level.mdfiles fromdocs/intowebsite/docs/. The recently mergeddocs/adr/section was silently skipped, so the ADR pages 404 on the published site even though the build succeeded.website/docs/. For nested files, omit the explicitidfrontmatter so Docusaurus derives both the id and the route from the file path — the cleanest way to give nested docs unique URLs without hitting Docusaurus's "id cannot include slash" rule.idretained), so this is backward-compatible: existing URLs do not move.Verified locally
npm run buildinwebsite/succeeds and produces:/docs/adrrenderingdocs/adr/README.md(the ADR section landing page)./docs/adr/aws-identity-centerrenderingdocs/adr/0001-aws-identity-center.md. The0001-numeric prefix is stripped per Docusaurus's autogenerated-sidebar convention.The user-typed URL
/docs/adr/README.mdwas never going to resolve — Docusaurus serves HTML, not raw.mdfiles. Internal links in the ADR README still use./*.mdso they continue to work on GitHub's file browser.Test plan
/docs/00-repo-inventory) are unchanged.