Skip to main content

Examples

Every example in the Zenzic repository is a self-contained reference project you can clone and run immediately. Each one is designed to demonstrate a specific feature or use-case so that the code you see is the minimum required to prove the concept.

All examples are located in examples/ in the Zenzic repository.

Quick-Run Pattern​

Every example follows the same convention:

# From the repo root — no install required
cd examples/<example-name>
uvx zenzic check all

Or with a persistent install:

pip install zenzic
cd examples/<example-name>
zenzic check all

Example Catalog​

Vanilla — Engine-Agnostic Quality Gate​

Directory: examples/vanilla/ Engine: vanilla (no build engine) Expected exit: 0

Demonstrates Zenzic running without any documentation engine. No mkdocs.yml, no docusaurus.config.ts — just Markdown files and a zenzic.toml. The VanillaAdapter treats every file as reachable.

Start here if: you have a project with plain Markdown and no SSG.

mkdocs-basic — MkDocs Integration Showcase​

Directory: examples/mkdocs-basic/ Engine: mkdocs Expected exit: 0 Extra required: pip install "zenzic[mkdocs]"

The primary showcase for zenzic.integrations.mkdocs. This example demonstrates:

  • MkDocsAdapter reading mkdocs.yml statically (no mkdocs binary invoked).
  • The zenzic plugin declared in mkdocs.yml — fires check all as a build gate during mkdocs build.
  • i18n folder-structure with English and Italian content.
# From mkdocs.yml in this example
plugins:
  - search
  - zenzic      # zenzic.integrations.mkdocs auto-discovered via entry point

Start here if: you use MkDocs and want a build-time quality gate.

docusaurus-v3 — Metadata-Driven Routing​

Directory: examples/docusaurus-v3/ Engine: docusaurus Expected exit: 0

Demonstrates DocusaurusAdapter parsing docusaurus.config.ts as plain text — no Node.js installation required. Key feature: docs/guide/about.mdx uses a frontmatter slug: /about override, demonstrating that Zenzic correctly maps the canonical URL via _extract_frontmatter_slug() rather than deriving it from the filesystem path.

---
title: About This Project
slug: /about
---

Start here if: you use Docusaurus v3 and want to validate links, slugs, and i18n structure.

zensical-basic — Zensical Engine​

Directory: examples/zensical-basic/ Engine: zensical Expected exit: 0

Minimal project demonstrating ZensicalAdapter reading zensical.toml. No Python library required for the adapter — ZensicalAdapter uses only tomllib (stdlib).

Start here if: you use Zensical as your build engine.

i18n-standard — Gold Standard Bilingual Docs​

Directory: examples/i18n-standard/ Engine: mkdocs Expected exit: 0

A bilingual documentation project structured to score 100/100 under zenzic check all --strict. Every page has an English original and an Italian translation in the correct directory structure. All links, slugs, and nav entries are consistent across locales.

Start here if: you maintain multilingual documentation and want to set a quality baseline.

vcs-aware-project — VCS-Aware Exclusion​

Directory: examples/vcs-aware-project/ Engine: vanilla Expected exit: 0

Demonstrates the Layered Exclusion Model introduced in v0.6.1 "Obsidian Bastion":

  • respect_vcs_ignore = true — Zenzic reads .gitignore patterns at L2-VCS.
  • included_dirs = ["generated-api"] — forces a VCS-ignored directory back into scope at L2 Forced Inclusion.
  • excluded_file_patterns = ["*_draft_*"] — Config-level L3 filename exclusion.

Start here if: you have VCS-ignored directories that should (or should not) be scanned.

custom-dir-target — Audit a Non-Default Directory​

Directory: examples/custom-dir-target/ Engine: vanilla Expected exit: 0

Shows how to point Zenzic at a docs directory that differs from the default docs/. Useful for monorepos or projects where documentation lives in content/, pages/, or another custom path.

single-file-target — Targeted Single-File Audit​

Directory: examples/single-file-target/ Engine: vanilla Expected exit: 0

Demonstrates scoping zenzic check links to one specific file using the --target flag. Useful for pre-commit hooks that only need to check changed files.

plugin-scaffold-demo — Custom Rule Plugin​

Directory: examples/plugin-scaffold-demo/ Engine: vanilla Expected exit: 0

The reference implementation for writing a custom Zenzic rule plugin. Generated by zenzic init --plugin my-plugin. Shows how to implement a BaseRule subclass, register it via the zenzic.rules entry point, and package it as a standalone Python package.

Start here if: you need a check that Zenzic doesn't provide out of the box.

broken-docs — Failure Reference Fixture​

Directory: examples/broken-docs/ Engine: vanilla Expected exit: 1

Intentionally triggers every Zenzic check to produce a complete failure report. This is the regression baseline for the check engine. Study this example to understand exactly what each finding type looks like in the output.

security_lab — Shield Test Fixture​

Directory: examples/security_lab/ Engine: vanilla Expected exit: 2 (Shield)

Intentionally triggers the Zenzic Shield (credential detection) and the link checker (path traversal, absolute host probes). Exit code 2 is expected and correct — the credential must be rotated. This fixture is the regression baseline for the Shield subsystem.

This example exits with code 2 by design

security_lab contains intentionally-placed synthetic credentials for Shield testing. Do not treat exit code 2 from this example as a real security incident. To verify Shield is working, run: cd examples/security_lab && zenzic check all; echo $? and confirm the output is 2.

Feature-to-Example Matrix​

FeatureExample
Zero-config plain Markdownvanilla
MkDocs static analysismkdocs-basic
MkDocs build-time gatemkdocs-basic
Docusaurus adapter + slug routingdocusaurus-v3
Zensical enginezensical-basic
Bilingual / i18n 100/100i18n-standard
VCS-aware exclusion (L1–L4)vcs-aware-project
Custom docs_dircustom-dir-target
Single-file --targetsingle-file-target
Custom rule pluginplugin-scaffold-demo
What failures look likebroken-docs
Shield credential detectionsecurity_lab

See Also​