Skip to main content

Z406-nav-contract — Navigation Contract Violation

Z-Code: Z406 NAV_CONTRACT · Engine: mkdocs · Exit: 1

zenzic check all
mkdocs - 2 files (2 docs, 0 assets) - 0.0s - 109 files/s
docs/(nav)
✘[Z406]mkdocs.yml extra.alternate[it]: link '/it/' does not correspond to any URL the build engine will generate. The Virtual Site Map contains no entry for '/it/'. Use a path that maps to an existing source file (e.g. '/index.it/' for the it home page).
────────────────────────────────────────────────────────────────────────────────
Summary:✘ 1 error⚠ 0 warningsℹ 0 info- 1 file with findings
FAILED: Hard errors detected. Exit code 1 is mandatory.
Refer to https://zenzic.dev/docs/reference/finding-codes for remediation · Try
'zenzic check --help' for options.
🔒 Suppression Audit: 0/30 (inline: 0, per-file: 0)
exit 1

The Fixture​

The fixture lives at examples/z406-nav-contract/ in the Zenzic repository. It uses the MkDocs engine.

mkdocs.yml declares extra.alternate with an Italian locale link /it/, but there are no Italian source pages (no docs/*.it.md or docs/it/ subtree). The route /it/ is therefore absent from the Virtual Site Map:

examples/z406-nav-contract/mkdocs.yml
site_name: My Project
extra:
  alternate:
    - name: English
      link: /
      lang: en
    - name: Italiano
      link: /it/
      lang: it
examples/z406-nav-contract/.zenzic.toml
docs_dir = "docs"
fail_under = 0

[build_context]
engine = "mkdocs"

Running the Example​

# Clone the Zenzic repository — no install required
cd examples/z406-nav-contract
uvx zenzic check all

Expected output:

mkdocs · 2 files (2 docs, 0 assets) · 0.0s · 109 files/s

docs/(nav)  x  [Z406]  mkdocs.yml extra.alternate[it]: link '/it/' does not
correspond to any URL the build engine will generate. The Virtual Site Map
contains no entry for '/it/'. Use a path that maps to an existing source file
(e.g. '/index.it/' for the it home page).

────────────────────────────────────────────────────────────────────────────────

Summary:  x 1 error  ! 0 warnings  i 0 info  · 1 file with findings

FAILED: Hard errors detected. Exit code 1 is mandatory.

Exit code: 1

Interpreting the Output​

The Z406 finding indicates a NAV_CONTRACT violation.

Zenzic builds a Virtual Site Map (VSM) — the complete set of URLs the documentation engine will generate from the source tree. Every URL declared in extra.alternate must exist in the VSM; if it does not, clicking the language switcher produces a 404:

  • Scan Type: Nav Contract Checker (mkdocs engine)
  • Severity: Error
  • Impact: Deducts 2.0 DQS points (brand governance category, weight 0.25).

Resolve the Issue​

Option A — Create the missing locale content:

# Create the Italian home page (MkDocs suffix-locale convention)
cp docs/index.md docs/index.it.md
# Translate the content, then re-run zenzic check all

Option B — Remove the broken alternate entry:

extra:
  alternate:
    - name: English
      link: /
      lang: en
-   - name: Italiano
-     link: /it/
-     lang: it

See Also​