Guida alla Configurazione dei Motori

Zenzic è agnostico — funziona con MkDocs, Zensical o una cartella standard di file Markdown senza richiedere l'installazione di alcun framework di build. È anche opinato: quando dichiari un motore, devi dimostrarlo. Questa guida spiega come configurare Zenzic per ogni motore supportato e quali sono le regole.

Portata multi-ecosistema

Zenzic è uno strumento Python, ma la sua portata non è limitata all'ecosistema Python della documentazione. Poiché Zenzic analizza file Markdown sorgente e configurazione come dati semplici — senza mai invocare un motore di build, senza mai importare codice di framework — può validare la documentazione di qualsiasi generatore di siti statici (SSG), indipendentemente dal linguaggio in cui è scritto.

Livello di supporto	Motore	Linguaggio SSG	Come
Nativo	MkDocs	Python	`MkDocsAdapter` — legge `mkdocs.yml`, risolve i18n, impone la nav
Nativo	Zensical	Python	`ZensicalAdapter` — legge `zensical.toml`, zero YAML
Nativo	Docusaurus	Node.js	`DocusaurusAdapter` — legge `docusaurus.config.ts`, risolve i18n
Agnostico	Standalone	qualsiasi	`StandaloneAdapter` — funziona su qualsiasi cartella Markdown; controllo orphan disabilitato
Estensibile	Hugo (esempio)	Go	Adapter di terze parti via entry-point `zenzic.adapters`
Estensibile	Jekyll (esempio)	Ruby	Adapter di terze parti via entry-point `zenzic.adapters`

Le voci "Estensibile" sono esempi di ciò che il sistema di adapter rende possibile — non adapter già distribuiti. Un team che gestisce documentazione Hugo o Jekyll può scrivere un pacchetto adapter di terze parti e installarlo accanto a Zenzic senza alcuna modifica a Zenzic stesso:

# Esempio: adapter di terze parti per un ipotetico supporto Hugo
uv pip install zenzic-hugo-adapter   # oppure: pip install zenzic-hugo-adapter
zenzic check all --engine hugo

Questa portata multi-linguaggio è una proprietà strutturale, non una promessa di roadmap. Il protocollo Adapter definisce cinque metodi; qualsiasi pacchetto Python che li implementa e si registra sotto il gruppo entry-point zenzic.adapters è un adapter Zenzic valido — per qualsiasi SSG.

Versioni Supportate dei Motori

Zenzic include adapter per specifiche linee di versione maggiore. Dichiarare un motore diverso è un errore di configurazione: Zenzic emetterà Z000 UNSUPPORTED_ENGINE e si interromperà.

Motore	Versioni supportate	Note
MkDocs	`1.x`	Serie congelata a `1.6.1`; nessuna `1.7` prevista. v2 è un progetto separato e richiede un adapter dedicato
Zensical	`0.0.x`	Pre-release; API volatile. L'adapter viene aggiornato in lockstep
Docusaurus	`3.x`	Il supporto v2 è deprecato ed è stato rimosso in Zenzic 0.9.0
Standalone	—	Agnostico rispetto al motore; la versione non è rilevante

Zenzic non invoca il binario del motore — legge i file di configurazione come dati semplici. I vincoli di versione riguardano lo schema del file di configurazione, non il binario del motore installato. Se il tuo progetto utilizza una versione più recente di quelle elencate, l'adapter potrebbe comunque funzionare; segnala un problema solo se riscontri un errore di parsing effettivo o un falso positivo riconducibile a una modifica dello schema.

Scegliere un motore

La sezione [build_context] in .zenzic.toml indica a Zenzic quale motore utilizza il tuo progetto:

# .zenzic.toml
[build_context]
engine = "mkdocs"   # oppure "zensical" o "docusaurus"

Se [build_context] è assente, Zenzic individua deterministicamente il motore:

mkdocs.yml presente → MkDocsAdapter
docusaurus.config.ts (o .js) presente → DocusaurusAdapter
nessuna configurazione presente, nessun locale dichiarato → StandaloneAdapter (controllo orphan disabilitato)

Ponte CLI — Controlli signal-to-noise

Selezione engine e verbosità report sono aspetti separati. Usa Comandi CLI: Flag globali per calibrare la policy per run:

--strict per elevare warning e imporre validazione URL esterni.
--exit-zero per run osservativi non bloccanti.
--show-info per ispezionare finding informativi di topologia.
--quiet per output CI/pre-commit a riga singola.

MkDocs

MkDocsAdapter viene selezionato quando engine = "mkdocs". Le stringhe motore non riconosciute ricadono su StandaloneAdapter — nessuna consapevolezza nav. Legge mkdocs.yml usando un loader YAML permissivo che ignora silenziosamente i tag sconosciuti (come l'interpolazione !ENV di MkDocs), quindi le configurazioni con molte variabili d'ambiente funzionano senza alcuna pre-elaborazione.

Limiti dell'analisi statica

MkDocsAdapter analizza mkdocs.yml come dati statici. Non esegue la pipeline di build di MkDocs. Questo significa:

Tag !ENV — trattati silenziosamente come null. Se la nav dipende da

interpolazione di variabili d'ambiente a runtime, le voci nav che dipendono da quei valori saranno assenti dalla visione di Zenzic.
Nav generata dai plugin — plugin che mutano la nav a runtime (es.

mkdocs-awesome-pages, mkdocs-literate-nav) producono un albero di navigazione che Zenzic non vede mai. Le pagine incluse solo da questi plugin vengono segnalate come orfane.
Macro — mkdocs-macros-plugin (template Jinja2 in Markdown) non viene

valutato. I link all'interno di espressioni macro non vengono validati.

Per progetti che dipendono fortemente dalla generazione dinamica della nav, aggiungi i percorsi generati dai plugin a excluded_dirs in .zenzic.toml per sopprimere i falsi positivi sugli orfani finché non sarà disponibile un adapter nativo.

Configurazione minima

# .zenzic.toml
docs_dir = "docs"

[build_context]
engine         = "mkdocs"
default_locale = "en"
locales        = ["it", "fr"]   # nomi delle directory locale non predefinite (folder mode)

Quando locales è vuoto, Zenzic si ricade a leggere le informazioni sui locale direttamente dal blocco del plugin i18n in mkdocs.yml — zero configurazione richiesta per la maggior parte dei progetti. Questo comprende sia il pacchetto community mkdocs-static-i18n che il plugin i18n integrato in mkdocs-material, poiché entrambi si dichiarano come i18n: in mkdocs.yml.

i18n: Folder Mode

In Folder Mode (docs_structure: folder), ogni locale non predefinito vive in una directory di primo livello sotto docs/:

docs/
  index.md          ← locale predefinito
  assets/
    logo.png        ← asset condiviso
  it/
    index.md        ← traduzione italiana

Zenzic legge la lista languages da mkdocs.yml per identificare le directory locale. I file il cui primo componente del percorso è una directory locale vengono esclusi dal controllo orphan — ereditano la loro appartenenza alla nav dall'originale nel locale predefinito.

Quando fallback_to_default: true è impostato, i link agli asset da docs/it/index.md che si risolvono a docs/it/assets/logo.png (assente) vengono automaticamente ricontrollati rispetto a docs/assets/logo.png, specchiando il comportamento di fallback effettivo del motore di build.

mkdocs.yml
# mkdocs.yml
plugins:

  - i18n:

      docs_structure: folder
      fallback_to_default: true
      languages:

        - locale: en

          default: true
          build: true

        - locale: it

          build: true

Regola: Se fallback_to_default: true è impostato, almeno una voce lingua deve avere default: true. Se nessuna lo ha, Zenzic lancia ConfigurationError immediatamente — non può determinare il locale di destinazione del fallback.

i18n: Suffix Mode

In Suffix Mode (docs_structure: suffix), i file tradotti sono fratelli degli originali:

docs/
  guide.md        ← locale predefinito
  guide.it.md     ← traduzione italiana (stessa profondità di directory)
  assets/
    logo.png      ← stesso percorso relativo da entrambi i file

Zenzic legge i codici locale non predefiniti da mkdocs.yml e genera pattern di esclusione *.{locale}.md (es. *.it.md, *.fr.md). Questi file vengono esclusi dal controllo orphan.

Solo i codici ISO 639-1 validi di due lettere minuscole producono pattern di esclusione. I tag di versione (v1, v2), tag di build (beta, rc1), codici a tre lettere e codici BCP 47 con regione vengono rifiutati silenziosamente — non producono esclusioni false.

Risoluzione degli URL di route

MkDocs costruisce gli URL dai percorsi sorgente quando use_directory_urls: true (impostazione predefinita): docs/guide/install.md → /guide/install/. Zenzic valida i link relativi a livello sorgente, non gli URL costruiti — quindi i link inter-documento sono identici in entrambe le modalità di routing.

Se use_directory_urls: false è impostato, MkDocs genera file .html piatti. La validazione dei link di Zenzic non è influenzata: i link relativi ../api.md si risolvono correttamente indipendentemente da questa impostazione. Solo i link assoluti (/guide/) vengono sempre segnalati come Z105 ABSOLUTE_PATH.

Zensical

ZensicalAdapter viene selezionato quando engine = "zensical". Legge zensical.toml nativamente usando tomllib di Python — zero YAML. Nessun mkdocs.yml viene letto né richiesto.

Native Enforcement

# .zenzic.toml
[build_context]
engine = "zensical"

Proxy Trasparente (Ponte di Migrazione)

Il Proxy Trasparente è la feature di migrazione distintiva di Zensical: se zensical.toml è assente ma mkdocs.yml è presente nella root del progetto, ZensicalAdapter legge automaticamente la configurazione MkDocs come ponte — senza alcuna configurazione manuale.

Questo significa che puoi adottare Zenzic con l'engine Zensical dal primo giorno di migrazione, prima di scrivere una singola riga di zensical.toml. Quando il ponte si attiva, il banner Zenzic notifica:

NOTICE: Zensical engine active via mkdocs.yml compatibility bridge.

Cosa legge il ponte da mkdocs.yml:

Campo MkDocs	Usato da Zensical Adapter per
`docs_dir`	Rilevamento della directory sorgente
`nav`	Appartenenza alla nav (rilevamento orphan)
`plugins.i18n.languages`	Identificazione delle directory locale
`theme.favicon`, `theme.logo`	Guardia asset Z404

Strategia di migrazione

Usa il Proxy Trasparente per eseguire zenzic check all sul tuo progetto MkDocs prima di impegnarti con Zensical. Una volta soddisfatto dei risultati, crea un zensical.toml nativo per la piena parità e sblocca le funzionalità specifiche di Zensical.

Formato nav di zensical.toml

Zenzic legge la sezione [nav] per determinare quali pagine sono dichiarate:

# zensical.toml
[project]
site_name = "La Mia Documentazione"

[nav]
nav = [
  {title = "Home",      file = "index.md"},
  {title = "Tutorial",  file = "tutorial.md"},
  {title = "API",       file = "reference/api.md"},
]

I file elencati sotto file (relativi a docs/) costituiscono il set della nav. Qualsiasi file .md sotto docs/ che non è in questo set e non è un mirror locale viene segnalato come orphan.

Perché Zensical elimina la complessità dell'i18n

Vedi Caricamento Configurazione per il razionale architetturale dietro i18n nativo di Zensical vs. indirezione di plugin MkDocs.

Limitazioni

Nav generata da plugin — I plugin Zensical che modificano la nav a runtime non vengono

valutati. Le pagine incluse solo da tali plugin potrebbero essere segnalate come orphan. Aggiungi i loro percorsi a excluded_dirs in .zenzic.toml per sopprimere i report falsi.
Contenuto dinamico — zensical.toml viene analizzato come TOML statico. Le espressioni

template o i campi calcolati non vengono valutati.
Scope di rilevamento — ZensicalAdapter cerca zensical.toml (o il ponte MkDocs) solo

nella root del progetto. I layout workspace nidificati richiedono un docs_dir esplicito in .zenzic.toml.

Docusaurus

DocusaurusAdapter viene selezionato quando engine = "docusaurus" o quando docusaurus.config.ts (o .js) viene rilevato nella root del progetto. Legge la configurazione di Docusaurus come testo statico usando pattern matching — nessun runtime Node.js, nessun npm install, nessuna valutazione JavaScript.

Analisi solo-sorgente

Docusaurus è un framework Node.js costruito su React. Zenzic non importa né esegue alcun codice Node.js. Il DocusaurusAdapter invece:

Legge docusaurus.config.ts come testo ed estrae dati strutturali — i18n.locales,

i18n.defaultLocale, routeBasePath e path del plugin docs, e configurazione sidebar.
Risolve le directory locale secondo il layout i18n standard di Docusaurus

(i18n/{locale}/docusaurus-plugin-content-docs/current/).
Mappa le sidebar da sidebars.ts o sidebars.js usando pattern matching a livello

testuale per determinare quali file sono dichiarati nella navigazione.

Configurazione minima

# .zenzic.toml
docs_dir = "docs"

[build_context]
engine         = "docusaurus"
default_locale = "en"
locales        = ["it", "fr"]

Quando locales è vuoto, Zenzic legge le informazioni sui locale dal blocco i18n in docusaurus.config.ts.

Supporto al versioning

Zenzic supporta nativamente la documentazione multi-versione di Docusaurus. Identifica:

Lista versioni — letta da versions.json nella root del progetto.
Contenuto versionato — scoperto sotto versioned_docs/version-{version}/.
Traduzioni versionate — scoperte sotto i18n/{locale}/docusaurus-plugin-content-docs/version-{version}/.

La Virtual Site Map mappa automaticamente questi percorsi ai rispettivi URL canonici, seguendo le regole ufficiali di versionamento di Docusaurus:

Versione latest (la prima voce in versions.json) mappa sulla root della routeBasePath — senza etichetta di versione nell'URL.
- Esempio: versioned_docs/version-1.1.0/hello.md con versions.json = ["1.1.0", "1.0.0"] → /docs/hello/.
Versioni precedenti conservano l'etichetta di versione nell'URL.
- Esempio: versioned_docs/version-1.0.0/hello.md → /docs/1.0.0/hello/.

Questo rispecchia esattamente il comportamento di Docusaurus, prevenendo falsi positivi di link rotti sulle pagine della versione latest.

Ghost Routing

Le rotte versionate sono trattate come Ghost Routes: sono sempre considerate raggiungibili perché Docusaurus genera automaticamente la navigazione per gli alberi di documentazione versionati.

Auto-discovery del blog

I post del blog Docusaurus vivono fuori da docs/, ma restano URL reali che la build serve agli utenti. Zenzic li scopre automaticamente — nessuna configurazione aggiuntiva richiesta:

Se docusaurus.config.ts dichiara un blocco blog: { path, routeBasePath }, Zenzic usa quei valori.
Altrimenti, se <repo>/blog/ esiste su disco, Zenzic assume il layout di default del plugin (path: 'blog', routeBasePath: 'blog').
Se nessuna delle due condizioni è vera, il plugin blog è considerato assente e nulla di extra viene scansionato.

Una volta scoperto, l'albero del blog è trattato da zenzic check all come contenuto di prima classe:

I link rotti all'interno di un post del blog vengono catturati (prima il file era silenziosamente ignorato).
I link rotti da docs/ verso un post (o viceversa) vengono catturati.
Gli asset referenziati solo da un post non producono più Z405 (Asset Inutilizzato).
I prefissi data nei nomi file (YYYY-MM-DD-slug.md) e gli override slug: nel frontmatter sono onorati esattamente come fa docusaurus build.

Per disattivare, imposta blog: false in docusaurus.config.ts. Per usare un layout custom, dichiaralo esplicitamente nello stesso file — Zenzic lo rileverà.

Virtual Routes (Tag, Paginazione, Autori)

Docusaurus genera rotte prive di file Markdown sorgente fisico: ogni tag univoco nel frontmatter produce una pagina /blog/tags/{slug}/, gli indici paginati producono pagine /blog/page/{n}/, e i profili autore producono pagine /blog/authors/{id}/.

DocusaurusAdapter inferisce queste virtual routes in modo statico — nessun build step, nessuna esecuzione Node.js — leggendo i metadati frontmatter dai post del blog già caricati in memoria.

Ogni VirtualRoute emessa dall'adapter porta:

Campo	Tipo	Esempio
`url`	`str`	`/blog/tags/python/`
`kind`	`Literal["tag","tag_index","pagination","author","author_index"]`	`"tag"`
`label`	`str`	`"tag:python"`
`source_files`	`frozenset[str]`	`{"blog/2026-04-12-post.md"}`

Il set source_files è l'implementazione dell'Invariante di Reverse-Mapping: ogni URL ammessa nella VSM — fisica o virtuale — deve risalire in modo non ambiguo a uno o più file sorgente reali. Una VirtualRoute con source_files vuoto solleva ValueError al momento della costruzione; non può raggiungere la VSM.

Route tag generate per post:

Dato un post con tags: [python, tutorial], Zenzic emette tre virtual routes:

/blog/tags/python/    kind=tag        source_files={"blog/2026-04-12-post.md"}
/blog/tags/tutorial/  kind=tag        source_files={"blog/2026-04-12-post.md"}
/blog/tags/           kind=tag_index  source_files={"blog/2026-04-12-post.md", ...}

La tag index (/blog/tags/) elenca sempre l'unione di tutti i file blog che portano almeno un tag, fornendo la tracciabilità cross-file necessaria per la diagnostica.

Paginazione e Autori — Fase 2

Le route di paginazione (/blog/page/{n}/) e le route autore saranno aggiunte nelle fasi successive. Il campo VirtualRoute.kind riserva già i letterali "pagination", "author" e "author_index" così i consumer downstream possono gestire tutti i tipi di rotta senza un cambiamento di schema breaking.

Connessione a tool esterni

Il comando zenzic inspect routes è ora disponibile. Questa funzionalità esporta la mappa completa del sito in formato JSON deterministico. È progettata per essere consumata da tool esterni: script Bash custom, dashboard di CI/CD, o tool specializzati che necessitano di contesto architetturale.

Layout i18n

Docusaurus memorizza le traduzioni in una struttura di directory profonda:

docs/
  index.mdx         ← locale predefinito
  assets/
    logo.png         ← asset condiviso
i18n/
  it/
    docusaurus-plugin-content-docs/
      current/
        index.mdx    ← traduzione italiana

L'adapter identifica i18n/{locale}/docusaurus-plugin-content-docs/current/ come root del mirror locale. I file sotto questi percorsi vengono esclusi dal controllo orphan — ereditano l'appartenenza alla nav dall'originale nel locale predefinito.

Regole frontmatter slug

Docusaurus consente di sovrascrivere l'URL canonico di qualsiasi pagina tramite la chiave frontmatter slug:. Zenzic applica le stesse regole di Docusaurus:

Slug assoluto (inizia con /): sempre preceduto dalla routeBasePath.
- slug: /ciao + routeBasePath: docs → /docs/ciao/.
- slug: /ciao + routeBasePath: '' (docs alla root del sito) → /ciao/.
Slug relativo (senza / iniziale): sostituisce solo l'ultimo segmento del percorso.
- slug: setup in guide/install.md → /docs/guide/setup/.

Collasso intelligente dei file

Zenzic rispecchia la logica isCategoryIndex di Docusaurus: un file collassa nell'URL della directory genitore quando il suo nome (case-insensitive) è:

index — es. guides/index.md → /docs/guides/
readme — es. guides/README.md → /docs/guides/
Il nome della cartella genitore — es. Guide/Guide.md → /docs/Guide/

Questo evita che Zenzic segnali link rotti quando gli autori usano una di queste tre convenzioni per creare pagine di atterraggio di categoria.

Navigazione Unificata Discovery

In Docusaurus, tutti i file in docs/ sono instradati dal plugin docs — il routing è guidato dal file system, non dalla sidebar. Sidebar, navbar e footer controllano solo la UX di scoperta: se un utente riesce effettivamente a trovare e cliccare una pagina.

Zenzic applica la Legge di Scoperta UX: un file è considerato REACHABLE se appare in qualsiasi superficie di navigazione dell'interfaccia. Un file assente da tutte le superfici è un orfano — ha un URL, ma nessun percorso utente conduce a esso.

DocusaurusAdapter aggrega tre sorgenti di navigazione staticamente (senza Node.js):

Sorgente	Posizione configurazione	Metodo
Sidebar	`sidebars.ts` / `sidebars.js`	Voci `type: 'doc'` e ID stringa bare
Navbar	`docusaurus.config.ts` → `themeConfig.navbar.items`	Path URL `to:` e attributi `docId:`
Footer	`docusaurus.config.ts` → `themeConfig.footer.links`	Path URL `to:`

Un file è ORPHAN_BUT_EXISTING solo se è assente da tutte e tre le sorgenti:

docs/changelog.mdx  → linkato dalla navbar (to: '/docs/changelog')  → REACHABLE ✓
docs/about.mdx      → linkato dal footer (to: '/docs/about')        → REACHABLE ✓
docs/secret.mdx     → assente da sidebar, navbar e footer           → ORPHAN_BUT_EXISTING ✗

Sidebar autogenerata

Quando sidebars.ts contiene type: 'autogenerated', Docusaurus mostra tutti i documenti nella sidebar automaticamente. Zenzic lo rileva e marca tutti i file come REACHABLE — nessun report orfano viene emesso indipendentemente dal contenuto di navbar o footer.

I path URL to: vengono risolti rimuovendo i prefissi baseUrl e routeBasePath, poi cercando su disco .md / .mdx. I link non-doc (es. /blog/, URL esterni) non corrispondono mai a un file e vengono ignorati silenziosamente — nessun falso positivo.

Risoluzione alias `@site/`

I progetti Docusaurus usano frequentemente l'alias @site/ nei link per referenziare file relativi alla root del progetto:

[Diagramma architettura](@site/static/img/arch.png)
[Codice sorgente](@site/docs/internals/architecture.mdx)

Zenzic risolve @site/ automaticamente alla root del repository. I link che iniziano con @site/docs/ vengono risolti rispetto alla docs root; tutti gli altri percorsi @site/ vengono verificati rispetto alla root del repository. Questo significa che Zenzic valida questi link senza generare falsi positivi di errore PathTraversal.

note

Per abilitare la risoluzione completa di @site/, imposta repo_root nella sezione [build_context] del tuo .zenzic.toml, oppure esegui zenzic check dalla root del progetto affinché Zenzic possa rilevarlo automaticamente.

Supporto MDX

Docusaurus usa file MDX (.mdx) nativamente. L'adapter tratta i file .mdx in modo identico ai file .md per scanning, validazione link e controllo orphan.

Schemi URL speciali

Zenzic riconosce il protocollo pathname:/// nativo di Docusaurus. Questo schema viene usato per referenziare asset statici fuori dal router React — download, pagine HTML standalone, PDF — che Docusaurus serve direttamente senza generazione di route:

[Apri Brand System &rarr;](pathname:///assets/brand/zenzic-brand-system.html)
[Scarica la guida](pathname:///assets/guide.pdf)

Poiché pathname:/// è un escape hatch specifico di Docusaurus senza equivalenti negli altri motori, Zenzic lo tratta come un bypass verificato — solo quando engine = "docusaurus":

Motore	Gestione `pathname:///`
`docusaurus`	Ignorato silenziosamente — escape hatch riconosciuto
`mkdocs`, `zensical`, `standalone`	Segnalato come `Z105 ABSOLUTE_PATH`

Isolamento per Motore

Questa eccezione è intenzionalmente limitata all'adapter Docusaurus. Se stai migrando da Docusaurus a un altro motore, Zenzic segnalerà ogni link pathname:/// come errore Z105 — guidandoti a sostituirli con percorsi relativi portabili.

Limiti dell'analisi statica

Plugin sidebar dinamici — le sidebar generate dinamicamente tramite JavaScript a

build-time producono una navigazione che Zenzic non può osservare staticamente. Le pagine incluse solo da plugin sidebar personalizzati verranno segnalate come orfane.
docusaurus.config.ts con TypeScript complesso — l'adapter usa pattern matching, non

valutazione TypeScript completa. Le configurazioni che calcolano valori a livello di modulo o importano da moduli esterni potrebbero non essere analizzate completamente.

Per i casi di sidebar dinamiche, aggiungi i percorsi generati a excluded_dirs in .zenzic.toml.

Divieto di Link Assoluti

Questa regola si applica a ogni motore, incondizionatamente.

I link che iniziano con / sono un errore bloccante in tutte le modalità motore:

{/* Rifiutato — il percorso assoluto rompe la portabilità */}
[Scarica](/assets/guide.pdf)

{/* Corretto — il percorso relativo sopravvive a qualsiasi prefisso di hosting */}
[Scarica](/assets/guide.pdf)

Un link a /assets/guide.pdf presuppone che il sito sia servito dalla root del dominio. Quando la documentazione è ospitata su https://example.com/docs/, il browser risolve /assets/guide.pdf in https://example.com/assets/guide.pdf — un 404. La correzione è sempre un percorso relativo.

Il controllo viene eseguito prima di qualsiasi logica dell'adapter — prima del parsing della nav, prima del rilevamento dei locale, prima della risoluzione dei percorsi. Non può essere soppresso dalla configurazione del motore.

Gli URL esterni (https://..., http://...) non sono interessati.

Standalone (nessun motore)

StandaloneAdapter viene restituito quando non è presente alcun file di configurazione del motore e non sono dichiarati locale. È la modalità universale di Zenzic — compatibile con qualsiasi progetto basato su Markdown che non utilizza un SSG supportato.

Quando usare Standalone

Repository Markdown statici — wiki, ADR log, documentazione in testo statico senza

pipeline di build.
Validazione pre-migrazione — esegui Zenzic su un progetto prima di scegliere un SSG per

rilevare link rotti e credenziali prima dell'introduzione di un framework.
Progetti SSG personalizzati — qualsiasi generatore non ancora coperto da un adapter nativo.

Usa excluded_dirs per sopprimere i falsi positivi delle directory di output generate.

Configurazione minimale

# .zenzic.toml — minimo richiesto per standalone
docs_dir = "docs"

Nessuna sezione [build_context] è necessaria. Zenzic rileva l'assenza di file di configurazione del motore e seleziona automaticamente StandaloneAdapter.

Capacità

I controlli snippet, placeholder, link e asset vengono eseguiti a piena potenza. Il rilevamento credenziali Z201, il rilevamento path traversal Z202/Z203 e le guardie logo/favicon Z401 funzionano tutti normalmente.

Tutti i metodi dell'adapter sono no-op:

is_locale_dir → sempre False
resolve_asset → sempre None
is_shadow_of_nav_page → sempre False
get_nav_paths → frozenset()
get_ignored_patterns → set()

Limitazioni

find_orphans restituisce [] immediatamente — senza una nav dichiarata, non c'è un insieme di riferimento con cui confrontarsi. Il rilevamento orphan richiede una dichiarazione nav: MkDocs nav:, Zensical [nav], o Docusaurus sidebars.ts.

Per progetti con localizzazione senza un engine supportato, aggiungi i nomi delle directory locale a excluded_dirs in .zenzic.toml per evitare falsi report orphan.

Portata multi-ecosistema​

Versioni Supportate dei Motori​

Scegliere un motore​

MkDocs​

Limiti dell'analisi statica​

Configurazione minima​

i18n: Folder Mode​

i18n: Suffix Mode​

Risoluzione degli URL di route​

Zensical​

Native Enforcement​

Proxy Trasparente (Ponte di Migrazione)​

Formato nav di zensical.toml​

Perché Zensical elimina la complessità dell'i18n​

Limitazioni​

Docusaurus​

Analisi solo-sorgente​

Configurazione minima​

Supporto al versioning​

Auto-discovery del blog​

Virtual Routes (Tag, Paginazione, Autori)​

Layout i18n​

Regole frontmatter slug​

Collasso intelligente dei file​

Navigazione Unificata Discovery​

Risoluzione alias @site/​

Supporto MDX​

Schemi URL speciali​

Limiti dell'analisi statica​

Divieto di Link Assoluti​

Standalone (nessun motore)​

Quando usare Standalone​

Configurazione minimale​

Capacità​

Limitazioni​

Portata multi-ecosistema

Versioni Supportate dei Motori

Scegliere un motore

MkDocs

Limiti dell'analisi statica

Configurazione minima

i18n: Folder Mode

i18n: Suffix Mode

Risoluzione degli URL di route

Zensical

Native Enforcement

Proxy Trasparente (Ponte di Migrazione)

Formato nav di zensical.toml

Perché Zensical elimina la complessità dell'i18n

Limitazioni

Docusaurus

Analisi solo-sorgente

Configurazione minima

Supporto al versioning

Auto-discovery del blog

Virtual Routes (Tag, Paginazione, Autori)

Layout i18n

Regole frontmatter slug

Collasso intelligente dei file

Navigazione Unificata Discovery

Risoluzione alias `@site/`

Supporto MDX

Schemi URL speciali

Limiti dell'analisi statica

Divieto di Link Assoluti

Standalone (nessun motore)

Quando usare Standalone

Configurazione minimale

Capacità

Limitazioni