Skip to content

Z103: ORPHAN_LINK

  • Severity: Error

    Penalty: 0.0 points | Category: general

  • Remediation & Opt-In

    Auto-Fixable: No | Opt-In: No

Rationale

This rule is triggered when a link references a Markdown file that exists on the local filesystem disk but is omitted from the site navigation tree (mkdocs.yml).

While the target file is physically present, the static site generator will not build or serve it. Linking to it creates a dead-end experience for users.

How to Fix

Inspect the flagged location in the Markdown file and update the content or configuration:

  • Failing Pattern (Triggers Z103)

    docs/example.md
    <!-- BAD: Linking to an unlisted draft file -->
Check the [Draft Architecture](../../drafts/arch-v2.md).

  • Passing Pattern (Resolves Z103)

    docs/example.md
    <!-- GOOD: Link to a file registered in site navigation -->
Check the [Architecture Explanation](../explanation/architecture.md).

Configuration

# mkdocs.yml - Ensure target document is listed under nav
nav:
  - Architecture: explanation/architecture.md

Reference

See the Finding Codes Index for finding code details.