---
icon: lucide/folder-open
---

<!-- SPDX-FileCopyrightText: 2026 PythonWoods <dev@pythonwoods.dev> -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# Example Projects

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

```bash
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` |

```bash
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

```bash
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 |

```bash
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

```bash
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.

---

## Running the full examples suite

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

```bash
# 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 ]
```
