Skip to main content

Configure Adapters and Engine

Zenzic uses an adapter to obtain engine-specific knowledge — nav structure, i18n directories, and locale patterns — without importing or executing any build framework.

For the complete [build_context] field reference, adapter discovery rules, and ZensicalAdapter nav format, see Configuration Reference — [build_context].

Declare your engine​

Add a [build_context] section to .zenzic.toml to set the engine explicitly:

[build_context]
engine         = "auto"     # "auto" (default), "mkdocs", "zensical", "docusaurus"
default_locale = "en"       # ISO 639-1 code of the default locale
locales        = ["it"]     # non-default locale directory names (e.g. docs/it/, docs/fr/)

TOML ordering: [build_context] must be the last section in .zenzic.toml.

--engine flag (one-off override)​

The --engine flag on zenzic check orphans and zenzic check all overrides build_context.engine for a single run without touching .zenzic.toml:

zenzic check orphans --engine zensical
zenzic check all --engine mkdocs

If you pass an engine name that has no registered adapter, Zenzic lists the available adapters and exits with code 1:

ERROR: Unknown engine adapter 'hugo'.
Installed adapters: mkdocs, standalone, zensical
Install a third-party adapter or choose from the list above.

Engine coexistence (mkdocs.yml + zensical.toml in the same repo)​

Some repositories carry both mkdocs.yml and zensical.toml during a transition — one build test-running Zensical while the other keeps serving production on MkDocs.

When engine is explicitly declared in .zenzic.toml, Zenzic uses that adapter — even when another engine's config file is also present. engine = "mkdocs" always reads mkdocs.yml even if zensical.toml exists, and vice versa.

If engine is omitted (or build_context is absent entirely), the default is engine = "auto". Zenzic then uses Auto-Discovery: it inspects the project root for known manifests and mounts the correct adapter automatically.

Auto-Discovery priority order
  1. zensical.toml → ZensicalAdapter
  2. docusaurus.config.ts / docusaurus.config.js → DocusaurusAdapter
  3. mkdocs.yml → MkDocsAdapter
  4. No manifest found → StandaloneAdapter
# .zenzic.toml — explicit engine declaration required
[build_context]
engine = "zensical"   # ← this line is what activates ZensicalAdapter

Third-party adapters​

Third-party adapters (e.g. zenzic-hugo-adapter) are discovered automatically once installed as Python packages — no Zenzic update required. Register via the zenzic.adapters entry-point group.

See Writing an Adapter for the full protocol.