feat(docs): mirror upstream docs tree directly (autosync)#385
Open
Ibrahim2595 wants to merge 1 commit into
Open
feat(docs): mirror upstream docs tree directly (autosync)#385Ibrahim2595 wants to merge 1 commit into
Ibrahim2595 wants to merge 1 commit into
Conversation
Rewrite the docs pipeline to build straight from llm-d/llm-d's docs/ tree instead of remapping it. The upstream folder structure IS the site structure, _category_.json drives the sidebar, and frontmatter controls order/labels -- no path remapping, flattening, or slug injection. - sync-docs.sh: mirror docs/ as-is, keeping relative Markdown links so Docusaurus resolves them natively (drops ~1000 lines of remapping) - sidebars.ts: collapse to an autogenerated sidebar from the mirrored tree - docusaurus.config.ts: add client redirects mapping the pre-autosync URLs (flattened well-lit-paths, resources/*, api-reference CRDs, /getting-started intro) to their new folder-mirrored locations - build-all.sh: move src/pages/index.tsx aside for the dev build so the new root intro (slug: /) doesn't collide with the legacy root redirect - VersionDropdown.tsx / docusaurus.config.js: point Dev links at the docs root now that the intro lives at / Assumes the foundations restructure (llm-d#382) and the llm-d autosync PR land first. Pairs with llm-d/llm-d feat/docs-autosync. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: IBRAHIM IBRAHIM <66755652+Ibrahim2595@users.noreply.github.com>
Ibrahim2595
requested review from
Gregory-Pereira,
chcost,
clubanderson,
davidgs,
jjasghar,
petecheslock and
robertgshaw2-redhat
as code owners
✅ Deploy Preview for llm-d ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This was referenced Jun 24, 2026
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.
What does this PR do?
This is the site half of the docs cleanup. It pairs with the upstream restructure in llm-d/llm-d#NNN, which reshaped that repo's
docs/folder so its layout matches the site one-to-one.Until now, the sync script did a lot of reshaping: it flattened folders, remapped paths, and rewrote links to fit a structure that only existed here. That was ~1,000 lines of glue, and it broke any time an upstream page moved.
Now the site just mirrors the upstream
docs/tree as-is. The folder structure becomes the nav,_category_.jsondrives the sidebar, frontmatter handles ordering, and relative links resolve on their own. No remapping.What changed
Rewrote
sync-docs.shto mirror upstreamdocs/as-is. The old script was ~1,000 lines of copying, flattening, path remapping, and link rewriting. The new one just copies the tree over and applies our MDX tweaks (callouts, tabs, etc.). Relative links are left alone and resolve natively.sidebars.tsis now auto-generated from the mirrored tree. Dropped the ~230-line hand-maintained sidebar. Section titles, order, and collapse state come from the upstream_category_.jsonfiles now.Added redirects so old URLs keep working. Anything that moved in the new layout (the flattened well-lit-paths,
resources/*, the API CRD pages, the/getting-startedintro) redirects to its new home, so existing links and bookmarks don't 404.Fixed "Edit this page" for the existing release docs. They get rebuilt with this config (by design), so the config rewrite had to keep handling their older layout, not just the new dev layout.
Pointed the "Dev" version links at the docs root. The dev intro now lives at
/docs/dev/instead of/docs/dev/getting-started, so the version dropdown (both the navbar andVersionDropdown.tsx) was updated to match.Small
build-all.shtweak for the dev build. The new dev intro sits at the docs root, which collided with the old root-redirect page — so the dev build moves that redirect aside and restores it afterward. Release builds are unaffected.Merge order
This one goes second. It reads the new structure that llm-d/llm-d#1933 adds upstream, so until that lands, the dev docs build here won't be green.
Merge llm-d/llm-d#1933 first, then this.
How was this tested?
npm test)npm run build:all)npm run check-links)npm run serve)Checklist
git commit -s) per DCOnpm test)npm run build:all)npm run check-links)Related Issues
#377