🛡️ Zenzic

"Zenzic is the silent guardian of your documentation. It doesn't just check links; it audits your brand's technical integrity."
Engineering-grade documentation linter — standalone, engine-agnostic, and security-hardened.

---

Documentation doesn't fail loudly. It decays silently.

Broken links, orphan pages, invalid code snippets, stale placeholder content, and leaked API keys accumulate over time — until users hit them in production. Zenzic catches all of these across MkDocs and Zensical projects as a standalone CLI.

Zenzic is agnostic — it works with any Markdown-based documentation system (MkDocs, Zensical, or a bare folder of .md files) without installing any build framework. And it is opinionated: absolute links are a hard error, and if you declare engine = "zensical" you must have zensical.toml — no fallback, no guessing.

---

📖 Documentation

Zenzic provides an extensive, engineering-grade documentation portal:

• 🚀 User Guide: Installation, CLI usage, and all available checks.
• 🏅 Badges: Official Zenzic Shield and Score badge snippets for your README.
• 🔄 CI/CD Integration: GitHub Actions workflows, dynamic badges, and regression detection.
• ⚙️ Developer Guide: Deep dive into the deterministic pure-core architecture, Two-Pass Pipeline, and state-machine parsing.
• 🤝 Contributing: Set up the local development environment (uv, nox), run the test suite, and submit PRs.

Explore the full documentation →

---

---

What Zenzic checks

Check	CLI command	What it detects
Links	zenzic check links	Broken internal links, dead anchors, and path traversal attempts
Orphans	zenzic check orphans	.md files absent from nav
Snippets	zenzic check snippets	Python, YAML, JSON, and TOML blocks with syntax errors
Placeholders	zenzic check placeholders	Stub pages and forbidden text patterns
Assets	zenzic check assets	Images and files not referenced anywhere
References	zenzic check references	Dangling References, Dead Definitions, Zenzic Shield

Beyond pass/fail, zenzic score aggregates all checks into a deterministic 0–100 quality score. zenzic diff compares the current score against a saved baseline — enabling regression detection on every pull request.

Autofix: Zenzic also provides active cleanup utilities. Run zenzic clean assets to automatically deleting the unused images identified by check assets (interactive or via -y).

---

Portability Standards

Zenzic enforces two rules that make documentation portable across any hosting environment and independent of any specific build engine.

Relative Path Enforcement

Zenzic rejects internal links that start with /. Absolute paths are environment-dependent: a link to /assets/logo.png works when the site is at the domain root, but returns 404 when hosted in a subdirectory (e.g. https://example.com/docs/assets/logo.png ≠ https://example.com/assets/logo.png).

<!-- Rejected by Zenzic -->
[Download](/assets/guide.pdf)

<!-- Correct — works at any hosting path -->
[Download](../assets/guide.pdf)

The error message includes an explicit fix suggestion. External URLs (https://...) are not affected.

i18n Support: Suffix Mode and Folder Mode

Zenzic natively supports both i18n strategies used by mkdocs-static-i18n:

Suffix Mode (page.locale.md) — translated files are siblings of the originals:

docs/
  guide.md        ← default locale (EN)
  guide.it.md     ← Italian translation (same depth, path-symmetric)
  assets/
    logo.png      ← shared asset, same relative path from both files

Folder Mode (docs/it/page.md) — non-default locales live in a top-level directory:

docs/
  guide.md
  assets/
    logo.png
  it/
    guide.md      ← Italian translation

In Folder Mode, Zenzic uses the [build_context] section in zenzic.toml to know which top-level directories are locale trees. Asset links from docs/it/guide.md that resolve to docs/it/assets/logo.png are automatically re-checked against docs/assets/logo.png — mirroring the engine's own fallback behaviour. Locale files are never reported as orphans.

# zenzic.toml
[build_context]
engine         = "mkdocs"      # "mkdocs" or "zensical"
default_locale = "en"
locales        = ["it", "fr"]  # non-default locale directory names

When zenzic.toml is absent, Zenzic reads locale configuration directly from mkdocs.yml (respecting docs_structure, fallback_to_default, and languages). No configuration is required for projects that do not use i18n.

First-Class Integrations

Zenzic is build-engine agnostic. It works with any Markdown-based documentation system — MkDocs, Zensical, or a bare folder of .md files. No build framework needs to be installed; Zenzic reads raw source files only.

Where a documentation ecosystem defines well-known conventions for multi-locale structure or build-time artifact generation, Zenzic provides enhanced, opt-in support by reading the project's configuration file as plain YAML — never by importing or executing the framework itself.

Engine Adapters

Zenzic translates engine-specific knowledge into engine-agnostic answers through a thin adapter layer:

zenzic.toml  →  get_adapter()  →  Adapter  →  Core (Scanner + Validator)

The adapter answers the questions the Core needs without knowing anything about MkDocs or Zensical internals:

Method	Question
is_locale_dir(part)	Is this path component a non-default locale directory?
resolve_asset(path)	Does a default-locale fallback exist for this missing asset?
is_shadow_of_nav_page(rel, nav)	Is this locale file a mirror of a nav-listed page?
get_nav_paths()	Which .md paths are declared in the nav?
get_ignored_patterns()	Which filename patterns are non-default locale files (suffix mode)?

Three adapters are available, selected automatically by get_adapter():

Adapter	When selected	Config source
MkDocsAdapter	engine = "mkdocs" or unknown engine	mkdocs.yml (YAML)
ZensicalAdapter	engine = "zensical"	zensical.toml (TOML, zero YAML)
VanillaAdapter	No config file, no locales declared	— (all no-ops)

Native Enforcement — engine = "zensical" requires zensical.toml to be present. If it is absent, Zenzic raises ConfigurationError immediately. There is no fallback to mkdocs.yml and no silent degradation. Zensical identity must be provable.

MkDocs — i18n fallback

When mkdocs.yml declares the i18n plugin with fallback_to_default: true, Zenzic mirrors the plugin's resolution logic: a link from a translated page to an untranslated page is not reported as broken, because the build will serve the default-locale version. Supported for both docs_structure: suffix and docs_structure: folder.

# mkdocs.yml
plugins:
  - i18n:
      docs_structure: folder
      fallback_to_default: true
      languages:
        - locale: en
          default: true
          build: true
        - locale: it
          build: true

If mkdocs.yml is absent (or the i18n plugin is not configured), Zenzic falls back to standard single-locale validation — no errors, no warnings, no framework required.

Build-time artifacts (excluded_build_artifacts)

Applies to any documentation system. If links point to files generated at build time (PDFs, ZIPs), declare their glob patterns in zenzic.toml:

# zenzic.toml
excluded_build_artifacts = ["pdf/*.pdf", "dist/*.zip"]

Zenzic suppresses errors for matching paths at lint time. The build remains responsible for generating the artifacts; Zenzic trusts the link without requiring the file on disk.

Reference-style links

[text][id] links are resolved through the same pipeline as inline links — including i18n fallback — for all documentation systems.

[API Reference][api-ref]

[api-ref]: api.md

---

Installation

With uv (recommended)

uv is the fastest way to install and run Zenzic:

# Zero-install, one-shot audit
uvx zenzic check all

# Global CLI tool — available in any project
uv tool install zenzic

# Project dev dependency — version-pinned in uv.lock
uv add --dev zenzic

With pip

# Global install (consider a virtual environment)
pip install zenzic

# Inside a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install zenzic

MkDocs rendering — zenzic[docs] extra

Zenzic's core is dependency-free: linting raw Markdown requires nothing beyond zenzic. The MkDocs stack is only needed to render your site, not to validate it.

If you use MkDocs and also want the full build stack available:

# uv
uv add --dev "zenzic[docs]"

# pip
pip install "zenzic[docs]"

Note: All seven checks — including check links --strict and check references — work on raw Markdown source files via a native Python parser and httpx. No MkDocs or Zensical installation is required for check, score, or diff.

Build artifacts: If your documentation links to files generated at build time (PDFs, ZIPs), add their glob patterns to excluded_build_artifacts in zenzic.toml rather than pre-generating them. See the First-Class Integrations section above.

---

CLI usage

# Individual checks
zenzic check links --strict
zenzic check orphans
zenzic check snippets
zenzic check placeholders
zenzic check assets

# Autofix & Cleanup
zenzic clean assets               # Interactively delete unused assets
zenzic clean assets -y            # Delete unused assets immediately
zenzic clean assets --dry-run     # Preview what would be deleted

# Reference pipeline (v0.2.0)
zenzic check references           # Harvest → Cross-Check → Shield → Integrity score
zenzic check references --strict  # Treat Dead Definitions as errors
zenzic check references --links   # Also validate reference URLs via async HTTP

# All checks in one command
zenzic check all --strict
zenzic check all --exit-zero      # Report without blocking the pipeline
zenzic check all --format json    # Machine-readable output

# Quality score (0–100)
zenzic score
zenzic score --save               # Persist baseline snapshot
zenzic score --fail-under 80      # Exit 1 if below threshold

# Regression detection against saved snapshot
zenzic diff                       # Exit 1 on any score drop
zenzic diff --threshold 5         # Exit 1 only if drop > 5 points

# Development server (engine-agnostic)
zenzic serve                      # Auto-detect mkdocs or zensical
zenzic serve --engine mkdocs
zenzic serve --port 9000
zenzic serve --no-preflight

Exit codes

Code	Meaning
0	All selected checks passed
1	One or more checks reported issues
2	SECURITY CRITICAL — Zenzic Shield detected a leaked credential

Warning: Exit code 2 is reserved exclusively for security events. If zenzic check references exits with code 2, a secret (OpenAI API key, GitHub token, or AWS access key) was found embedded in a reference URL inside your documentation. Rotate the credential immediately.

---

🛡️ Zenzic Shield

The Zenzic Shield is a two-layer security system built into the core engine:

Layer	Introduced	Protects against
Credential detection	v0.2.0	Leaked API keys / tokens embedded in reference URLs
Path traversal	v0.3.0	../../../../etc/passwd-style escape from docs/

Credential detection

The credential layer runs during Pass 1 (Harvesting) of the reference pipeline and scans every reference URL for known credential patterns before any HTTP request is issued.

<!-- This definition would trigger an immediate Exit 2 -->
[api-docs]: https://api.example.com/?key=sk-AbCdEfGhIjKlMnOpQrStUvWxYz0123456789012345678901

╔══════════════════════════════════════╗
║        SECURITY CRITICAL             ║
║  Secret(s) detected in documentation ║
╚══════════════════════════════════════╝

  [SHIELD] docs/api.md:12 — openai-api-key detected in URL
    https://api.example.com/?key=sk-AbCdEfGhIj...

Build aborted. Rotate the exposed credential immediately.

How it works:

1. The Shield runs inside Pass 1 — before Pass 2 validates links and before any HTTP ping is issued. A document containing a leaked credential is never used to make outbound requests.
2. Patterns use exact-length quantifiers ({48}, {36}, {16}) — no backtracking, O(1) per line.
3. Seven credential families are covered out of the box:

Type	Pattern
OpenAI API key	sk-[a-zA-Z0-9]{48}
GitHub token	gh[pousr]_[a-zA-Z0-9]{36}
AWS access key	AKIA[0-9A-Z]{16}
Stripe live key	sk_live_[0-9a-zA-Z]{24}
Slack token	xox[baprs]-[0-9a-zA-Z]{10,48}
Google API key	AIza[0-9A-Za-z\-_]{35}
PEM private key	-----BEGIN [A-Z ]+ PRIVATE KEY-----

1. No blind spots — the Shield scans every line of the source file, including lines inside fenced code blocks (bash, yaml, unlabelled, etc.). A credential committed inside a code example is still a committed credential.

Tip: Add zenzic check references to your pre-commit hooks to catch leaked credentials before they are ever committed to version control.

Path traversal (v0.3.0)

The path traversal layer runs inside InMemoryPathResolver during check links. It normalises every resolved href with os.path.normpath (pure C, zero kernel calls) and verifies the result is contained within docs/ using a single string prefix check — $O(1)$, allocation-free.

Attack href:   ../../../../etc/passwd
After resolve: /etc/passwd
Shield check:  /etc/passwd does not start with /docs/ → PathTraversal returned, link rejected

Any href that escapes the docs root is surfaced as a distinct PathTraversal error — never silently collapsed into a generic "file not found".

---

CI/CD integration

GitHub Actions

- name: Lint documentation
  run: uvx zenzic check all

- name: Check references and run Shield
  run: uvx zenzic check references

Full workflow: .github/workflows/zenzic.yml

For dynamic badge automation and regression detection, see the CI/CD Integration guide.

---

Configuration (zenzic.toml)

All fields are optional. Zenzic works with no configuration file.

docs_dir = "docs"
excluded_dirs = ["includes", "assets", "stylesheets", "overrides", "hooks"]
snippet_min_lines = 1
placeholder_max_words = 50
placeholder_patterns = ["coming soon", "todo", "stub"]
fail_under = 80   # exit 1 if score drops below this; 0 = observational mode

# Engine and i18n context — required only for folder-mode multi-locale projects.
# When absent, Zenzic reads locale config directly from mkdocs.yml.
[build_context]
engine         = "mkdocs"   # "mkdocs" or "zensical"
default_locale = "en"
locales        = ["it"]     # non-default locale directory names

---

Development

For a faster, interactive development workflow using just, or for detailed instructions on adding new checks, see the Contributing Guide.

uv sync --group dev
nox -s dev         # Install pre-commit hooks (once)

nox -s tests       # pytest + coverage
nox -s lint        # ruff check
nox -s format      # ruff format
nox -s typecheck   # mypy --strict
nox -s docs        # mkdocs build --strict
nox -s preflight   # zenzic check all (self-check)

---

Contributing

We welcome bug reports, documentation improvements, and pull requests. Before you start:

1. Open an issue to discuss the change — use the bug report, feature request, or docs issue template.
2. Read the Contributing Guide — especially the Local development setup and the Zenzic Way checklist (pure functions, no subprocesses, source-first).
3. Every PR must pass nox -s preflight (tests + lint + typecheck + self-dogfood) and include REUSE/SPDX headers on new files.

Please also review our Code of Conduct and Security Policy.

Citing Zenzic

A CITATION.cff file is present at the root of the repository. GitHub renders it automatically — click "Cite this repository" on the repo page for APA or BibTeX output.

License

Apache-2.0 — see LICENSE.

---

© 2026 PythonWoods. Engineered with precision.
Based in Italy 🇮🇹  ·  Committed to the craft of Python development.
dev@pythonwoods.dev