Skip to content

ci(docs): check links on the built site and repair existing ones - #777

Open
bartoszmajsak wants to merge 4 commits into
kserve:mainfrom
bartoszmajsak:upstream/ci/feat/documentation-links
Open

bartoszmajsak wants to merge 4 commits into
kserve:mainfrom
bartoszmajsak:upstream/ci/feat/documentation-links

Conversation

@bartoszmajsak

Copy link
Copy Markdown
Contributor

Docusaurus only checks Markdown links and <Link>. Raw <a href>, anchors (onBrokenAnchors is warn), external URLs and self links like /website/master/... go unchecked, so they break on the live site first. An audit of the current site found 101 broken internal links, 7 missing GitHub targets and 29 external 404s across six doc versions.

Proposed Changes

  • PRs build the site at head and base and fail on a new broken internal link or anchor, a GitHub file verified missing through the API, or a new external URL that returns 404/410 twice. Links resolve the way GitHub Pages serves them, so route-flattening bugs like frameworks/sklearn/sklearn fail. Existing debt never fails a PR.
  • A nightly audit keeps one bot-owned issue: internal and GitHub failures right away, other websites after seven days. Only that job can write issues.
  • The triage modules are vendored from ci(docs): prevent broken links and repair existing references kserve#6568, so both repos follow one policy.
  • Broken links are repaired in every version, including anchors in the generated API references, fixed in their templates.

On a fork at this head, the PR run checks 42 new external URLs with no failures, and the nightly audit covers 964 pages and 1096 external URLs with no internal or GitHub failures. Six injected faults each fail the gate; a text edit on a page with debt and docs:version 0.21 pass.

Seven external 404s stay, in generated SDK reference pages built from upstream docstrings. Two go away with the next SDK doc regen after kserve/kserve#6568; the nightly issue picks up the rest after seven days.

Open question: 8 anchors on the OIP REST pages only exist in upstream inference_rest.md and carry expiring exceptions. Fix them in open-inference-protocol (open_inference_rest.yaml lines 80, 104 and 138), or post-process the generated pages here?

Repair details
  • The gRPC reference template linked A.B as #a-b, but Docusaurus slugs the heading #ab. crd-ref-docs linked Knative, Gateway API and KEDA types to sections that don't exist; they now point to pkg.go.dev.
  • release-<ActiveDocsVersion /> inside a link URL rendered as a truncated tree/release-. Those links now use a small component.
  • /website/master/... self links, mkdocs-era kserve/website/tree/main/docs paths, renamed anchors and moved external pages are updated across docs/, all versioned_docs and the blog.

Follow-up to #695 and #776.

Docusaurus checks Markdown links at build time, but raw <a href> tags,
anchors and external URLs reach the live site unchecked (kserve#695, kserve#776).

Scan the production build as GitHub Pages serves it, and fail PRs only on
failures that a build of the base does not have. A nightly audit keeps one
issue, with the verification, history and triage vendored from
kserve/kserve#6568.

Signed-off-by: Bartosz Majsak <bartosz.majsak@gmail.com>
The gRPC template linked message A.B as #a-b, but Docusaurus slugs that
heading to #ab, and it linked scalars to a table the page never had.
crd-ref-docs linked Knative, Gateway API, GIE and KEDA types to sections
that don't exist, and listed KServe types it never renders.

Signed-off-by: Bartosz Majsak <bartosz.majsak@gmail.com>
(cherry picked from commit c09a124c467c2b1b0f0f8995344000ac85bf63ff)
Self links to /website/master, mkdocs-era repository paths and renamed
headings stopped resolving, and Markdown link URLs cannot embed
<ActiveDocsVersion />, so release links rendered as tree/release-.
Upstream pages moved or were removed (llm-d, vLLM, Knative, Kubeflow).
OIP REST anchors from the upstream spec get expiring exceptions.

Signed-off-by: Bartosz Majsak <bartosz.majsak@gmail.com>
@netlify

netlify Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

👷 Deploy request for elastic-nobel-0aef7a pending review.

Visit the deploys page to approve it

Name Link
🔨 Latest commit 86c8e43

@greptile-apps

greptile-apps Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The latest changes appear safe to merge.

Summary

Adds checks for links in the built website and repairs links across current and versioned docs.

  • Pull requests check links on the built site without failing on old issues.
  • Nightly audits track link failures and update one documentation issue.
  • Documentation links now point to current pages, files, and headings.
  • Generated API references link to valid sections and external type definitions.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Build head site] --> C[Scan built links]
  B[Build base site for PRs] --> D[Scan baseline links]
  C --> E[Check links and apply exceptions]
  D --> E
  E --> F[Fail PR on new broken links]
  E --> G[Nightly audit report]
  G --> H[Trusted job updates history and issue]
Loading

Reviews (2) · Last reviewed commit: "fix(ci): report links with an invalid po..." · Reviewed by Greptile

Comment thread hack/linkcheck/github.py Resolved
| [Inspur](https://www.inspur.com/) | [Qingshan Chen](https://github.com/iamlovingit) | | |
| [Intuit](https://www.intuit.com/) | [Rachit Chauhan](https://github.com/rachitchauhan43) | | |
| [Kubeflow](https://www.kubeflow.org/) | [Yuan Tang](https://github.com/terrytangyuan) | [KServe Integration](https://www.kubeflow.org/docs/external-add-ons/kserve/) | Production |
| [Kubeflow](https://www.kubeflow.org/) | [Yuan Tang](https://github.com/terrytangyuan) | [KServe Integration](https://www.kubeflow.org/docs/ecosystem/kserve/) | Production |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

extra tab

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a tab, just spaces - the new URL is shorter, so the padding keeps the column as wide as in the other rows.

| [Red Hat](https://www.redhat.com/) | [Yuan Tang](https://github.com/terrytangyuan) | [Red Hat OpenShift AI](https://www.redhat.com/en/technologies/cloud-computing/openshift/openshift-ai), [KubeCon Talk](https://youtu.be/oVJXnlrSuDE?si=doDtv2Ajcvg4fzH7), [Blogpost](https://developers.redhat.com/articles/2024/03/15/empower-conversational-ai-scale-kserve) | Production |
| [SAP](https://www.sap.com) | [Lize Cai](https://github.com/lizzzcai) | [Adopter Interview with CNCF](https://github.com/cncf/toc/blob/main/projects/kserve/kserve-adopter-interview-sap.md) | Production |
| [Seldon](https://www.seldon.io/) | [Alex Housley](https://github.com/ahousley) | | |
| [Seldon](https://seldon.io/) | [Alex Housley](https://github.com/ahousley) | | |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here, padding for the shorter URL.

```

You can find [the code example](https://github.com/kserve/kserve/tree/release-<ActiveDocsVersion />/docs/samples/v1beta1/triton/torchscript/image_transformer_v2) and [Dockerfile](https://github.com/kserve/kserve/blob/release-<ActiveDocsVersion />/docs/samples/v1beta1/triton/torchscript/transformer.Dockerfile) in the KServe repository.
You can find [the code example](https://github.com/kserve/kserve/tree/v0.9.0/docs/samples/v1beta1/triton/torchscript/image_transformer_v2) and [Dockerfile](https://github.com/kserve/kserve/blob/v0.9.0/docs/samples/v1beta1/triton/torchscript/transformer.Dockerfile) in the KServe repository.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

any reason to pin to a specific version?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sample was removed from kserve in kserve/kserve#2629, so it is gone since v0.10.0 and v0.9.0 is the last tag that has it. Before this change the link rendered as a truncated tree/release-, so it never worked. We could also drop the sentence, since the code is inline above. WDYT?

## References

* [Modelcar Design document](https://docs.google.com/document/d/1Bs4fnP8rhPMaoPoLSYVvuRq-z9vkGPQ0rKbmfH4I7js/edit#heading=h.xw1gqgyqs5b)
* [Modelcar Design document (archived)](https://web.archive.org/web/20241118173548if_/https://docs.google.com/document/d/1Bs4fnP8rhPMaoPoLSYVvuRq-z9vkGPQ0rKbmfH4I7js/edit)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we keep it?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would keep it. The original doc is deleted (Google returns 410), and the archived copy still has the full design. Happy to drop it if you would rather not link an archive though.

A rendered href such as `https://host.invalid:99999/doc` raised from the
GitHub target parser and stopped the whole scan. It is now a malformed
URL finding on its page, like an unclosed IPv6 bracket.

Signed-off-by: Bartosz Majsak <bartosz.majsak@gmail.com>

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants