Skip to content

Upgrading Zensical: 0.0.24 → 0.0.38

This site previously pinned zensical>=0.0.24. As of this writing, the latest release on PyPI is 0.0.38, so I bumped the dependency in pyproject.toml:

pyproject.toml
dependencies = [
    "zensical>=0.0.38",
]

Below is a condensed diff of what landed between those two versions, focused on the user-visible changes. The full release notes live on GitHub.

What changed

0.0.38 — Link & footnote validation, --strict mode

The headline feature: Zensical now validates internal references at build time and reports issues with precise source locations. New checks (all enabled by default):

  • unresolved_references, unresolved_footnotes
  • unused_definitions, unused_footnotes
  • shadowed_definitions, shadowed_footnotes
  • invalid_links, invalid_link_anchors

Pair them with the new --strict flag in CI to fail the build on any warning:

Bash
zensical build --strict

Sample output:

Text Only
Warning: page does not exist
   ╭─[ index.md:3:14 ]
   │
 3 │ [id]: non-existent.md
   │       ───────┬───────
   │              ╰───────── page does not exist
───╯

If you want to opt out:

zensical.toml
[project]
validation = false

0.0.37 — Installable themes

You can now package theme overrides as a pip-installable distribution by registering an entry point under mkdocs.themes. Inside an organization with many sites, this lets you publish one shared theme and consume it everywhere:

pyproject.toml of a custom theme package
[project.entry-points."mkdocs.themes"]
my-theme = "my_theme"
zensical.toml of any consuming site
[project.theme]
name = "my-theme"

0.0.35 — GLightbox, HTML in TOC, relative links in raw HTML

Native GLightbox integration via a new Markdown extension — faster than the MkDocs plugin because it hooks into Python Markdown directly:

zensical.toml
[project.markdown_extensions.zensical.extensions.glightbox]

Section titles in the table of contents now render with inline HTML/markup (emojis, code spans, etc.), replacing the old typeset plugin from Material for MkDocs. Relative links inside raw HTML blocks are also resolved correctly now.

0.0.34 — TOML 1.1.0 in zensical.toml, ZRX rewrite

Configuration parsing was upgraded to TOML 1.1.0, which allows newlines inside inline tables. Long lists become much more readable:

zensical.toml
[[project.theme.palette]]
primary = "indigo"
accent = "indigo"
media = "(prefers-color-scheme: light)"
scheme = "default"
toggle = {
  icon = "lucide/sun",
  name = "Switch to dark mode"
}

Markdown pages that include snippets are also now rebuilt automatically when a snippet changes.

0.0.33 — Better zensical new defaults

Bootstrapping a new project with zensical new now writes a zensical.toml that already includes the recommended Markdown extensions. The official Docker image switched its base to Alpine Linux.

0.0.30 — Versioning via mike

Multi-version sites on GitHub Pages are supported through a Zensical-tailored fork of mike. Standard mike commands work as expected; native versioning is on the roadmap.

0.0.25 – 0.0.32 — Bug fixes & refactorings

Mostly polish: UI updates (Lucide v1 icons, mobile TOC), Pygments CVE mitigation, snippets/auto-nav fixes, base-URL prefix handling, Windows file watching, and absolute-link handling. Worth upgrading for these alone.

What I had to change in this repo

Just the version pin in pyproject.toml. Everything else in zensical.toml is forward-compatible — no breaking changes affected my configuration.

To pull the new version in:

Bash
uv sync

Then verify with a build:

Bash
uv run zensical build --strict

The --strict flag is a quick way to surface any latent broken links the new validator finds.