lee/zensical
1
0
Fork 0
mirror of https://github.com/zensical/zensical.git synced 2026-09-22 14:25:38 +00:00
Code Issues Packages Projects Releases Wiki Activity
411 Commits 2 Branches 60 Tags
bee1c3f7ea1900fbe4e7e8eeae533d4b89437a4c
Commit Graph
411 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
Timothée Mazzucotelli bee1c3f7ea fix: give higher priority than superfences to macros preprocessor (#638) 
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
 2026-05-05 21:41:00 +00:00
Martin Donath bc3e017c30 chore: release v0.0.40 
## Summary

This version adds support for [macros], covering the functionality of the `mkdocs-macros-plugin`. Macros allow you to define custom variables and functions that can be used in your Markdown files, making it easier to manage and reuse content across your documentation.

We've implemented macros support as a Python Markdown extension, since it's essentially a Markdown preprocessor that doesn't need to be aware of the rest of Zensical's rendering process, except for the current page and configuration. The benefit is that it can now also be used in Python docstrings to build API documentation with [mkdocstrings].

[macros]: https://zensical.org/docs/setup/extensions/macros/
[mkdocstrings]: https://mkdocstrings.github.io

Signed-off-by: squidfunk <martin.donath@squidfunk.com>
v0.0.40 		2026-05-04 17:49:13 +02:00
Martin Donath bdc3471b79 fix: update ui to v0.0.16 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-04 17:46:43 +02:00
Martin Donath 36b5131574 feature: exclude macros blocks from link validation 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-04 16:45:06 +02:00
Timothée Mazzucotelli f7fe088a37 feature: support macros plugin 
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
 2026-05-04 14:40:04 +00:00
Timothée Mazzucotelli 91090e9917 refactor: combine file watching for extensions 
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
 2026-05-04 12:05:41 +00:00
Timothée Mazzucotelli 91a9f85d77 chore: fix import in test file 
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
 2026-05-04 11:02:50 +00:00
Timothée Mazzucotelli b2fdc788d4 refactor: pass rendering context into preprocessor 
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
 2026-05-04 09:55:15 +00:00
Timothée Mazzucotelli c23fb92789 chore: setup pytest and initial markdown extension testing 
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
 2026-05-04 09:32:24 +00:00
Martin Donath 296eb2414a Merge pull request #622 from zensical/fix/link-validation-windows 
fix: link validation exclusions on Windows ignoring `\r` (#615)
 2026-05-04 09:04:33 +02:00
Timothée Mazzucotelli e0c6700c33 chore: set concise output for Ruff 
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
 2026-05-03 21:27:44 +00:00
squidfunk 4be2374fbe fix: link validation doesn't catch end of MathJax when \r present (#615) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-03 19:13:58 +02:00
squidfunk c6cffec95f fix: link validation exclusions don't catch \r\n line feeds 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-03 19:01:03 +02:00
squidfunk 6efe0a3bcc fix: link validation exclusions require empty line after code block (#618) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-03 18:55:05 +02:00
Martin Donath 645bbe881a fix: clear site directory contents instead of removing it (#621) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-03 16:46:58 +02:00
squidfunk 814d2e9edf fix: link validation yields false positives on Windows (#616) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-03 12:39:09 +02:00
Martin DonathandtakeshiD b229bac9ad fix: zensical serve returns 404 after suspend (#574) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
Co-authored-by: takeshiD <goriponikeike55@gmail.com>
 2026-05-01 20:08:37 +02:00
Martin Donath b5492cef2e fix: shim for mkdocs-glightbox fails when only defaults are set (#611) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-01 19:32:54 +02:00
Martin Donath 0291ad5360 chore: release v0.0.39 
## Summary

This version fixes several bugs related to link validation and lightbox configuration.

Signed-off-by: squidfunk <martin.donath@squidfunk.com>
v0.0.39 		2026-05-01 18:24:15 +02:00
Martin Donath fe42fc4dde fix: shim for MkDocs validation syntax overrides Zensical's (#607) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-01 18:18:35 +02:00
Martin Donath 89d99bafaf Merge pull request #597 from zensical/fix/validation-text-fragment 
fix: anchor not extracted from combined anchor-text-fragment
 2026-05-01 18:02:52 +02:00
Martin Donath 273dd2313a fix: auto-themed gallery takes precedence over explicit grouping 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-01 17:37:02 +02:00
Martin Donath b693a2fe4b Fix glightbox captions (#605) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-01 13:46:55 +02:00
squidfunk dfc74bf921 chore: fix ty warning 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-01 13:39:22 +02:00
squidfunk 3e27d6954b refactor: move glightbox config options to dataclass 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-01 13:36:14 +02:00
squidfunk 8ed39039ce chore: disable ruff's N802 globally 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-01 13:27:06 +02:00
squidfunk c050add8a0 fix: error when setting caption_position on glightbox extension (#604) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-01 13:12:13 +02:00
squidfunk 699d3be0f6 fix: add Python backtrace on Markdown rendering error 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-05-01 13:09:24 +02:00
squidfunk acc2620a57 fix: validation doesn't correctly map percent-encoded links (#598) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-30 17:33:54 +02:00
squidfunk da317bf201 fix: add $...$ and $$...$$ blocks to exclusions for link validation (#599) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-30 17:20:41 +02:00
squidfunk 94f0d29756 fix: anchor not extracted from combined anchor-text-fragment 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-30 15:31:21 +02:00
Martin Donath 2f6ce8c5aa chore: upgrade Docker image to latest Alpine 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-30 14:54:25 +02:00
Martin Donath 0e7f1d8cf8 chore: release v0.0.38 
## 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>
v0.0.38 		2026-04-30 13:56:34 +02:00
Martin Donath 201c615cd0 feature: add link and footnote validation and --strict mode (#175) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-30 13:17:23 +02:00
Timothée Mazzucotelli b3c1d91ed8 refactor: use our markdown subclasses 
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
 2026-04-28 12:34:15 +00:00
Martin Donath ce8cbf817c refactor: simplify function definitions after zrx upgrade 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-27 16:56:48 +02:00
Martin Donath 55c9d26e91 chore: release v0.0.37 
## Summary

This version adds support for installable themes. You can now bundle your theme overrides and package them into a custom theme which can be installed via `pip`.

As of now, we closely mirror the process used by MkDocs, where themes just need to register themselves in the `mkdocs.themes` entrypoint, to allow users that already have derivations of Material for MkDocs to run them on Zensical. In the coming months, with the advent of the [component system], we'll make this process much more flexible and foster reuse at the component level. For now, this is a first step to allow sharing of theme overrides and default configurations inside organizations with dozens or even thousands of projects.

> [!TIP]
>
> If your organization has been a happy user of Material for MkDocs and is considering switching to Zensical, please support our work through [Zensical Spark]. Your financial contribution helps us achieve full compatibility with MkDocs much faster, gives you access to hands-on support by the core team, and allows you to shape Zensical together with us.

[component system]: https://zensical.org/about/roadmap/#component-system
[Zensical Spark]: https://zensical.org/spark/

Signed-off-by: squidfunk <martin.donath@squidfunk.com>
v0.0.37 		2026-04-27 09:54:04 +02:00
Martin Donath 5178689c7a chore: fix ty warning 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-27 09:35:01 +02:00
Martin Donath 5fd8871c6a fix: revert change in search processor (regression) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-26 17:01:37 +02:00
Martin Donath 99d53f68c2 feature: add collectors to extract references for link validation 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-25 15:13:54 +02:00
Martin DonathandTimothée Mazzucotelli 98720928cc refactor: subclass Markdown processors to extend functionality 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr>
 2026-04-25 13:42:39 +02:00
Timothée Mazzucotelli 72ba12236b fix: sanitize nested metadata (#582) 
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
 2026-04-25 11:26:28 +00:00
Timothée Mazzucotelli dfb73ff1f3 chore: switch to ty 
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
 2026-04-24 17:14:04 +00:00
Martin Donath c937ed3c4d Merge pull request #577 from zensical/fix/glightbox-title 
fix: attributes not applied to lightbox images
 2026-04-24 16:17:38 +02:00
squidfunk 2fb663e1fd fix: text adjacent to image included in link to open image in lightbox (#579) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-24 16:04:53 +02:00
squidfunk dc32baf98f fix: anchor links preserved in table of content section titles (#578) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-24 14:16:11 +02:00
squidfunk fdeb0616cd refactor: use identical name for tree- and postprocessor 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-24 13:58:01 +02:00
squidfunk 127648e743 fix: attributes not applied to lightbox images 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-24 13:55:20 +02:00
Timothée Mazzucotelliandsquidfunk 76945357dc feature: installable theme extensions (#511) 
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
Co-authored-by: squidfunk <martin.donath@squidfunk.com>
 2026-04-24 13:37:59 +02:00
Timothée Mazzucotelli 46b03e5d7c chore: add spacing in markdown example 
This also makes the markup for lists compliant with Python-Markdown (required blank line before).

Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
 2026-04-24 09:25:59 +00:00