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).
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>
Since markdown-exec is not a proper Markdown extension but just a collection of custom superfences for the pymdownx.superfences extension, we cannot directly parametrize it to disable a few things that Zensical doesn't need (compared to MkDocs). We can't make it a proper extension because it modifies the configuration of superfences, hence requiring to run before it in all cases, order which we cannot guarantee since users could enable it themselves as a Markdown extension and after superfences.
To instruct markdown-exec that it runs through Zensical, we set a global variable in its top-level module. This requires that a new version of markdown-exec is published to take it into account when deciding whether to inject assets when rendering Pyodide fences, that Zensical provides natively (contrary to MkDocs).
Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>
## 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>
Timothée Mazzucotelli