zensical

library0.0.33pypypiunverified

Zensical is a modern static site generator built by the creators of Material for MkDocs. It focuses on performance, extensibility, and a smooth developer experience, leveraging a Rust core. The current version is 0.0.33, with frequent releases addressing bugs and introducing new features.

devops

pip install zensical

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · ZENSICAL

zensical

devopspythonv0.0.33

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Start a new Zensical project and serve it locally for development. This demonstrates the typical CLI-first interaction with the library.

# Zensical is primarily a command-line interface (CLI) tool. # First, initialize a new Zensical project in the current directory: zensical new . # This will create a `zensical.toml` configuration file and a `docs/` # directory with example content. # Then, serve the site locally and watch for changes: zensical serve # The site will typically be available at http://127.0.0.1:8000

Debug

Known issues

breakingThe user interface update in v0.0.31, which upgraded Lucide to v1, led to the removal of 19 brand icons. Projects relying on these specific icons will need to update their configuration or choose alternative icons.

fix

Review your project's icon usage. Consult Lucide v1 migration guides for a list of removed icons and available alternatives.

affects: >=0.0.31

gotchaVersion 0.0.26 had a regression where manylinux x86 wheels were incorrectly built for Python 3.8 instead of the required Python 3.10+, causing installation failures on affected architectures.

fix

Ensure you are using Python 3.10 or newer and update to the latest Zensical version (>=0.0.27) to avoid this specific packaging issue. Verify your Python environment if installation fails.

affects: 0.0.26

gotchaWhen bootstrapping a new project with `zensical new` prior to v0.0.33, the generated `zensical.toml` file might not include all recommended Markdown Extensions. This could lead to a less feature-rich setup out-of-the-box.

fix

For projects initialized before v0.0.33, manually add desired Markdown Extensions to your `zensical.toml` file or consider regenerating the config if starting a new project.

affects: <0.0.33

deprecatedZensical introduced a tailored fork of `mike` (v0.0.30) for managing multiple documentation versions. This is noted as a temporary solution, with native versioning support planned for future releases. The current `mike` integration may change.

fix

Be aware that the `mike` integration might evolve. Monitor Zensical's official releases and documentation for updates on native versioning support and potential migration paths from the `mike` workflow.

affects: >=0.0.30

Errors

Common errors & fixes

error: linker `cc` not found

The Rust compiler (or a dependency) requires a C compiler to build native components, but it cannot find one installed on your system.

fix

Install C/C++ build tools appropriate for your operating system. For Linux (Debian/Ubuntu): `sudo apt-get install build-essential`. For macOS: `xcode-select --install`. For Windows: Install Visual Studio Build Tools (including 'Desktop development with C++').

zensical: command not found

The `zensical` executable was either not installed successfully or the directory where Cargo places executables is not included in your system's PATH environment variable.

fix

Ensure `cargo install zensical` completed without errors. Then, add Cargo's binary directory (`$HOME/.cargo/bin` on Linux/macOS, or `%USERPROFILE%\.cargo\bin` on Windows) to your system's PATH. You might need to restart your terminal or shell to apply changes.

ld: library not found for -lssl

The `zensical` build process (or one of its dependencies) requires the OpenSSL development libraries, but the linker cannot find them on your system, often on macOS or some Linux distributions.

fix

Install OpenSSL development libraries. For macOS with Homebrew: `brew install openssl`. For Debian/Ubuntu: `sudo apt-get install libssl-dev`. You may also need to set environment variables like `OPENSSL_DIR` or `PKG_CONFIG_PATH` to help the linker find it, e.g., `export OPENSSL_DIR=$(brew --prefix openssl)`.

LINK : fatal error LNK1104: cannot open file 'python3.lib'

On Windows, when building `zensical` or a dependency that links against Python, the linker cannot find the `python3.lib` file, usually because Python was not installed with development headers/libraries or its path isn't correctly configured for the linker.

fix

Reinstall Python on Windows and ensure you select the option to 'Install development headers and libraries' or 'Add Python to environment variables'. Also, ensure that Visual Studio C++ build tools are correctly installed and configured for your environment.

Error: I/O error: Directory not found (os error 2)

This error typically occurs when `zensical build` or `zensical serve` is run from a directory that is not a valid `zensical` project, or when the `zensical.toml` configuration file specifies a non-existent source or output directory.

fix

Ensure you are running the command from the root directory of your `zensical` project. If you are starting a new project, use `zensical new <project-name>` first. Verify that all paths referenced in your `zensical.toml` configuration file (e.g., `src_dir`, `out_dir`) exist and are correct.

Upgrade

Version history

0.0.33latest on PyPI · released Apr 14, 2026

Audit

Dependencies

pythonrequiredZensical requires Python 3.10 or newer to run.

PygmentsoptionalUsed for syntax highlighting in code blocks; updated in v0.0.32 to mitigate a vulnerability.

Agent activity

24 hits · last 30 days

node

Resources

githubhttps://github.com/zensical/zensical ↗

packagehttps://pypi.org/project/zensical/ ↗

homepagehttps://zensical.org/ ↗

docshttps://zensical.org/docs/ ↗

changeloghttps://zensical.org/docs/changelog/ ↗