Passa al contenuto principale

Z406-nav-contract — Violazione del Contratto di Navigazione

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

Il Fixture​

Il fixture si trova in examples/z406-nav-contract/ nel repository Zenzic. Utilizza l'engine MkDocs.

mkdocs.yml dichiara extra.alternate con un link in italiano /it/, ma non esistono pagine sorgente in italiano (nessun docs/*.it.md o sottodirectory docs/it/). La rotta /it/ è quindi assente dalla 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"

Eseguire l'Esempio​

# Clona il repository Zenzic — nessuna installazione richiesta
cd examples/z406-nav-contract
uvx zenzic check all

Output atteso:

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

Interpretare l'Output​

Il finding Z406 indica una violazione del NAV_CONTRACT.

Zenzic costruisce una Virtual Site Map (VSM) — il set completo di URL che il motore di documentazione genererà dall'albero sorgente. Ogni URL dichiarato in extra.alternate deve esistere nella VSM; se non esiste, cliccare il selettore di lingua produce un 404:

  • Tipo di scansione: Nav Contract Checker (engine mkdocs)
  • Severità: Error
  • Impatto: Deduce 2.0 punti DQS (categoria brand governance, peso 0.25).

Risolvere il Problema​

Opzione A — Creare il contenuto locale mancante:

# Creare la home page italiana (convenzione suffix-locale MkDocs)
cp docs/index.md docs/index.it.md
# Tradurre il contenuto, poi rieseguire zenzic check all

Opzione B — Rimuovere la voce alternate non valida:

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

Vedi Anche​