Introduzione

Zenzic è un analizzatore statico di classe ingegneristica per documentazione basata su Markdown.

A differenza dei linter tradizionali che controllano la prosa o dei link-checker generici che scansionano l'HTML generato, Zenzic opera nel "Build-Aware Gap": il momento critico tra la scrittura dei file sorgente e la loro trasformazione in un sito web.

Perché esiste Zenzic

Il progetto è nato da un'osservazione strutturale: gli ecosistemi di strumenti per la documentazione sono intrinsecamente instabili. I motori di build introducono breaking change, i formati di configurazione cambiano e i team migrano tra generatori. Affidarsi all'output di build per la garanzia della qualità è un rischio strategico.

Zenzic fornisce un Porto Sicuro per i tuoi contenuti costruendo una Virtual Site Map (VSM) direttamente dal sorgente Markdown grezzo. Questo garantisce che la tua documentazione rimanga valida e sicura, indipendentemente dal motore di build (Docusaurus, MkDocs o Zensical) che utilizzi.

Pilastri Fondamentali

1. Analizza il Sorgente, non la Build: Agnostico rispetto al generatore di siti statici.
2. Pure Python (Zero Sottoprocessi): Nessuna dipendenza esterna, 100% portabile e sicuro.
3. Lo Scudo della Sentinella: Scansione integrata per credenziali e probe dei percorsi host.
4. Intelligenza del Grafo: Complessità $O(V+E)$ per il rilevamento dei cicli di link.

"Il Codice è Legge. La Documentazione è Verità. La Sentinella è vigile."

---

Installazione

Zero-install (consigliato per CI)

Esegui Zenzic su qualsiasi progetto senza installazione tramite uvx:

uvx zenzic check all

uvx risolve ed esegue Zenzic in un ambiente isolato. Non è necessaria alcuna configurazione di ambiente virtuale.

Installazione persistente

pip install zenzic

Con il plugin nativo MkDocs

Per usare ZenzicPlugin all'interno di mkdocs build, installa l'extra opzionale [mkdocs]:

pip install "zenzic[mkdocs]"

Questo aggiunge mkdocs>=1.6.1 come dipendenza e abilita l'entry point zenzic.integrations.mkdocs. Consulta la panoramica dell'ecosistema per il modello completo Adapter vs. Integrazione.

---

Quick Start

1. Crea un file zenzic.toml nella radice del repository:

docs_dir = "docs"

[build_context]
engine = "docusaurus"   # oppure: mkdocs | zensical | vanilla

2. Esegui tutti i controlli:

zenzic check all

3. Interpreta il codice di uscita:

Codice	Significato
0	Pulito — nessun problema rilevato
1	Risultati — problemi di qualità della documentazione rilevati
2	Shield — credenziale esposta rilevata (mai sopprimibile)
3	Blood Sentinel — tentativo di path traversal rilevato (mai sopprimibile)