Introduction

Zenzic is an engineering-grade static analyzer for Markdown-based documentation.

Unlike traditional linters that check prose or generic link checkers that crawl generated HTML, Zenzic operates in the Build-Aware Gap: the critical moment between writing source files and their transformation into a website.

Why Zenzic exists

The project was born from a structural observation: documentation tooling ecosystems are inherently unstable. Build engines introduce breaking changes, configuration formats shift, and teams migrate between generators. Relying on the "build output" for quality assurance is a strategic risk.

Zenzic provides a Safe Harbor for your content by building a Virtual Site Map (VSM) directly from the raw Markdown source. This ensures that your documentation remains valid and secure, regardless of which build engine (Docusaurus, MkDocs, or Zensical) you use.

Core Pillars

1. Lint the Source, not the Build: Agnostic to your static site generator.
2. Pure Python (No Subprocesses): Zero external dependencies, 100% portable and secure.
3. The Sentinel Shield: Built-in scanning for credentials and host-path probes.
4. Graph Intelligence: $O(V+E)$ complexity for link cycle detection.

"The Code is Law. The Documentation is Truth. The Sentinel is vigilant."

---

Installation

Zero-install (recommended for CI)

Run Zenzic on any project without installation using uvx:

uvx zenzic check all

uvx resolves and runs Zenzic in an isolated environment. No virtual environment setup required.

Persistent install

pip install zenzic

With MkDocs native plugin

To use the ZenzicPlugin inside mkdocs build, install the optional [mkdocs] extra:

pip install "zenzic[mkdocs]"

This adds mkdocs>=1.6.1 as a dependency and enables the zenzic.integrations.mkdocs entry point. See the Ecosystem overview for the full Adapter vs. Integration model.

---

Quick Start

1. Create a zenzic.toml at your repository root:

docs_dir = "docs"

[build_context]
engine = "docusaurus"   # or: mkdocs | zensical | vanilla

2. Run all checks:

zenzic check all

3. Interpret the exit code:

Code	Meaning
0	Clean — no issues found
1	Findings — documentation quality issues detected
2	Shield — leaked credential detected (never suppressed)
3	Blood Sentinel — path traversal attempt detected (never suppressed)