feat: bring well-lit path guides onto the docs site - #453
Open
UgaTheDev wants to merge 2 commits into
Open
Conversation
UgaTheDev
requested review from
Gregory-Pereira,
chcost,
clubanderson,
davidgs,
jjasghar,
petecheslock and
robertgshaw2-redhat
as code owners
July 28, 2026 09:40
✅ Deploy Preview for llm-d ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Unsigned commits detected! Please sign your commits. For instructions on how to set up GPG/SSH signing and verify your commits, please see GitHub Documentation. |
UgaTheDev
force-pushed
the
feat/docs/well-lit-path-guides
branch
2 times, most recently
from
July 30, 2026 09:43
750d3be to
14a2e40
Compare
Mirrors the top-level well-lit-path deployment guides from llm-d/llm-d (guides/<name>/README.md) onto the site as their own docs-plugin instance at /guides, the same way community/ already mirrors repo-root files from that repo. This first slice wires up the full pipeline end to end and migrates two guides (Optimized Baseline, Multi-Model Routing): - docs-sync.yaml gains a `guides:` list (docs-sync.yaml, manifest.go, validate.go) and a sync step (sync/guides.go) analogous to the existing community sync. - docusaurus.config.js registers a second @docusaurus/plugin-content-docs instance rooted at guides/, with its own sidebar (sidebarsGuides.js) and a navbar entry, and adds /guides to the local search index. - guides/index.md is the authored landing page for the section. - preprocess.mjs now resolves a well-lit path's "Deploy" link to the migrated guide's page under /guides when that guide has been synced, instead of always sending it to GitHub. - guides/guides.go additionally repairs two classes of absolute /docs/... links that appear in guide READMEs (written assuming guides render inline with a docs snapshot): /docs/guides/<name> isn't a real path here (guides live at /guides/<name>), and other /docs/<section>/... targets that haven't shipped in the latest release yet are routed through /docs/dev/ instead of 404ing. Guides not yet migrated keep resolving via their existing GitHub fallback, so this ships without any broken links or orphaned nav entries; `make check-links` passes clean, matching main. Remaining guides (predicted-latency-routing, precise-prefix-cache- routing, tiered-prefix-cache, pd-disaggregation, wide-ep-lws, flow-control, workload-autoscaling, fast-model-actuation, the two workload guides, and the recipes/ directory) are left for follow-up PRs, along with the faceted model/server/accelerator/router-mode navigation the issue asks for — this PR is the plumbing plus a working example, not the full information architecture. Fixes llm-d#380 Signed-off-by: Kush Zingade <kush.zingade@gmail.com>
Review of the well-lit path guides sync found the guide READMEs' relative links resolving wrong on the two shipped pages: rewriteURL was mapping any guides/... path (not just the two migrated guide roots) through toSiteDocURL, producing /docs/guides/<name>/... links that are not a real route on this site. A regex repair pass then collapsed those broken links down to the guide's own root, so e.g. all three Benchmarking Reports links on optimized-baseline.md became self-links to the page the reader is already on, and the calibration recipe / configuration matrix links pointed at guides/recipes instead of the file their link text named. The links themselves are relative in the upstream READMEs (e.g. ./benchmark-results/<x>/README.md, ../recipes/router/calibration/ README.md) - the /docs/guides/... form was never present upstream, it was produced by this repo's own rewriter. So the fix is in rewriteURL: only route docs/... targets through toSiteDocURL; guides/... targets that aren't a migrated guide's own README (the pathMap case) now fall through to GitHub blob/tree, same as any other out-of-tree link, preserving the full path. This removes the regex repair pass in guides.go entirely along with the incorrect comment that blamed upstream READMEs for the rewriter's own bug. Also convert GitHub alert blockquotes (> [!NOTE] etc.) into Docusaurus admonitions for guide pages. guides/ isn't run through the JS markdown preprocessor (it bails on anything outside docsDir), so the ten alerts across the two migrated guides were rendering as literal blockquotes containing "[!NOTE]". Ported preprocess.mjs's convertGithubAdmonitions to Go and run it in the guides sync step. Also drop the guides docs-plugin instance's editUrl - it points "Edit this page" at llm-d/llm-d for guides/index.md, a file that only exists in this repo, matching how the community instance already omits it (synced pages have their own custom_edit_url). Added a table test over rewriteURL covering the guides link cases above. Signed-off-by: Kush Zingade <kush.zingade@gmail.com>
UgaTheDev
force-pushed
the
feat/docs/well-lit-path-guides
branch
from
August 11, 2026 06:07
14a2e40 to
b8ebdb8
Compare
5 tasks
Author
|
Four weeks on this one with everything green (signed commits, DCO, deploy preview all passing) — Scope recap, since the diff looks bigger than the decision it asks for: this adds the sync So the review is really one question: is generating the guides from the source repo the right |
Member
Contributor
|
I was waiting for clarification on this as well. |
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
3 participants
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?
Brings the well-lit-path deployment guides from llm-d/llm-d onto this site as their own docs section at
/guides, the same waycommunity/mirrors repo-root files.This is a first slice: the full sync plumbing plus two guides migrated end to end (Optimized Baseline, Multi-Model Routing). Guide pages are generated from
guides/<name>/README.mdin llm-d/llm-d by thellmd-sitesync tool rather than copied by hand, so they stay current the way the community files do.guides/index.mdis authored; the sidebar isautogeneratedand ordered bysidebar_position.Remaining guides, and the faceted model/server/accelerator/router-mode navigation the issue describes, are deliberately left for follow-up PRs. The overview page says so explicitly, and a guide that isn't on the site yet still resolves from its well-lit path's "Deploy" link, which falls back to the recipe on GitHub, so this lands incrementally without leaving dead links behind.
The second commit fixes two things found in self-review.
rewriteURLwas routing anyguides/...path throughtoSiteDocURL, producing/docs/guides/<name>/...links that aren't a real route here; a regex repair pass then collapsed those to the guide's own root, so all three "Benchmarking Reports" links onoptimized-baseline.mdbecame self-links to the page the reader was already on. The fix is inrewriteURLitself: onlydocs/...targets go throughtoSiteDocURL, andguides/...targets that aren't a migrated guide's own README fall through to GitHub blob/tree with the full path intact. That let the regex pass be deleted entirely. Separately,guides/isn't run through the JS markdown preprocessor (it bails outsidedocsDir), so ten GitHub alert blockquotes across the two pages were rendering as literal[!NOTE]text;convertGithubAdmonitionsis now ported to Go and run in the guides sync step.Why is this change needed?
Fixes #380. The deployment recipes are the thing readers need after picking a well-lit path, and today they only exist as READMEs in llm-d/llm-d, so the "Deploy" links leave the site. Generating them through the existing sync tooling means they don't have to be maintained twice.
How was this tested?
npm test)npm run build:all)npm run check-links)npm run serve)npm testisn't defined as a script in this repo, so there was nothing to run under that name. The test surface for the sync tooling is Go:go test ./...intools/llmd-sitepasses, including new cases covering the guides manifest entries, the guide file helpers, and the corrected link rewriting.npm run build:allcompletes with✓ build complete.npm run check-linksreports 0 broken links across 403 pages / 446 links, with all 304 GitHub URLs checked.Served the built site locally and checked both generated pages.
/guides/optimized-baselineand/guides/multi-model-routingboth return 200, the ten GitHub alerts render as Docusaurus admonitions (16 admonition elements, zero literal[!NOTE]strings left in the HTML), and the three "Benchmarking Reports" links resolve to their full upstream paths underguides/optimized-baseline/benchmark-results/...rather than back to the page itself.One thing worth flagging: the generated
/guides/optimized-baselinepage carries a broken-anchor warning (distinct from the link check above, which is clean), because its source README links to#benchmarking-reportwhile the heading it points at is## Benchmarking Reports. That's pre-existing in llm-d/llm-d (guides/optimized-baseline/README.md), not introduced here, and since the page is generated I left it rather than patching a file the next sync would overwrite. Happy to send the one-word fix upstream separately.onBrokenAnchorsis alreadywarnand the site has a number of these today, so the build isn't affected either way.Checklist
git commit -s) per DCOnpm test)npm run build:all)npm run check-links)"Tests pass locally" is checked on the basis of the Go suite, since there's no
npm testscript. "Documentation updated" refers to the authoredguides/index.mdoverview page.Related Issues
Fixes #380.
Context: #421 replaced the old
sync-docs.shapproach with thellmd-siteGo tooling, and this builds on that rather than reviving the earlier shell-script approach from the closed #387.