Passa al contenuto principale

Z103-orphan-link — Link Orfano

Z-Code: Z103 ORPHAN_LINK · Engine: zensical · Exit: 1

zenzic check links
zensical - 2 files (2 docs, 0 assets) - 0.0s - 101 files/s
docs/guide.md
⚠[Z402]Physical file not listed in navigation.
docs/index.md:16:2
✘[Z101]'guide.md' resolves to '/guide/' which exists on
disk but is not listed in the site navigation (UNREACHABLE_LINK) — add it to nav
in mkdocs.yml or remove the link
14│ The following link points to a page that exists on disk but has no
nav entry:
15│
16❱- [Guide](guide.md) — `guide.md` exists on disk, but it is **not in
the nav** → **Z103**
│ ^^^^^^^^^^^^^^^^^
17│
18│ ## What Zenzic Reports
────────────────────────────────────────────────────────────────────────────────
Summary:✘ 1 errors⚠ 1 warningsℹ 0 info- 2 files 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/z103-orphan-link/ nel repository Zenzic. Contiene due documenti e due file di configurazione:

FileRuolo
docs/index.mdSorgente — in nav, rimanda a guide.md alla riga 16
docs/guide.mdDestinazione — esiste su disco, non in nav
.zenzic.tomlConfigurazione engine (zensical), fail_under = 0
zensical.tomlDichiarazione nav — guide.md deliberatamente escluso

zensical.toml dichiara una nav con solo index.md. Il file guide.md esiste su disco ma non ha alcuna voce di navigazione — il suo stato VSM è ORPHAN_BUT_EXISTING. Quando index.md rimanda a esso alla riga 16, la VSMBrokenLinkRule di Zenzic attiva Z103: il link aggira la navigazione e rende la pagina raggiungibile solo via URL diretto.

examples/z103-orphan-link/zensical.toml
[project]
site_name = "Z103 Example"
docs_dir  = "docs"
nav = [
    "index.md",
]

Eseguire l'Esempio​

# Clona il repository Zenzic — nessuna installazione richiesta
cd examples/z103-orphan-link
uvx zenzic check links

Expected output:

zensical - 2 files (2 docs, 0 assets) - 0.0s - 103 files/s

docs/guide.md  !  [Z402]  Physical file not listed in navigation.

docs/index.md:16:2  x  [Z101]  'guide.md' resolves to '/guide/' which exists on 
disk but is not listed in the site navigation (UNREACHABLE_LINK) — add it to nav
in mkdocs.yml or remove the link

    14  │  The following link points to a page that exists on disk but has no 
nav entry:
    15  │  
    16  ❱  - [Guide](guide.md) — `guide.md` exists on disk, but it is **not in 
the nav** → **Z103**
        │    ^^^^^^^^^^^^^^^^^
    17  │  
    18  │  ## What Zenzic Reports

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

Summary:  x 1 error  ! 1 warning  i 0 info  - 2 files 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 code: 1

Interpretare l'Output​

Il codice di errore Z103 indica un problema di tipo ORPHAN_LINK.

Questo errore o avviso viene generato da Zenzic quando una pagina markdown esiste ed è collegata tramite link, ma la destinazione del link non è raggiungibile tramite la struttura di navigazione principale del sito (es. omessa dalla sidebar). In questo esempio specifico:

  • Tipo di Scansione: Link Validator
  • Severità: Error
  • Impatto: I link orfani possono creare sezioni isolate di contenuto e comportano una detrazione DQS di 2.0 punti.

Correggere la Violazione​

Aggiungi guide.md alla nav in zensical.toml:

zensical.toml (dopo la correzione)
[project]
site_name = "Z103 Example"
docs_dir  = "docs"
nav = [
    "index.md",
    "guide.md",
]

Poi riesegui:

uvx zenzic check links  # → exit 0, nessun finding

In alternativa, rimuovi il link [Guide](guide.md) da index.md se la pagina è intenzionalmente non pubblicata.

Vedi Anche​