## Summary
This version fixes two false positives in the reference extractor and reverts Zensical's bootstrapped `zensical.toml` to TOML 1.0, since most editor tooling does not yet support TOML 1.1. Zensical understands both, TOML 1.0 and TOML 1.1, so this change does not affect the functionality of Zensical itself.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version significantly reduces peak memory usage by 8–10×, making builds of large documentation projects substantially more efficient. It also improves reference validation by preventing false positives for links successfully resolved through autorefs.
Additionally, the [user interface](https://github.com/zensical/ui) is updated to [v0.0.25](https://github.com/zensical/ui/releases/tag/v0.0.25), fixing instant navigation for inline scripts and version aliases created with `mike`. This release also corrects `mike` configuration defaults and updates `webbrowser` to address a security vulnerability.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
This commit fixes validation reporting false unresolved-reference errors for Markdown links that are successfully resolved by autorefs. Validation now runs after pages render, so it uses the autorefs results from the current build state and emits one complete issue report for that state.
**Validation implementation summary:**
- Page rendering now returns the identifiers that autorefs resolved, alongside rendered output.
- Validation combines those resolutions with the source-page references and anchors; a reference resolved by autorefs is no longer reported as unresolved.
- The workflow tracks a generation for page content and navigation, so it waits for matching render results from every page before creating issues. This prevents validation from using stale render data or printing duplicate reports during incremental updates.
- Reference collection now follows the configured documentation directory, and tests cover reporting after rendering and a subsequent clean rebuild.
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
## Summary
This version adds support for enabling strict mode directly in `mkdocs.yml` or `zensical.toml`, allowing warnings to fail builds consistently without the `--strict` command-line option. It also reduces memory usage by sharing cross-reference data between navigation clones.
Additionally, the user interface is updated to `v0.0.24`, improving search rendering for right-to-left languages and adding four new Lucide icons. The generated `zensical.toml` now uses TOML 1.1 syntax, and `pymdownx` is updated to version 11.0 to address a vulnerability.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version adds search support for CJK languages: Chinese, Japanese, and Korean. Search needs to segment text into individual words before it can index and match them. While many languages separate words with spaces, this is not consistently the case for CJK text, particularly Chinese and Japanese. Search now uses locale-aware segmentation to identify meaningful word boundaries, ensuring that content and queries are indexed and matched correctly.
Set the [site language](https://zensical.org/docs/setup/language/#site-language) to `zh`, `zh-Hant`, `zh-TW`, `ja`, or `ko` to enable segmentation.
The search modal is also larger, showing more results and context at once. Additionally, keyboard keys inside admonitions now use the correct background color in the modern theme.
Dependencies and development tooling were updated, including TypeScript 7. The build scripts now use `tsx` instead of `ts-node`, and `npm-run-all2` replaces the unmaintained `npm-run-all`. Updated icon packages add 56 new icons: 23 Font Awesome icons, 21 Lucide icons, 8 Octicons, and 4 Simple Icons.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version improves cached rebuilds by persisting `objects.inv` and autorefs data, fixes stale builds after removing files, and upgrades `soupsieve` to address vulnerabilities.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
On a first build without cache, pages are built and cross-references resolved thanks to the autorefs data retrieved from the Python interpreter.
On a second build, if a page changed, the cache is not reused, so the page is rebuilt and cross-references within it must be resolved again, but if the target symbols were rendered in other, already cached pages, the Python interpreter doesn't hold the necessary data to resolve these cross-references.
We fix this by caching autorefs data. We still need to update the data retrieved from the cache with the data retrieved from the Python interpreter, to give precedence to autorefs data for pages that were rebuilt.
This solution still has the issue that stale data is never removed from the cache (for example, symbols that were completely deleted from the sources and API docs). The API would have to change a lot and often for it to have an impact though. Cleaning (`rm .cache/autorefs.json` or `zensical build --clean`) from time to time easily mitigates this.
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
## Summary
This release adds native support for [markdown-exec](https://github.com/pawamoy/markdown-exec), improves compatibility around generated URLs and project configuration, and updates the user interface to `v0.0.20`.
Zensical now supports [markdown-exec], an MkDocs plugin that executes Python code blocks during the build and injects the result into the rendered page. In practice, this makes it easier to build interactive technical documentation, generated examples, and executable snippets that integrate directly with the theme in both `classic` and `modern` variants.
Additionally, the [user interface](https://github.com/zensical/ui) is updated to [v0.0.20](https://github.com/zensical/ui/releases/tag/v0.0.20), which includes client-side support for `markdown-exec` and several styling and interaction fixes. Mermaid diagram colors are now applied correctly for sequence numbers and activations, flow chart arrows, and state diagram arrows. Search filter scrollbars no longer overlap selectable items, and images using `data-gallery` are attributed correctly again.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
Thanks to Sinan Polat for reporting the issue and providing a clear analysis and proof of concept.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version improves search result quality and includes several bug fixes and refactorings.
### Search excerpts
Search results now include excerpts, making it easier to understand why a result matches. Search remains fully client-side and as fast as before, even for projects with thousands of pages. We still consider search an active area of iteration and expect to further improve it and expose more configuration options over time.
### User interface
The [user interface] is updated to [v0.0.19], which includes several navigation and interaction fixes. Search highlighting now ignores single-character tokens, which avoids noisy matches like highlighting every `e` for queries such as `e-mail`. Instant previews now include a hover bridge so moving the cursor from a link to the tooltip no longer drops the popup across the visual gap.
[user interface]: https://github.com/zensical/ui
[v0.0.19]: https://github.com/zensical/ui/releases/tag/v0.0.19
Dependencies were also updated, including TypeScript 6 and SVGO 4 compatibility adjustments. 83 new icons were added, 2 icons were removed, and 19 icons were modified. The Lucide icon set was updated to version v1.21.0.
### Validation defaults
The validation options `unresolved_references`, `unresolved_footnotes`, `unused_definitions`, `unused_footnotes`, `shadowed_definitions`, and `shadowed_footnotes` are now disabled by default. These checks remain available when explicitly enabled, but they have proven too unstable in edge cases with the current reference parser. They will eventually be superseded by the higher-fidelity parser that is already used by [Zensical Studio] and is planned for Open Source release and later integration into Zensical.
[Zensical Studio]: https://zensical.org/studio/
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version reverts a behavior change in link validation that was introduced in 0.0.44 which is causing false positives.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version fixes several bugs related to link validation and macros, and ensures that dotfiles are not removed from the site directory during generation.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version fixes further edge cases in link validation, and adds support for UTF-8 encoding with byte-order-marks.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version includes a number of bug fixes and refactorings to improve the stability and accuracy of link validation, and fixes a reload loop when the `custom_dir`, which is auto-watched, is explicitly added to `watch`. Moreover, GLightbox is now only downloaded when needed, which fixes an issue when using Zensical in air-gapped environments.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## 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>
## Summary
This version fixes several bugs related to link validation and lightbox configuration.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
Martin Donath