fix(docs): repair the 15 broken links lychee reports on release/1.3.1 - #12641
Conversation
lychee has been failing on every PR against release/1.3.1. The 15 errors fall into three unrelated classes; all are fixed here and every replacement URL was verified to return 200. Dead external link (7 hits, 3 files): https://communityinviter.com/apps/cloud-native/cncf now 404s. Replaced with https://slack.cncf.io/ in CONTRIBUTING.md and both contribution guides, including the zh-CN twin. Links into main whose targets moved in the Fern migration (5 hits, 5 files): Repointed at the release tree, the same fix #12618 applies on release/1.4.0. All four targets verified present on release/1.3.1: docs/kubernetes/installation-guide.md docs/benchmarks/embedding_cache.md docs/features/multimodal/multimodal-vllm.md examples/backends/trtllm/mm_router_worker/README.md Docs-site URL that never existed (2 hits, README.md): https://docs.nvidia.com/dynamo/design-docs/disaggregated-serving 404s. The page is in-repo and named disagg-serving.md, so both table links now point at docs/design-docs/disagg-serving.md on the release tree. Not addressed: a kubebuilder.io request timeout in docs/kubernetes/webhooks.md, which is a flake rather than a broken link. Signed-off-by: Dan Gil <dagil@nvidia.com>
| ## Results | ||
|
|
||
| Full result tables are reproduced below from the [source study](https://github.com/ai-dynamo/dynamo/blob/main/docs/benchmarks/embedding_cache.md); the headline numbers: | ||
| Full result tables are reproduced below from the [source study](https://github.com/ai-dynamo/dynamo/blob/release/1.3.1/docs/benchmarks/embedding_cache.md); the headline numbers: |
There was a problem hiding this comment.
🟡 Documentation pages link to other documentation pages with full web addresses instead of in-repo paths
Two documentation pages now point at other documentation pages through absolute github.com addresses pinned to a release branch (blob/release/1.3.1/docs/... at docs/benchmarks/qwen3-6-35b-feature-stack.mdx:28), instead of the required in-repo relative path, so readers get bounced out of the docs site and the links go stale as soon as the branch name changes.
Impact: Readers clicking these links leave the documentation site for raw files on GitHub, and the links will point at outdated content once the release branch moves on.
Style rule for links inside docs/
docs/AGENTS.md states: "Links: relative + extension within docs/; absolute github.com/ai-dynamo/dynamo URLs for targets outside docs/". Both changed links target files inside docs/:
docs/benchmarks/qwen3-6-35b-feature-stack.mdx:28→docs/benchmarks/embedding_cache.md(should be./embedding_cache.md)docs/benchmarks/qwen3-vl-embedding-cache.mdx:97→docs/features/multimodal/multimodal-vllm.md#embedding-cache(should be../features/multimodal/multimodal-vllm.md#embedding-cache)
The rest of docs/ follows the relative convention (e.g. docs/benchmarks/benchmarking.md:107 uses ../kubernetes/installation-guide.md). The links in recipes/qwen3-vl-30b/README.md:51 and deploy/helm/charts/platform/templates/NOTES.txt:30 are outside docs/, so absolute URLs are correct there.
| Full result tables are reproduced below from the [source study](https://github.com/ai-dynamo/dynamo/blob/release/1.3.1/docs/benchmarks/embedding_cache.md); the headline numbers: | |
| Full result tables are reproduced below from the [source study](./embedding_cache.md); the headline numbers: |
Was this helpful? React with 👍 or 👎 to provide feedback.
| | | [SGLang](https://docs.nvidia.com/dynamo/backends/sg-lang) | [TensorRT-LLM](https://docs.nvidia.com/dynamo/backends/tensor-rt-llm) | [vLLM](https://docs.nvidia.com/dynamo/backends/v-llm) | | ||
| |---|:----:|:----------:|:--:| | ||
| | [**Disaggregated Serving**](https://docs.nvidia.com/dynamo/design-docs/disaggregated-serving) | ✅ | ✅ | ✅ | | ||
| | [**Disaggregated Serving**](https://github.com/ai-dynamo/dynamo/blob/release/1.3.1/docs/design-docs/disagg-serving.md) | ✅ | ✅ | ✅ | |
There was a problem hiding this comment.
🔍 Feature-matrix row now leaves the docs site for a raw GitHub markdown file
Every other row in this table (and the Core Capabilities table at README.md:93-100) links to docs.nvidia.com/dynamo/.... Fern derives page slugs from the nav page: title, and docs/index.yml:482-483 declares page: Disaggregated Serving → path: design-docs/disagg-serving.md, which implies the docs-site slug is design-docs/disaggregated-serving — exactly the URL being removed here. Compare README.md:87 (design-docs/overall-architecture) whose file is design-docs/architecture.md, confirming the title-derived slug pattern. The 404 the PR observed may therefore be because the 1.3.1 docs version hasn't been published yet rather than because the URL 'never existed'. Worth confirming before permanently downgrading two prominent README links to raw GitHub markdown, which reads worse for users and pins them to a branch that will eventually be superseded.
Was this helpful? React with 👍 or 👎 to provide feedback.
Summary
lycheefails on every PR againstrelease/1.3.1. The 15 errors fall into three unrelated classes; all are fixed here, and every replacement URL was verified to return 200.communityinviter.com/apps/cloud-native/cncf404s. Replaced withhttps://slack.cncf.io/mainwhose targets moveddocs.nvidia.com/dynamo/design-docs/disaggregated-serving404s; the page is in-repo asdisagg-serving.mdDetail
CNCF invite —
CONTRIBUTING.md,docs/contribution-guide.md,docs/contribution-guide.zh-CN.md. The old invite URL is dead upstream;slack.cncf.iois the current entry point.Moved doc links — the Fern migration restructured these paths on
main, so release-branch files linking intomainnow 404. This is the same fix #12618 applies onrelease/1.4.0. All four targets were verified present onrelease/1.3.1before repointing:deploy/helm/charts/platform/templates/NOTES.txt->docs/kubernetes/installation-guide.mddocs/benchmarks/qwen3-6-35b-feature-stack.mdx->docs/benchmarks/embedding_cache.mddocs/benchmarks/qwen3-vl-embedding-cache.mdx->docs/features/multimodal/multimodal-vllm.md#embedding-cachedocs/features/multimodal/multimodal-kv-routing.md->examples/backends/trtllm/mm_router_worker/README.md(2 links)recipes/qwen3-vl-30b/README.md->docs/features/multimodal/multimodal-vllm.md#embedding-cacheDisaggregated serving — both
README.mdtable links pointed at a docs-site path that has never resolved. The page exists in-repo asdocs/design-docs/disagg-serving.md, so they now point there on the release tree.Not addressed
A
kubebuilder.iorequest timeout indocs/kubernetes/webhooks.md. That is a flake, not a broken link, and fixing it is not in scope.Test plan
lycheepasses onrelease/1.3.1