Skip to content

Zensical

Patch version

This site runs a patched version of Zensical.

Why

The main reason is to patch the rendering context of the integrated MiniJinja engine. As of now, it is deliberately inconsistent.

While you can access pages from sitemap or 404 templates, this variable is excluded for templates with more dynamic context.

However, it is crucial to access it for building index pages (blog, tags, etc) that act as collections of subsequent pages.

Another reason is to make sure there is no immediate lock-in should the commercial focus of the development lead to design decisions that do not match the current workflow for small documentation projects any longer.

How it is working

It injects the build artifact from codeshell/zensical/releases1 into the build workflow2 using a GitHub repository variable ${{ vars.ZENSICAL_LINUX_WHL }}.

This has two advantages:

  • It is not necessary to build the patched version locally
  • The dependencies in the Zensical source are not altered.

Switching between the official and custom build is as easy as removing the repository variable or setting it to an empty string. No need to commit any changes to the repository.

Usage

You will find the version specific guide in the release notes.

The following example shows the instructions for v0.0.50. Adjust accordingly.

GitHub Actions (Ubuntu)

- run: |
    curl -L https://github.com/codeshell/zensical/releases/download/v0.0.50-patch-1/zensical-0.0.50-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl -o /tmp/zensical.whl
    uv pip install /tmp/zensical.whl
- run: uv run zensical build --clean

If you do not want to change the workflow file every time the url changes, set it as variable. You can use the workflow of this documentation2 as a reference.

Local Development (Windows)

uv pip install https://github.com/codeshell/zensical/releases/download/v0.0.50-patch-1/zensical-0.0.50-cp310-abi3-win_amd64.whl

Releases

  1. https://github.com/codeshell/zensical/releases ↩

  2. https://github.com/codeshell/docs/blob/main/.github/workflows/deploy.yml ↩↩