Skip to content

Example Projects

The examples/ directory at the repository root contains five self-contained projects. Each is a runnable fixture: navigate into the directory and run zenzic check all to see its output.

git clone https://github.com/PythonWoods/zenzic
cd zenzic/examples/<name>
zenzic check all

broken-docs — Intentional Failures Fixture

Purpose: Trigger every Zenzic check at least once. Useful when debugging a new check or verifying that an error message is correctly formatted.

Expected result: FAILED — multiple check failures, exit code 1.

Check What triggers it
Links Missing file, dead anchor, path traversal, absolute path, broken i18n
Orphans api.md exists on disk but is absent from the nav
Snippets Python block with a SyntaxError (missing colon)
Placeholders api.md has only 18 words and a bare task marker
Assets assets/unused.png is on disk but never referenced
Custom rules ZZ-NOFIXME pattern in .zenzic.toml 
cd examples/broken-docs
zenzic check all            # exit 1
zenzic check all --exit-zero  # exit 0 (soft-gate mode)

Engine: mkdocs. Also ships a zensical.toml to demonstrate the same fixture under the Zensical engine.

i18n-standard — Gold Standard Bilingual Project

Purpose: Demonstrate a perfectly clean bilingual project that scores 100/100. Use this as the reference template when starting a new multilingual docs project.

Expected result: SUCCESS — all checks pass, score 100/100.

Key patterns this example demonstrates:

  • Suffix-mode i18n — translations live as page.it.md siblings, never in a

docs/it/ subtree

  • Path symmetry — ../../assets/brand/svg/zenzic-wordmark.svg resolves identically from

both page.md and page.it.md

  • Build artifact exclusion — excluded_build_artifacts lets Zenzic validate

links to generated files without requiring them on disk

  • fail_under = 100 — any regression breaks the gate
cd examples/i18n-standard
zenzic check all --strict   # exit 0, score 100/100

Engine: mkdocs with i18n plugin in docs_structure: suffix mode.

security_lab — Zenzic Credential Scanner Test Fixture

Purpose: Exercise the credential scanner subsystem — credential detection and path traversal classification — before releases.

Expected result: FAILED — exit code 2 (credential scanner event; non-suppressible).

File What it triggers
traversal.md PathTraversal: ../../etc/passwd escapes docs/
attack.md PathTraversal + seven fake credential patterns (all credential scanner families)
absolute.md Absolute paths (/assets/logo.png, /etc/passwd)
fenced.md Fake credentials inside unlabelled and bash fenced blocks 
cd examples/security_lab
zenzic check links --strict   # exit 1 (path traversal)
zenzic check references       # exit 2 (credential scanner: fake credentials)
zenzic check all              # exit 2 (credential scanner takes priority)

The credentials in attack.md and fenced.md are entirely synthetic — they match the regex shape but are not valid tokens for any service.

Engine: mkdocs.

standalone — Engine-Agnostic Quality Gate

Purpose: Show Zenzic running without any build engine. No mkdocs.yml, no zensical.toml, no Hugo config. Just engine = "standalone" in .zenzic.toml.

Expected result: SUCCESS — all applicable checks pass.

What works in Standalone mode:

  • Links, snippets, placeholders, and assets are fully checked
  • [[custom_rules]] fire identically to any other mode
  • fail_under enforces a minimum quality score
  • The orphan check is skipped — with no declared nav there is no reference set
cd examples/standalone
zenzic check all   # exit 0

Use Standalone mode for Hugo, Sphinx, Astro, Jekyll, GitHub wikis, or any project that does not use MkDocs or Zensical.

plugin-scaffold-demo — Plugin SDK Living Scaffold

Purpose: Provide the exact output generated by zenzic init --plugin plugin-scaffold-demo as a committed integration fixture.

Expected result: SUCCESS — the generated scaffold is lint-clean.

cd examples/plugin-scaffold-demo
zenzic check all   # exit 0

Use this fixture to validate scaffold regressions: if this example starts failing, the SDK template has drifted.

Running the full examples suite

From the repository root, verify all examples produce their expected exit codes:

# Gold standard and standalone: must be clean
(cd examples/i18n-standard && zenzic check all --strict)
(cd examples/standalone        && zenzic check all)

# Broken: must fail with exit 1
(cd examples/broken-docs    && zenzic check all); [ $? -eq 1 ]

# Security lab: must exit with code 2 (credential scanner)
(cd examples/security_lab   && zenzic check all); [ $? -eq 2 ]

# Plugin scaffold demo: generated template must be clean
(cd examples/plugin-scaffold-demo && zenzic check all)