Passa al contenuto principale

Installa Zenzic

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.

Installazione​

Temporanea — nessuna installazione richiesta​

uvx 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 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 zenzic
uvx 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.

Solo analisi statica — nessun runtime di build richiesto​

Zenzic legge i file di configurazione (mkdocs.yml, zensical.toml, pyproject.toml) come testo statico. Non esegue il motore di build né i suoi plugin.

Non installare MkDocs, Material for MkDocs o alcun plugin di build nell'ambiente di linting. Non servono. L'ambiente di linting ha una sola dipendenza: zenzic.

# Fare il lint di qualsiasi progetto MkDocs — nessun extra necessario
uvx 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 StandaloneAdapter (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 identifica il motore di documentazione dai file di configurazione presenti 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à Standalone). 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 seleziona un adapter in base al file di configurazione del motore di build presente nella root del repository. La modalità Engine-aware si attiva quando viene trovato mkdocs.yml o zensical.toml, abilitando il rilevamento degli orfani basato sulla nav, la risoluzione del fallback i18n, la soppressione delle directory locale e il tracciamento delle Ghost Route. La modalità Standalone si attiva quando non viene trovata alcuna configurazione del motore — il controllo degli orfani viene saltato perché senza una dichiarazione nav ogni file sembrerebbe orfano.

Usa --engine per sovrascrivere l'adapter rilevato per una singola esecuzione senza modificare .zenzic.toml.

Per il razionale di design completo dietro la modalità engine-aware rispetto a standalone, vedi Architettura — Sovereign CLI.

Dismissione di Zenzic​

Se hai bisogno di rimuovere Zenzic dal tuo progetto, il processo di dismissione richiede meno di 30 secondi e non lascia tracce.

Passo 1 — Rimuovere da CI/CD​

Elimina il blocco di Zenzic dai tuoi file di workflow (ad es., .github/workflows/docs.yml):

- uses: PythonWoods/zenzic-action@<version>
  with:
    version: "<version>"
    format: sarif
    upload-sarif: "true"

O, se eseguito direttamente in uno step shell:

- name: Zenzic
  run: uvx zenzic check all

Passo 2 — Rimuovere la configurazione​

Elimina il file di configurazione dal tuo repository:

rm .zenzic.toml
# OPPURE modifica pyproject.toml e rimuovi la sezione [tool.zenzic]

Prossimi passi: