[akira28]

The assembler now checks links from narrative docs and redirects.yml into /docs/api/doc/... against the API pages it generated, and warns about each link that does not resolve.

Affects: Assembler builds, API reference, Authoring

Prompt summary: Implement link checking for the API docs from elastic/docs-eng-team#997. Links into the auto-generated API reference can disappear without notice, for example when an endpoint is discontinued, and nothing validates them today. Report broken links as warnings plus a report file, and check page existence only.

Why

https://www.elastic.co/docs/api/doc/... links pass through the Markdown build unchecked, and redirect targets with :// are only parsed as URIs. API pages come from external specs, so an endpoint can vanish and the links to it break with no signal.

What

Recording API links

Links are recorded where they are parsed: the inline link parser, the autolink parser and DirectiveLinkValidator, which hero actions, card targets and card intros all pass through. Every page, including API children: pages and snippets, reaches these parsers, so each link is recorded with its file, line and column. Links inside API descriptions, which parse without link validation, are recorded in HtmlWriter.RenderApiDescription through OutboundLinkExtractor and reported against the page's description. Redirect targets in redirects.yml are recorded separately and reported against that file. ApiLinkMatcher normalizes each URL by dropping the query and fragment, collapsing repeated slashes, trimming the trailing slash and lowercasing it.

Generated page set

OpenApiGenerator.GeneratedUrls collects every page the generator renders, across all version trees, plus the redirect stubs for collapsed operations and the .json and .yaml spec downloads. URLs are recorded under /docs whatever path prefix the build uses, so PR previews compare like with like. AssemblerOpenApiBuildStep returns the union of these sets with the catalog entries.

Validation and report

After the API step, ApiLinkValidator compares recorded links with the generated set. It follows the old bump.sh redirects the edge serves (ApiLegacyRedirects, mirrored from docs-infra and shared with ApiSitemapParityTests) before comparing, reports each URL once per file, warns per broken link and writes api-link-report.json next to redirects.json. The path is also a GitHub Actions output, api-link-report-path. The step is skipped when the API Explorer produced no pages, so builds with the flag off are unchanged.

Out of scope: #anchor checking, links from product source code, and probing production URLs.

Verify

dotnet test tests/Elastic.Documentation.Tests
dotnet test tests/Elastic.Markdown.Tests --treenode-filter "/*/*/*ApiLink*/*"
dotnet test tests/Elastic.Documentation.Build.Tests --treenode-filter "/*/*/ApiLinkValidatorTests/*"
dotnet test tests/Elastic.ApiExplorer.Tests --treenode-filter "/*/*/OpenApiGeneratorCatalogSplitTests/GenerateProducts_Records*"

Closes elastic/docs-eng-team#997

🤖 Generated with Claude Code

[github-actions]

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4653/

Sample changed pages:

• docs/syntax/links.md

[infra-vault-gh-plugin-prod]

Severity: P2 (Medium)

RenderApiDescription runs on every page that shows a shared description, such as a schema, parameter or response description. Each call passes a different virtual description.md path (one per page URL), so the (Url, File) dedupe in ApiLinkValidator keeps every copy. One broken link in a shared spec description then produces a warning on every operation page that renders it, which can be hundreds of near-identical warnings, and it inflates checked in the report. Each warning also points at line 1 of a file in the output directory that doesn't exist. Dedupe description links by URL plus spec or product root, or record them once per description text, rather than once per rendering page.

_{Generated by Libra. Specialist: libra-complexity. React with 👍 or 👎 to give feedback on this comment.}

[infra-vault-gh-plugin-prod]

Severity: P2 (Medium)

Include raw HTML anchor targets when recording description links. ApiDescriptionPipeline supports <a href="..."> links, but OutboundLinkExtractor only collects Markdown link nodes and directive targets, so an HTML link to a missing API page never reaches the validator and produces neither a warning nor a report entry.

_{Generated by Libra. React with 👍 or 👎 to give feedback on this comment.}