Passa al contenuto principale

Per iniziare

Zenzic legge direttamente dal filesystem e funziona con qualsiasi progetto basato su Markdown. Usalo in locale, come hook di pre-commit, nelle pipeline CI o per audit una-tantum.

Esempi canonici​

Il repository include fixture mantenuti e allineati ai contratti documentati:

  • examples/mkdocs-basic/ — baseline MkDocs 1.6 (nav annidata, link nav esterno, tag YAML tolleranti come !ENV e !relative).
  • examples/i18n-standard/ — gold standard bilingue in strict mode.
  • examples/zensical-basic/ — baseline Zensical v0.0.31+ ([project].nav).
  • examples/broken-docs/ — errori intenzionali (exit 1).
  • examples/security_lab/ — fixture sicurezza (Shield exit 2, Blood Sentinel exit 3).
Vuoi eseguirlo subito?
uvx --pre zenzic check all

Nessuna installazione richiesta. uvx scarica ed esegue Zenzic in un ambiente temporaneo.

Installazione​

Temporanea — nessuna installazione richiesta​

uvx --pre zenzic check all

uvx risolve ed esegue Zenzic da PyPI in un ambiente temporaneo. Nulla viene installato sul sistema. La scelta giusta per audit una-tantum, git hooks e job CI dove si vuole evitare di fissare una dipendenza dev.

Strumento globale — disponibile in ogni progetto​

uv tool install --pre zenzic
zenzic check all

Installa una volta, usa in qualsiasi progetto. Il binario è disponibile nel PATH senza attivare un virtual environment.

Dipendenza dev del progetto — versione fissata per progetto​

uv add --dev --pre zenzic
uv run zenzic check all

Installa Zenzic nel virtual environment del progetto e fissa la versione in uv.lock. La scelta giusta per progetti di team e pipeline CI che installano le dipendenze del progetto prima di eseguire i controlli.

Lean e Agnostico per Design​

Zenzic esegue un'analisi statica dei tuoi file di configurazione (mkdocs.yml, zensical.toml, pyproject.toml). Non esegue il motore di build né i suoi plugin.

Questo significa che non è necessario installare MkDocs, Material for MkDocs o altri plugin di build nel tuo ambiente di linting. Zenzic rimane leggero e privo di dipendenze, rendendolo ideale per pipeline CI/CD veloci e isolate.

# Fare il lint di qualsiasi progetto MkDocs — nessun extra necessario
uvx --pre zenzic check all
Adapter di terze parti

Gli adapter di terze parti (es. un ipotetico zenzic-hugo-adapter) sono pacchetti installabili separati — non extra di zenzic stesso. Nessun extra è richiesto per VanillaAdapter (cartelle Markdown semplici).

Workflow Init → Config → Check​

Il workflow standard per adottare Zenzic in un progetto:

1. Init — scaffolding del file di configurazione​

Crea un zenzic.toml con un singolo comando. Zenzic rileva automaticamente il motore di documentazione e preimposta [build_context] di conseguenza:

zenzic init

Esempio di output quando è presente mkdocs.yml:

Created zenzic.toml
  Engine pre-set to mkdocs (detected from mkdocs.yml).

Edit the file to enable rules, adjust directories, or set a quality threshold.
Run zenzic check all to validate your documentation.

Se non viene rilevato alcun file di configurazione engine, zenzic init produce uno scaffold engine-agnostico (modalità Vanilla). In entrambi i casi, tutte le impostazioni sono commentate per default — decommenta e modifica solo i campi di cui hai bisogno.

Eseguendo Zenzic senza un zenzic.toml, Zenzic utilizza i valori predefiniti e mostra un pannello Helpful Hint che suggerisce zenzic init:

╭─ 💡 Zenzic Tip ─────────────────────────────────────────────────────╮
│ Using built-in defaults — no zenzic.toml found.                      │
│ Run zenzic init to create a project configuration file.              │
│ Customise docs directory, excluded paths, engine adapter, and rules. │
╰──────────────────────────────────────────────────────────────────────╯

2. Config — personalizza per il tuo progetto​

Modifica il zenzic.toml generato per silenziare il rumore e impostare soglie appropriate:

# zenzic.toml — nella root del repository
excluded_assets = [
"assets/favicon.svg",      # referenziato da mkdocs.yml, non da nessuna pagina .md
"assets/social-preview.png",
]
placeholder_max_words = 30     # le pagine di reference tecnico sono intenzionalmente brevi
fail_under = 70                # stabilisce un quality floor iniziale

Consulta la Guida alla Configurazione per l'elenco completo dei campi.

3. Check — esegui in modo continuativo​

Con il baseline stabilito, esegui Zenzic su ogni commit e pull request:

# Hook pre-commit o step CI
# --strict: valida URL esterni + tratta i warning come errori
zenzic check all --strict

# Salva il baseline (punto di riferimento) qualità sul branch main
zenzic score --save

# Blocca le PR che regrediscono il baseline di più di 5 punti
zenzic diff --threshold 5

Modalità engine​

Zenzic opera in una di due modalità a seconda che riesca a trovare un file di configurazione del motore di build:

Modalità Engine-aware​

Quando mkdocs.yml (MkDocs/Zensical) o zensical.toml (Zensical) è presente nella root del repository, Zenzic carica l'adapter corrispondente che fornisce:

  • Consapevolezza della nav — il controllo orfani sa la differenza tra "non nella nav" e "non dovrebbe essere nella nav" (ad esempio i file di locale i18n).
  • Fallback i18n — i link cross-locale vengono risolti correttamente invece di essere segnalati come non validi.
  • Soppressione directory locale — i file sotto docs/it/, docs/fr/, ecc. non vengono segnalati come orfani.

Modalità Vanilla​

Quando non viene trovata alcuna configurazione del motore di build, Zenzic ricade su VanillaAdapter. In questa modalità:

  • Il controllo orfani viene saltato. Senza una dichiarazione di nav, ogni file sembrerebbe un orfano.
  • Tutti gli altri controlli vengono eseguiti normalmente — link, snippet, placeholder, asset e riferimenti.

La modalità Vanilla è la scelta giusta per wiki Markdown semplici, repository GitHub-wiki o qualsiasi progetto dove la navigazione è implicita.

Forza una modalità specifica

Usa --engine per sovrascrivere l'adapter rilevato per una singola esecuzione:

zenzic check all --engine vanilla    # salta il controllo orfani
zenzic check all --engine mkdocs     # forza l'adapter MkDocs

Prossimi passi: