Skip to main content

Install Zenzic

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.

Install​

Ensure you have Python 3.10 or higher installed.

Ephemeral — no installation required​

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

Static analysis only — no build runtime required​

Zenzic reads configuration files (mkdocs.yml, zensical.toml, pyproject.toml) as plain text. It does not execute the build engine or its plugins.

Do not install MkDocs, Material for MkDocs, or any build plugin in your linting environment. They are not needed. The linting environment has one dependency: zenzic.

# Lint any MkDocs project — no extras needed
uvx 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 StandaloneAdapter (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 identifies the documentation engine from its configuration files 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 (Standalone 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 selects an adapter based on the build-engine configuration file present at the repository root. Engine-aware mode activates when mkdocs.yml or zensical.toml is found, enabling nav-aware orphan detection, i18n fallback resolution, locale directory suppression, and Ghost Route tracking. Standalone mode activates when no engine config is found — the orphan check is skipped because without a nav declaration every file would appear orphaned.

Use --engine to override the detected adapter for a single run without changing .zenzic.toml.

For the full design rationale behind engine-aware vs. standalone mode, see Architecture — Sovereign CLI.

Decommissioning Zenzic​

If you need to remove Zenzic from your project, the decommission process takes less than 30 seconds and leaves no trace.

Step 1 — Remove from CI/CD​

Delete the Zenzic block from your workflow files (e.g., .github/workflows/docs.yml):

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

Or, if running directly in a shell step:

- name: Zenzic
  run: uvx zenzic check all

Step 2 — Remove configuration​

Delete the configuration file from your repository:

rm .zenzic.toml
# OR edit pyproject.toml and remove the [tool.zenzic] section

Next steps: