docs-site/link-check

Validation of the links emitted by the built documentation HTML.

Internal (same-site) links are validated offline: every href/src must resolve to a real file in the build output, and every #fragment must resolve to a real element id on the target page.

External links can only be validated over the network, so those requests are heavily deduplicated — each unique external URL is fetched at most once regardless of how many of the thousands of generated pages reference it — and run through a bounded concurrency pool.

Interfaces

Interface	Description
BrokenLink	A single link that does not resolve.
CollectBrokenExternalLinksOptions	Options for collectBrokenExternalLinks.
DocumentationPage	A single built documentation page to validate.
ExternalLinkProbeResult	What one probe of an external URL learned.
ExternalLinkRetryOptions	How collectBrokenExternalLinks retries a transient failure: a network failure, an HTTP 429 or an HTTP 5xx. Each wait doubles from ExternalLinkRetryOptions.initialDelayInMilliseconds up to ExternalLinkRetryOptions.maxDelayInMilliseconds, is jittered into its upper half, and is never shorter than the server’s Retry-After. The waits of one URL never add up to more than ExternalLinkRetryOptions.totalBudgetInMilliseconds; the status of the last attempt is final.
LinkCheckFileSystem	Filesystem access the link checker needs, injected so the pure decision logic can be tested against an in-memory stub instead of a real build output.

Functions

Function	Description
collectBrokenExternalLinks	Validates the deduplicated external URLs over the network through a bounded concurrency pool. A network failure, an HTTP 429 and an HTTP 5xx are retried with an exponential, jittered backoff that honors Retry-After (see ExternalLinkRetryOptions); any other status, a 404 included, is final at once. Probes of one host are also capped at CollectBrokenExternalLinksOptions.perHostConcurrency, and a probe of another host is started while one host is at its cap.
collectBrokenLinks	Finds every internal link across the built documentation pages that does not resolve. External and non-HTTP links are ignored. Each internal link must resolve to an existing page, and each #fragment must resolve to an existing element id on the target page.
collectExternalTargets	Collects every unique external URL referenced across the built pages, deduplicated. Only HTTP(S) links that are not isInternalDocUrl are returned. Each unique URL maps to the first page that referenced it, so a later failure can be reported with a concrete example page even though the URL is fetched only once.
extractIds	Extracts the values of every id attribute in a chunk of HTML.
extractLinks	Extracts the values of every href/src attribute in a chunk of HTML.
formatBrokenLinks	Formats broken links into a human-readable multi-line report.
getOutputRelativePath	Computes the build-output-relative path for an internal documentation URL.
getPageUrl	Computes the absolute URL a built page is served at.
isInternalDocUrl	Determines whether a resolved link points at a page hosted by this documentation site.
parseRetryAfterInMilliseconds	Reads an HTTP Retry-After header, which is either a number of seconds or an HTTP date.
resolveWithinRoot	Resolves an output-relative path to an absolute path inside the build-output root, rejecting paths that escape it via .. segments.

Variables

Variable	Description
DEFAULT_EXTERNAL_LINK_PER_HOST_CONCURRENCY	The default CollectBrokenExternalLinksOptions.perHostConcurrency. A documentation site links thousands of pages of its sibling sites, all on one host, and GitHub Pages answers a burst of them with a 503.
DEFAULT_EXTERNAL_LINK_RETRY_INITIAL_DELAY_IN_MILLISECONDS	The default ExternalLinkRetryOptions.initialDelayInMilliseconds.
DEFAULT_EXTERNAL_LINK_RETRY_MAX_DELAY_IN_MILLISECONDS	The default ExternalLinkRetryOptions.maxDelayInMilliseconds.
DEFAULT_EXTERNAL_LINK_RETRY_TOTAL_BUDGET_IN_MILLISECONDS	The default ExternalLinkRetryOptions.totalBudgetInMilliseconds.
NETWORK_FAILURE_STATUS	The BrokenLink.httpStatus sentinel for a network-level failure (timeout, DNS, connection refused) where no HTTP response was received.