## 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>
## 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>
## 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>
## 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>
## 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>
This version adds the missing update of the user interface that should've been included with 0.0.35.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version adds native support for [GLightbox], a JavaScript lightbox library to add zoom and gallery features to images. Images can be automatically annotated with the new `glightbox` Markdown extension. Add the following to `zensical.toml`:
``` toml
[project.markdown_extensions.zensical.extensions.glightbox]
```
> [!NOTE]
>
> In order to integrate with configuration in `mkdocs.yml`, where [GLightbox] is implemented as a plugin, a compatibility shim is included, so no re-configuration is necessary if you're already using the plugin. Note that our extension is more efficient and faster than the plugin, as it does not re-parse the entire HTML of each page, but instead uses Python Markdown's native extension API.
### HTML in the table of contents
Additionally, __section titles in the table of contents will now render with HTML markup__, so you can use emojis and other inline features in section titles and have them render correctly in the table of contents. In Material for MkDocs, this functionality was implemented with the `typeset` plugin. Zensical now supports this natively.
### Relative links in raw HTML
Relative links in raw HTML are now correctly resolved. Initially, we carried over the link processing and resolution logic from MkDocs, which does not support relative links in raw HTML to this day. We implemented a Python Markdown postprocessor, to ensure that relative links in raw HTML are handled as well.
[GLightbox]: https://biati-digital.github.io/glightbox/
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version ships support for usage of TOML v1.1.0 in `zensical.toml`, which allows new lines in inline tables. Thus, configuration files can now be made more readable, especially when they contain long lists of items. For example:
__Prior to this version__
``` toml
palette = [
{ scheme = "default", toggle = { icon = "lucide/sun", name = "Switch to dark mode" } },
{ scheme = "slate", toggle = { icon = "lucide/moon", name = "Switch to light mode" } },
]
```
__With this version__
``` toml
palette = [
{
scheme = "default",
toggle = {
icon = "lucide/sun",
name = "Switch to dark mode"
}
},
{
scheme = "slate",
toggle = {
icon = "lucide/moon",
name = "Switch to light mode"
}
},
]
```
Additionally, Markdown pages with snippets are now rebuilt when snippets are updated, and an issue with breadcrumbs was fixed when the top-level `index.md` was not at the root of `nav` defined explicitly.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version updates our official [Docker image] to be based on Alpine Linux for better compatibility and ease of use. It also adds all recommended Markdown Extensions to the generated `zensical.toml` file when bootstrapping a project with `zensical new`, ensuring a smoother setup experience. Additionally, the [user interface] is updated to [v0.0.13], which includes two bug fixes for anchor links in the table of contents.
[Docker image]: https://hub.docker.com/r/zensical/zensical
[user interface]: https://github.com/zensical/ui
[v0.0.13]: https://github.com/zensical/ui/releases/tag/v0.0.13
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version fixes a bug where Markdown files used as snippets were included into auto-generated navigation, and a bug with prefix stripping when the site URL contains a path component. Additionally, the Pygments dependency was updated to mitigate a vulnerability.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version updates the [user interface] to [v0.0.12], which includes the [removal of 19 brand icons] due to the update of Lucide to v1, and the addition of 166 new icons, most of them in SimpleIcons and FontAwesome. Additionally, there are bug fixes related to the latest changes of the table of contents in the modern theme and instant navigation on anchor links.
[user interface]: https://github.com/zensical/ui
[v0.0.12]: https://github.com/zensical/ui/releases/tag/v0.0.12
[removal of 19 brand icons]: https://lucide.dev/guide/version-1
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version adds support for [mike], a tool for managing multiple versions of MkDocs projects on GitHub Pages. We created [a tailored fork of mike] for Zensical – all mike commands should work as expected. See the [mike documentation] for usage instructions.
Note that this is a temporary solution. Zensical will ship [native support for versioning] in the near future, which will remove the GitHub Pages constraint and offer more flexibility in how versions are deployed and served.
The [user interface] is updated to [v0.0.11], which adds a floating table of contents for mobile to the modern theme. The toggle sits at the bottom of the screen for easy thumb access, and the sidebar scrolls to accommodate arbitrarily long tables of contents. This release also includes several improvements: snappier sidebar animations, better tooltip readability, and improved inline code block sizing.
[mike]: https://github.com/jimporter/mike
[a tailored fork of mike]: https://github.com/squidfunk/mike
[native support for versioning]: https://zensical.org/about/roadmap/#versioning
[mike documentation]: https://github.com/jimporter/mike#readme
[user interface]: https://github.com/zensical/ui
[v0.0.11]: https://github.com/zensical/ui/releases/tag/v0.0.11
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version fixes an issue with absolute paths in links, as well as changed files not being picked up by Zensical on Windows 11.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version updates the [user interface] to [v0.0.10], which fixes a couple of bugs related to search and code annotation rendering. Additionally, it adds support for version selectors in the modern theme, paving the way for adding support for [mike] to manage multiple versions of documentation on GitHub Pages.
In addition, this release adds new configuration options for the file watcher to improve compatibility in certain environments.
### File watcher
You can now opt into using a **polling-based file watcher**, which is particularly useful when running Docker on Windows, where filesystem event limitations (e.g., inotify constraints) can cause issues.
To enable the polling watcher:
``` bash
export ZENSICAL_POLL_WATCHER=1
```
The polling interval is configurable and defaults to `500` milliseconds (aligned with MkDocs behavior):
``` bash
export ZENSICAL_POLL_INTERVAL=500
```
[user interface]: https://github.com/zensical/ui
[v0.0.10]: https://github.com/zensical/ui/releases/tag/v0.0.10
[mike]: https://github.com/jimporter/mike
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version fixes a reload loop for when auto-appended snippets are located inside of the `docs` directory, and auto-reload for pages with Chinese path segments.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
# Summary
This version fixes a regression introduced in 0.0.25 where the wheels built for manylinux x86 would be based on Python 3.8 instead of Python 3.10, making Zensical unusable on those architectures. This is
related to a [recent bug] in our upstream dependency [maturin], which was introduced in version 1.12.5. Additionally, it fixes a deprecation warning on Python 3.14 when using the emoji extension.
[recent bug]: https://github.com/PyO3/maturin/issues/3059
[maturin]: https://github.com/PyO3/maturin
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version updates the [user interface] to [v0.0.9], which improves on accessibility and fixes some minor rendering issues. Additionally, it fixes some bugs related to configuration parsing and plugin handling in `zensical serve`, ensuring a smoother development experience.
[user interface]: https://github.com/zensical/ui
[v0.0.9]: https://github.com/zensical/ui/releases/tag/v0.0.9
### Highlights
- `zensical serve` now keeps running on configuration parsing errors
- Auto-appended `pymdownx.snippets` files are now watched for changes
- Search highlighting now works with keyboard navigation
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version updates the [user interface] to [v0.0.8], which fixes issues with instant previews for Chinese and other non-ASCII languages, and layout shifts when switching from short to long pages in the modern theme. Additionally, same-page links for when directory URLs are disabled where not resolved correctly, which is fixed as well.
[user interface]: https://github.com/zensical/ui
[v0.0.8]: https://github.com/zensical/ui/releases/tag/v0.0.8
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
# Summary
This version fixes a regression introduced in 0.0.22, where builds would error with mkdocstrings being not found, although the plugin wasn't configured.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
This version updates the [user interface] to [v0.0.6], which fixes excessive memory usage for pages with hundreds of links that are marked with data-preview (for instant previews), among several other improvements and bug fixes.
[user interface]: https://github.com/zensical/ui
[v0.0.6]: https://github.com/zensical/ui/releases/tag/v0.0.6
- Back-to-top button was moved to the bottom for `modern` theme
- Several fixes for instant previews, improving memory usage and usability
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
## Summary
This version fixes excessive memory usage when building large mkdocstrings-powered documentation sites. Additionally, it fixes an issue where the build sometimes terminates prematurely. We're working on further improvements to memory consumption and stability in upcoming releases, as we're currently refactoring a significant part of the runtime.
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
This version adds support for the generation of `objects.inv` for your [mkdocstrings]-powered documentation site, allowing external tools to discover and link to your API documentation. No changes to your configuration are necessary.
Please also update to mkdocstrings v1.0.2.
[mkdocstrings]: https://mkdocstrings.github.io/
Signed-off-by: squidfunk <martin.donath@squidfunk.com>
Martin Donath