Zenzic Shield internally audits this repository for credential leaks on every commit.
The Safe Harbor for your Markdown documentation.
Engine-agnostic static analysis — standalone, security-hardened, zero configuration needed.
Got a folder of Markdown files? Run an instant security and link audit using uv:
uvx zenzic check all ./your-folderZenzic will identify your engine via its configuration files or default to Vanilla mode for standalone folders — providing immediate protection for links, credentials, and structural integrity.
pip install zenzic
zenzic lab # Interactive showroom — 9 acts, every engine, zero setup
zenzic check all # Audit the current directory📖 Full docs → · 🏅 Badges · 🔄 CI/CD guide
| Without Zenzic | With Zenzic |
|---|---|
| ❌ Broken anchors silently 200 OK in Docusaurus v3 | ✅ Mathematical anchor validation via VSM |
| ❌ Leaked API keys in code blocks committed to git | ✅ The Shield — 9-family credential scanner, exit 2 |
❌ Path traversal ../../../../etc/passwd in links |
✅ Blood Sentinel — non-suppressible exit 3 |
| ❌ Orphan pages unreachable from any nav link | ✅ Semantic orphan detection — not just file-exists |
| ❌ Silent 404s accumulating in Google Search Console | ✅ Directory Index Integrity checks |
| ❌ MkDocs → Zensical migration with unknown breakage | ✅ Transparent Proxy — lint both with one command |
- Not a site generator. It audits source; it never builds HTML.
- Not a build wrapper. Zero-Trust Execution: no subprocesses, no
mkdocsordocusaurusbinaries invoked. - Not a spell checker. Structure and security — not prose.
- Not an HTTP crawler. All validation is local and file-based.
| Capability | Command | Detects | Exit |
|---|---|---|---|
| Link integrity | check links |
Broken links, dead anchors | 1 |
| Orphan detection | check orphans |
Files absent from nav — invisible after build |
1 |
| Code snippets | check snippets |
Syntax errors in Python / YAML / JSON / TOML blocks | 1 |
| Placeholder content | check placeholders |
Stub pages and forbidden text patterns | 1 |
| Unused assets | check assets |
Images and files not referenced anywhere | 1 |
| Credential scanning | check references |
9 credential families — text, URLs, code blocks | 2 |
| Path traversal | check links |
System-path escape attempts | 3 |
| Quality score | score |
Deterministic 0–100 composite metric | — |
| Regression detection | diff |
Score drop vs saved baseline — CI-friendly | 1 |
Autofix: zenzic clean assets [-y] [--dry-run] deletes unused images.
🚀 v0.6.1 "Obsidian Glass" (Stable) — Full Docusaurus v3 versioning,
@site/alias resolution, and Zensical Transparent Proxy. See CHANGELOG.md.
Two security layers are permanently active — neither is suppressible by --exit-zero:
The Shield scans every line — including fenced code blocks — for credentials. Unicode normalization defeats obfuscation (HTML entities, comment interleaving, cross-line lookback). Detected families: AWS, GitHub/GitLab, Stripe, Slack, OpenAI, Google, PEM headers, hex payloads. → Exit 2. Rotate and audit immediately.
Blood Sentinel normalizes every resolved link with os.path.normpath and rejects any path
escaping the docs/ root. Catches ../../../../etc/passwd-style traversal before any OS syscall.
→ Exit 3.
| Exit | Meaning |
|---|---|
0 |
All checks passed |
1 |
Quality issues found |
2 |
SECURITY — leaked credential detected |
3 |
SECURITY — system-path traversal detected |
Add
zenzic check referencesto your pre-commit hooks to catch leaks before git history.
Zenzic reads config files as plain text — never imports or executes your build framework:
| Engine | Adapter | Highlights |
|---|---|---|
| Docusaurus v3 | DocusaurusAdapter |
Versioned docs, @site/ alias, Ghost Route detection |
| MkDocs | MkDocsAdapter |
i18n suffix + folder modes, fallback_to_default |
| Zensical | ZensicalAdapter |
Transparent Proxy bridges mkdocs.yml if zensical.toml absent |
| Any folder | VanillaAdapter |
Zero-config, Directory Index Integrity — no engine required |
Third-party adapters install via the zenzic.adapters entry-point group.
See the Developer Guide for the adapter API.
Zero-config by default. Priority: zenzic.toml > [tool.zenzic] in pyproject.toml > built-ins.
# zenzic.toml (all fields optional)
docs_dir = "docs"
fail_under = 80 # exit 1 if score < threshold; 0 = observe only
excluded_dirs = ["includes", "assets", "overrides"]
excluded_build_artifacts = ["pdf/*.pdf", "dist/*.zip"]
placeholder_patterns = ["coming soon", "todo", "stub"]
[build_context]
engine = "mkdocs" # mkdocs | docusaurus | zensical | vanilla
default_locale = "en"
locales = ["it"]zenzic init # Generate zenzic.toml with auto-detected values
zenzic init --pyproject # Embed [tool.zenzic] in pyproject.tomlCustom lint rules — declare project-specific patterns in zenzic.toml, no Python required:
[[custom_rules]]
id = "ZZ-NODRAFT"
pattern = "(?i)\\bDRAFT\\b"
message = "Remove DRAFT marker before publishing."
severity = "warning"Rules fire identically across all adapters. No changes required after engine migration.
- name: 🛡️ Zenzic Sentinel
run: uvx zenzic check all --strict
# Exit 1 = quality · Exit 2 = leaked credential · Exit 3 = path traversal
# Exits 2 and 3 are never suppressible.
- name: Regression gate
run: |
uvx zenzic score --save # on main branch
uvx zenzic diff # on PR — exit 1 if score dropsFor badge automation and regression gates, see the CI/CD guide.
Full workflow: .github/workflows/ci.yml
# Zero-install, one-shot audit (recommended for CI and exploration)
uvx zenzic check all ./docs
# Global CLI tool
uv tool install zenzic
# Pinned dev dependency
uv add --dev zenzic
# pip
pip install zenzic
pip install "zenzic[mkdocs]" # + MkDocs build-time pluginThe
[mkdocs]extra adds the build-time plugin (zenzic.integrations.mkdocs). All engine adapters (Docusaurus, Zensical, Vanilla) are included in the base install.
Portability: Zenzic rejects absolute internal links (starting with /). Relative links
work at any hosting path. External https:// URLs are never affected.
# Checks
zenzic check links [--strict]
zenzic check orphans
zenzic check snippets
zenzic check placeholders
zenzic check assets
zenzic check references [--strict] [--links]
zenzic check all [--strict] [--exit-zero] [--format json] [--engine ENGINE]
zenzic check all [--exclude-dir DIR] [--include-dir DIR]
# Score & diff
zenzic score [--save] [--fail-under N]
zenzic diff [--threshold N]
# Autofix
zenzic clean assets [-y] [--dry-run]
# Init
zenzic init [--pyproject]
# Interactive showroom
zenzic lab [--act N] [--list]╭─────────────────────── 🛡 ZENZIC SENTINEL v0.6.1 ────────────────────────╮
│ │
│ docusaurus • 38 files (18 docs, 20 assets) • 0.9s │
│ │
│ ────────────────────── docs/guides/setup.mdx ─────────────────────────── │
│ │
│ ✗ 12: [Z001] 'quickstart.mdx' not found in docs │
│ │ │
│ 12 │ Read the [quickstart guide](quickstart.mdx) first. │
│ │ │
│ ────────────────────────────────────────────────────────────────────────── │
│ │
│ ✗ 1 error • 1 file with findings • FAILED │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
Visit the documentation portal for interactive screenshots and rich examples.
- Auto-fix Engine — Automatic repair of broken links and orphaned anchors.
- IDE Extensions — Real-time linting for VS Code and Cursor via LSP.
- AI Context Provider — VSM export in LLM-friendly format for AI agents.
- Astro & VitePress Adapters — Expanding the Safe Harbor to JS frameworks.
Zenzic is built on three operational contracts:
Lint the Source, Not the Build. The VSM (Virtual Site Map) maps every .md file to its
canonical URL without running the build — errors are caught before they reach production.
Zero-Trust Execution. No subprocesses, no arbitrary code execution, no build engine imports.
Docusaurus .ts/.js configs are parsed via static text analysis — Node.js is never invoked.
Mandatory Exclusion at Every Entry Point. All file discovery goes through
LayeredExclusionManager — a 4-level hierarchy (System → VCS → Config → CLI). No global scan
without an explicit exclusion context.
See the Architecture Guide for the Two-Pass Reference Pipeline and VSM deep-dive.
Why not grep? Grep is blind to structure. Zenzic understands Docusaurus versioning,
MkDocs i18n fallbacks, and Ghost Routes — pages that don't exist as files but are valid URLs.
Does it run my build engine? No. 100% subprocess-free. Static analysis on plain text only.
Can it handle thousands of files? Yes. Adaptive parallelism for discovery; O(1) VSM lookup
per link; content-addressable cache (SHA256(content + config + vsm_snapshot)) skips unchanged files.
Shield vs Blood Sentinel? Shield = secrets inside content (exit 2). Blood Sentinel = links pointing to OS system paths (exit 3). Both are non-suppressible.
No zenzic.toml needed? Correct. Zenzic identifies the engine from config files present and applies safe defaults. Run
zenzic init at any time to generate a pre-populated config file.
What is zenzic lab? A 9-act interactive showroom covering every engine and error class.
Run it once before integrating Zenzic into any project.
uv sync --all-groups
nox -s tests # pytest + coverage
nox -s lint # ruff
nox -s typecheck # mypy --strict
nox -s preflight # lint + format + typecheck + pytest + reuse
just verify # preflight + zenzic check all --strict (self-dogfood)See the Contributing Guide for the Zenzic Way checklist and PR conventions.
- Open an issue to discuss the change.
- Read the Contributing Guide — Zenzic Way checklist, pure functions, no subprocesses, source-first.
- Every PR must pass
nox -s preflightand include REUSE/SPDX headers on new files.
See also: Code of Conduct · Security Policy
A CITATION.cff is present at the root. Click "Cite this repository" on
GitHub for APA or BibTeX output.
Apache-2.0 — see LICENSE.
© 2026 PythonWoods. Engineered with precision.
Based in Italy 🇮🇹 · Committed to the craft of Python development.
dev@pythonwoods.dev