Skip to main content

Frequently Asked Questions

This page collects answers to questions frequently asked by Zenzic users. Browse the sections below or use the search bar to find what you need.

Help us grow this page

Have a question that isn't answered here? Open an issue and we will add it.

General​

What is Zenzic?

Zenzic is a high-performance documentation linter for any Markdown-based project. It operates on raw source files — never the generated output — so it works with any build engine: MkDocs, Zensical, or any other static site generator via the adapter system. It detects broken links, orphan pages, placeholder stubs, unused assets, leaked credentials, and more — before the build runs.

Is Zenzic free?

Yes. Zenzic is Open Source under the Apache-2.0 license. You can use, modify, and distribute it freely, including in commercial contexts.

Which Python versions are supported?

Zenzic requires Python 3.11 or higher.

Installation and usage​

How do I install Zenzic?

The easiest way is to use uvx to run it directly without installing:

uvx zenzic check all

Or add it to your project with uv add --dev zenzic (recommended) or pip install zenzic.

Do I need a zenzic.toml file?

No. Zenzic works with zero configuration — the defaults cover most standard projects out of the box. zenzic.toml is only needed to customise behaviour, such as excluding specific directories, assets, or external URLs.

Can I use Zenzic with a non-MkDocs project?

Yes. Zenzic works on any folder of Markdown files without requiring a build engine at all (Vanilla mode). Native adapters for MkDocs, Zensical, and other engines add nav-awareness and i18n support. Third-party adapters can extend this to any other engine. See the Engines guide for details.

Checks and results​

What is the difference between zenzic check all and zenzic score?

zenzic check all runs all checks and returns a binary pass/fail result. zenzic score computes a weighted quality score from 0 to 100 with per-category breakdown, useful for continuous monitoring and badges.

What is an "orphan page"?

An orphan page is a Markdown file present in docs/ but absent from the site navigation declared in your build engine's configuration file. Orphan pages are unreachable by users navigating the site structure. Zenzic reports them so you stay in control.

The external link check is slow. Can I disable it?

External link validation only runs when --strict is passed — omitting the flag disables all network requests entirely. To permanently suppress specific URLs without removing strict mode, add their prefixes to excluded_external_urls in zenzic.toml:

excluded_external_urls = [
    "https://internal.company.com",
    "https://github.com/MyOrg/private-repo",
]

Does Zenzic check links in images too?

Yes. The link check analyses all Markdown references: text links, images, reference-style links, and same-page anchors (if validate_same_page_anchors: true is set).

CI/CD​

How do I integrate Zenzic in GitHub Actions?

- name: Lint documentation
  run: uvx zenzic check all --strict

For the full setup with dynamic badges and regression detection, see the CI/CD guide.

What does the --strict flag do?

The --strict flag has two effects depending on the command:

  • zenzic check links --strict / zenzic check all --strict: also validates external HTTP/HTTPS links via network requests (disabled by default for speed).
  • zenzic check references --strict: treats Dead Definitions (reference links defined but never used) as hard errors instead of warnings.

Recommended in CI pipelines to catch all classes of issues.

What is the Zenzic Shield (exit code 2)?

Exit code 2 means the reference check detected a pattern that looks like a credential (API key, token, password) in a URL or text. Rotate the credential immediately if you receive this exit code.

What is the Blood Sentinel (exit code 3)?

Exit code 3 means a link resolves to an OS system directory (/etc/, /root/, /var/, etc.). This is treated as a security incident and cannot be suppressed. Remove the offending link path.

Why does Zenzic report DANGLING_REFERENCE when I defined the link at the bottom of the file?

Your reference definition is likely being silently deleted by another tool in your pipeline. markdownlint --fix (a common pre-commit hook) removes bare [id]: url reference definitions when they appear in certain positions — after HTML blocks, <figure> tags, or before the first heading — without reporting which rule triggered the removal. The line simply disappears.

Solution: Use inline links ([text](url)) instead of reference-style links ([text][id] + [id]: url at the bottom). Inline links are immune to this class of linter interference and are the recommended format for documentation in repositories with aggressive linting pipelines.

Troubleshooting​

Zenzic passes but my build engine reports broken links (or vice versa).

This usually happens when frontmatter slug overrides move a page's URL away from its filesystem location. Zenzic resolves relative links from the file path; build engines like Docusaurus resolve them from the URL path (after slug mapping). When a file at docs/guides/checks.mdx has slug: /checks, the two systems disagree on where ../ leads.

Solution: remove the slug override and let the URL follow the filesystem. If you moved a file to docs/guides/checks.mdx, its URL becomes /docs/guides/checks — both Zenzic and the build engine will then resolve ../ identically. If you need the old URL for external links, configure a server-side redirect instead of a slug override.