Checks

The five built-in checks and their shared base class. See The Five Checks for what each one flags.

Base

class markdown_checker.checks.base.BaseCheck

Bases: Generic[TLink], ABC

Abstract base class for all link checks.

name: str

The CLI --func value and REGISTRY key that selects this check, e.g. "check_broken_paths".

Which half of a file’s extracted links this check consumes: "paths" for links.paths, "urls" for links.urls.

abstractmethod run(links, config=None, service=None)

Run the check against the extracted links.

Parameters:

  • links (MarkdownLinks) – Extracted URLs and paths from a file.

  • config (Config | None) – Runtime configuration for the check run.

  • service (URLCheckService | None) – Optional shared URL-checking pipeline (dedupe memo, per-host pacing, circuit breaker). Only used by checks with link_type “urls”; ignored otherwise. When None, URL checks fall back to a private, run-scoped service instance.

Returns:

List of links that failed the check, each with an .issue set.

Return type:

list[TLink]

submit(links, config=None, service=None)

Begin checking without blocking the caller, returning an opaque “pending” token to be finished later via collect().

The default implementation simply runs the check synchronously and hands the finished result to collect() unchanged - appropriate for checks with no network I/O to overlap with other files. Checks that can hand work off to a shared service (e.g. URL checks) should override both submit() and collect() to split the non-blocking submission from the blocking wait for results.

Parameters:

  • links (MarkdownLinks) – Extracted URLs and paths from a file.

  • config (Config | None) – Runtime configuration for the check run.

  • service (URLCheckService | None) – Optional shared URL-checking pipeline.

Returns:

An opaque token to pass to collect().

Return type:

object

collect(pending)

Resolve a pending token from submit() into final results.

Parameters:

pending (object) – The token returned by a matching submit() call.

Returns:

List of links that failed the check, each with an .issue set.

Return type:

list[TLink]

Broken Paths

The check_broken_paths check: flags relative/root-relative paths that don’t exist on disk.

class markdown_checker.checks.broken_paths.BrokenPathsCheck

Bases: BaseCheck[MarkdownPath]

Check for relative paths in markdown files that do not exist on disk.

name: str

The CLI --func value and REGISTRY key that selects this check, e.g. "check_broken_paths".

Which half of a file’s extracted links this check consumes: "paths" for links.paths, "urls" for links.urls.

run(links, config=None, service=None)

Flag every path in links.paths whose target does not exist on disk (see MarkdownPath.exists), setting issue="is broken" (error-level) on each. config and service are unused: this check does no network I/O.

Parameters:
Return type:

list[MarkdownPath]

Broken URLs

The check_broken_urls check: flags URLs that don’t return a 2xx response.

class markdown_checker.checks.broken_urls.BrokenURLsCheck

Bases: BaseCheck[MarkdownURL]

Check for URLs in markdown files that return non-2xx responses.

name: str

The CLI --func value and REGISTRY key that selects this check, e.g. "check_broken_paths".

Which half of a file’s extracted links this check consumes: "paths" for links.paths, "urls" for links.urls.

submit(links, config=None, service=None)

Filter out skipped domains/URLs, then hand each remaining URL to service (or a private, run-scoped service when service is None) without blocking. Returns a _Pending token - the (url, Future) pairs plus the owned service, if any - for collect() to resolve later.

Parameters:
Return type:

object

collect(pending)

Block on every Future produced by submit(), map each result to an issue via _to_issue(), and close the service if this check owns it (i.e. no shared service was passed to submit).

Parameters:

pending (object)

Return type:

list[MarkdownURL]

run(links, config=None, service=None)

Synchronous convenience wrapper: collect(submit(...)). Used by callers (and tests) that don’t need submit/collect overlap across files.

Parameters:
Return type:

list[MarkdownURL]

Locale

The check_urls_locale check: flags URLs containing a locale segment (e.g. /en-us/).

class markdown_checker.checks.locale.URLsLocaleCheck

Bases: BaseCheck[MarkdownURL]

Check that URLs do not contain a country/language locale segment.

name: str

The CLI --func value and REGISTRY key that selects this check, e.g. "check_broken_paths".

Which half of a file’s extracted links this check consumes: "paths" for links.paths, "urls" for links.urls.

run(links, config=None, service=None)

Flag every URL in links.urls whose path contains a locale segment (see MarkdownLinkBase.has_locale), unless its host is in config.skip_domains, _BUILTIN_SKIP_DOMAINS, or its URL matches config.skip_urls_containing. Sets issue="has locale" (error-level) on each match. service is unused: this check does no network I/O.

Parameters:
Return type:

list[MarkdownURL]

Tracking

The check_urls_tracking/check_paths_tracking checks: flag links missing a wt.mc_id tracking ID.

class markdown_checker.checks.tracking.URLsTrackingCheck

Bases: BaseCheck[MarkdownURL]

Check that URLs on configured tracking domains include a tracking ID.

name: str

The CLI --func value and REGISTRY key that selects this check, e.g. "check_broken_paths".

Which half of a file’s extracted links this check consumes: "paths" for links.paths, "urls" for links.urls.

run(links, config=None, service=None)

Flag every URL in links.urls whose host matches config.tracking_domains but is missing a wt.mc_id query parameter (see MarkdownLinkBase.has_tracking). URLs on other hosts, or matching config.skip_domains/ skip_urls_containing, are ignored. Sets issue="is missing tracking id" (error-level) on each match. service is unused: this check does no network I/O.

Parameters:
Return type:

list[MarkdownURL]

class markdown_checker.checks.tracking.PathsTrackingCheck

Bases: BaseCheck[MarkdownPath]

Check that relative paths include a tracking ID.

name: str

The CLI --func value and REGISTRY key that selects this check, e.g. "check_broken_paths".

Which half of a file’s extracted links this check consumes: "paths" for links.paths, "urls" for links.urls.

run(links, config=None, service=None)

Flag every path in links.paths missing a wt.mc_id query parameter (see MarkdownLinkBase.has_tracking), setting issue="is missing tracking id" (error-level) on each. Unlike check_urls_tracking, there is no domain filter: every path is checked. config and service are unused.

Parameters:
Return type:

list[MarkdownPath]