Skip to main content

Getting Started

Zenzic reads directly from the filesystem and works with any Markdown-based project. Use it in local development, as a pre-commit hook, in CI pipelines, or for one-off audits.

Canonical examples​

The repository ships maintained fixtures that mirror the documented contracts:

  • examples/mkdocs-basic/ — MkDocs 1.6 baseline (nested nav, external nav link, tolerant YAML tags like !ENV and !relative).
  • examples/i18n-standard/ — strict bilingual gold standard.
  • examples/zensical-basic/ — Zensical v0.0.31+ baseline ([project].nav).
  • examples/broken-docs/ — intentional failures (exit 1).
  • examples/security_lab/ — security fixture (Shield exit 2, Blood Sentinel exit 3).
Just want to run it now?
uvx --pre zenzic check all

No installation required. uvx downloads and runs Zenzic in a throwaway environment.

✘ 2 errors⚠ 1 warning• 1 file with findings
FAILED: One or more checks failed.

Install​

Ephemeral — no installation required​

uvx --pre zenzic check all

uvx resolves and runs Zenzic from PyPI in a throwaway environment. Nothing is installed on your system. The right choice for one-off audits, git hooks, and CI jobs where you want to avoid pinning a dev dependency.

Global tool — available in every project​

uv tool install --pre zenzic
zenzic check all

Install once, use in any project. The binary is available on your PATH without activating a virtual environment.

Project dev dependency — version pinned per project​

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

Installs Zenzic into the project's virtual environment and pins the version in uv.lock. The right choice for team projects where everyone must use the same version, and for CI pipelines that install project dependencies before running checks.

Lean & Agnostic by Design​

Zenzic performs a static analysis of your configuration files (mkdocs.yml, zensical.toml, pyproject.toml). It does not execute the build engine or its plugins.

This means you do not need to install MkDocs, Material for MkDocs, or any other build-related plugins in your linting environment. Zenzic remains lightweight and dependency-free, making it ideal for fast, isolated CI/CD pipelines.

# Lint any MkDocs project — no extras needed
uvx --pre zenzic check all
Third-party engine adapters

Third-party adapters (e.g. a hypothetical zenzic-hugo-adapter) are separate installable packages — not extras of zenzic itself. No extra is required for VanillaAdapter (plain Markdown folders).

Init → Config → Check workflow​

The standard workflow for adopting Zenzic in a project:

1. Init — scaffold a configuration file​

Bootstrap a zenzic.toml with a single command. Zenzic auto-detects the documentation engine and pre-populates [build_context] accordingly:

zenzic init

Example output when mkdocs.yml is present:

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.

If no engine config file is found, zenzic init produces an engine-agnostic scaffold (Vanilla mode). In either case, all settings are commented out by default — uncomment and adjust only the fields you need.

Run Zenzic without a zenzic.toml and it falls back to built-in defaults, printing a Helpful Hint panel that suggests 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 — tune to your project​

Edit the generated zenzic.toml to suppress noise and set thresholds appropriate to your project:

# zenzic.toml — place at the repository root
excluded_assets = [
"assets/favicon.svg",      # referenced by mkdocs.yml, not by any .md page
"assets/social-preview.png",
]
placeholder_max_words = 30     # technical reference pages are intentionally brief
fail_under = 70                # establish an initial quality floor

See the Configuration Reference for the full field list.

3. Check — run continuously​

With the baseline established, run Zenzic on every commit and pull request:

# Pre-commit hook or CI step
# --strict: validate external URLs + treat warnings as errors
zenzic check all --strict

# Save a quality baseline on main
zenzic score --save

# Block PRs that regress the baseline by more than 5 points
zenzic diff --threshold 5

Engine modes​

Zenzic operates in one of two modes depending on whether it can discover a build-engine configuration file:

Engine-aware mode​

When mkdocs.yml (MkDocs/Zensical) or zensical.toml (Zensical) is present at the repository root, Zenzic loads the corresponding adapter which provides:

  • Nav awareness — orphan detection knows the difference between "not in the nav" and "not supposed to be in the nav" (e.g. i18n locale files).
  • i18n fallback — cross-locale links are resolved correctly instead of being flagged as broken.
  • Locale directory suppression — files under docs/it/, docs/fr/, etc. are not reported as orphans.
  • Ghost Routes — when mkdocs-material with reconfigure_material: true generates locale entry points (e.g. /it/) at build time, those pages never appear in nav:. Zenzic marks them REACHABLE automatically in the Virtual Site Map so they are never reported as false orphans — with no manual exclusion list required.

Vanilla mode​

When no build-engine configuration is found, Zenzic falls back to VanillaAdapter. In this mode:

  • Orphan check is skipped. Without a nav declaration, every file would appear to be an orphan.
  • All other checks run normally — links, snippets, placeholders, assets, and references.

Vanilla mode is the right choice for plain Markdown wikis, GitHub-wiki repos, or any project where navigation is implicit rather than declared.

Force a specific mode

Use --engine to override the detected adapter for a single run:

zenzic check all --engine vanilla    # skip orphan check regardless of config files
zenzic check all --engine mkdocs     # force MkDocs adapter

Next steps: