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-kit.zip 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 Shield Test Fixture

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

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

File	What it triggers
traversal.md	PathTraversal: ../../etc/passwd escapes docs/
attack.md	PathTraversal + seven fake credential patterns (all Shield 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 (Shield: fake credentials)
zenzic check all              # exit 2 (Shield 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.

---

vanilla — Engine-Agnostic Quality Gate

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

Expected result: SUCCESS — all applicable checks pass.

What works in Vanilla 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/vanilla
zenzic check all   # exit 0

Use Vanilla mode for Hugo, Docusaurus, 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 vanilla: must be clean
(cd examples/i18n-standard && zenzic check all --strict)
(cd examples/vanilla        && 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 (Shield)
(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)