zensical/zensical v0.0.38

0.0.38

on GitHub

Summary

This version adds link and footnote validation and strict mode – two of the most frequently requested features. Zensical now checks all internal references at build time and reports issues with precise source locations, so broken links don't make it into your published documentation. Unlike MkDocs, which only validates final rendered links, Zensical also checks for unresolved references, as well as unused and shadowed definitions – covering the full lifecycle of a reference from definition to use.

Validation

Zensical scans every Markdown file in your project and resolves all internal references against each other: inline links, reference-style links, footnotes, link definitions, and anchor targets. Every check is individually configurable and enabled by default.

$ zensical build
...
Warning: page does not exist
   ╭─[ index.md:3:14 ]
   │
 3 │ [id]: non-existent.md
   │       ───────┬───────
   │              ╰───────── page does not exist
───╯

The following checks for links and footnotes are now available:

• unresolved_references
• unresolved_footnotes
• unused_definitions
• unused_footnotes
• shadowed_definitions
• shadowed_footnotes
• invalid_links
• invalid_link_anchors

Strict mode

The new --strict command line flag causes the build to fail when any enabled validation check triggers, turning warnings into errors. This is useful for CI pipelines where you want to enforce link integrity and prevent broken documentation from being published:

$ zensical build --strict
...
Warning: unresolved link reference
   ╭─[ index.md:1:35 ]
   │
 1 │ This is an [unresolved reference][id].
   │                                   ─┬
   │                                    ╰── unresolved link reference
───╯
1 issue found
Aborted because --strict flag is set

Upgrading

No changes to your configuration are required – all checks are enabled by default. It's quite likely that you'll run into at least some warnings – as we did – when upgrading, since before, it was easy to miss unused link definitions or unresolved references. If you want to disable validation entirely, you can use:

[project]
validation = false

As always, if you run into any problems, please open an issue.

Changelog

Features

• 201c615 zensical, compat – add link and footnote validation and --strict mode (#175)

Refactorings

• b3c1d91 zensical, compat – add custom Markdown subclasses
• ce8cbf8 zensical – simplify function definitions after zrx upgrade