mirror of
https://github.com/zensical/zensical.git
synced 2026-05-03 09:30:43 +00:00
Martin Donath
0e7f1d8cf8
## 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. [link and footnote validation]: https://zensical.org/docs/setup/validation/ [strict mode]: https://zensical.org/docs/setup/validation/#strict-mode ### 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. ``` console $ zensical build ... Warning: page does not exist ╭─[ index.md:3:14 ] │ 3 │ [this page]: non-existent.md │ ───────┬─────── │ ╰───────── page does not exist ───╯ ``` The following checks for links and footnotes are now available: - [`unresolved_references`](https://zensical.org/docs/setup/validation/#unresolved_references) - [`unresolved_footnotes`](https://zensical.org/docs/setup/validation/#unresolved_footnotes) - [`unused_definitions`](https://zensical.org/docs/setup/validation/#unused_definitions) - [`unused_footnotes`](https://zensical.org/docs/setup/validation/#unused_footnotes) - [`shadowed_definitions`](https://zensical.org/docs/setup/validation/#shadowed_definitions) - [`shadowed_footnotes`](https://zensical.org/docs/setup/validation/#shadowed_footnotes) - [`invalid_links`](https://zensical.org/docs/setup/validation/#invalid_links) - [`invalid_link_anchors`](https://zensical.org/docs/setup/validation/#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: ``` console $ 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](https://zensical.org/docs/setup/validation/), you can use: ``` toml [project] validation = false ``` As always, if you run into any problems, please [open an issue](https://github.com/zensical/zensical/issues). [as we did]: https://github.com/zensical/docs/commit/facabcce36977468ef6465f2ac19ff68b692ada2 [disable validation entirely]: https://zensical.org/docs/setup/validation/#configuration-zensicaltoml_1 Signed-off-by: squidfunk <martin.donath@squidfunk.com>
A modern static site generator built by the creators of Material for MkDocs
Home · Get started · Compatibility · Roadmap · Newsletter · Zensical Spark
Write your documentation in Markdown and create a professional static site for your Open Source or commercial project in minutes – searchable, customizable, more than 60 languages, for all devices.
Visit our documentation at zensical.org/docs/.
Zensical Spark
Zensical Spark is our offering for professionals and organizations using Zensical commercially. It lets us provide best-in-class support, keep the project sustainable, and Zensical free for everyone.
Zensical Spark may be a great fit if you:
- Need help migrating a complex MkDocs project to Zensical
- Want to ensure Zensical meets all your requirements – see how we work
- Want direct support from the core team, including 1:1 sessions
For the full list of benefits, see our subscription tiers.