Zensical Static Site Generator¶
Zensical pitch
A scalable Open Source systems for technical writing that always keep you in the flow
Zensical is a highly efficient tool for generating websites from Markdown content. Build times are as low as a few seconds for 500+ page site (an order of magnitude faster than most generator tools).
Content is written using Python flavoured Markdown, enabling authors to create a rich user experience without creating additional CSS or JavaScript. This website is an example of that experience.
TOML notation is used to configure a project, defining feature toggles and navigation for the website.
NOTE: Zensical is a reimplementation of "Material for MkDocs" and MkDocs.
Install Zensical¶
Zensical can be installed locally via vu or pip Python package managers. Practicalli recommends Uv for simplicity.
Uv is used to install Zensical as a tool, negating the need for a Python Virtual environment
Practicalli dotfiles Makefile-zensical defines tasks that wrap Zensical commands, providing a consistent and simple command line experience.
Install the latest version of Zensical as a tool using uv (updating if there is a new version).
Run Zensical locally¶
Create a new Zensical project, which adds a docs directory, zensical.toml config and .github/workflow/docs.yml to publish the site vig GitHub pages.
Or clone an existing repository that contains a Zensical project.
Build the website and serve locally at http://localhost:7777
Additional Plugins¶
All plugins are defined within the zensical.toml configuration for the project.
Custom Theme¶
catppuccin-zensical theme plugin is used to enhance the look of the Zensical theme.
Overrides not compatible with theme plugin
Your overrides will not work when using a theme plugin. At the time of writing, the Zensical theme will only work with one set of overrides, which a theme plugin will supersede.
A custom theme can be defined using your own overrides html and css files.