Skip to content

Get started

Zensical is a modern static site generator designed to simplify building and maintaining project documentation. It's built by the creators of Material for MkDocs and shares the same core design principles and philosophy – batteries included, easy to use, with powerful customization options.

You can learn more about how both projects interconnect with each other here.

Installation

Zensical is written in Rust and Python, and is published as a Python package. We recommend to use a Python virtual environment when installing with pip or with uv. Both options automatically install all necessary dependencies alongside Zensical.

Prerequisites

You need to have Python and a Python package manager installed on your system before you install Zensical. We recommend you follow the Python Setup and Usage instructions for your operating system provided on the Python website. Modern Python distributions include the pip package manager, so unless you are developing Python software and use uv, this is the simplest option to install Zensical on your system.

Use with Docker

If you are familiar with Docker and wish to use Zensical in a container then you can use our official Docker image. For installation and usage instructions, see the documentation on Docker Hub.

Install with pip

Zensical can be installed into a virtual environment1 with pip.

Open up a terminal window and install Zensical by first setting up a virtual environment and then using pip to install the Zensical package into it:

python3 -m venv .venv
source .venv/bin/activate
pip install zensical

Open up a Command Window and install Zensical by first setting up a virtual environment and then using pip to install the Zensical package into it:

python -m venv .venv  # (1)!
.venv\Scripts\activate
pip install zensical
  1. Depending on your Python installation, you may need to use a different binary name such as python3 or use py -3.

Open up a terminal window and install Zensical by first setting up a virtual environment and then using pip to install the Zensical package into it:

python3 -m venv .venv
source .venv/bin/activate
pip install zensical

Install with uv

If you are developing software using Python, chances are you're already using uv as a package and project manager, which has become popular in recent years.

To install Zensical with uv and add it to your development dependencies in your pyproject.toml, use:

uv init
uv add --dev zensical
uv run zensical

Note that when using Zensical as a project dependency, you need to always either use uv run or activate the project's virtual environment manually.

Running as a uv tool

We recommend always running Zensical from a project virtual environment to make sure the version used is well defined. However, uv can also run Zensical as a tool with a one-liner. See the uv documentation for details.

Other tools using PyPI

There are, of course, other dependency managers and build tools in the Python ecosystem that use PyPI as the repository. Installing Zensical with them should be similar to the process of installing with uv. Refer to their documentation for details.

Third-party distributions

There are other distributions that make Zensical available but they may or may not use the official packages we distribute exclusively through PyPI. You can use these distributions if you have good reasons to do so but for normal use we recommend the installation methods above that we officially support.

Install with Anaconda/Mamba

Zensical is available in the conda-forge community repository so that it can be installed using Anaconda or Mamba.

Warning

We cannot provide support for distributions we do not control. If you experience any issues please contact the maintainers of conda-forge/zensical-feedstock.

conda create -n zensical python=3.14
conda activate zensical
conda install -c conda-forge zensical

If you are using Anaconda or Mamaba, make sure that the base environment is activated. If you are using Anaconda, you can just open an Anaconda Prompt. If you installed Mamba as part of Miniforge, there will be an equivalent Miniforge Prompt.

conda create -n zensical python=3.14
conda activate zensical
conda install -c conda-forge zensical

conda create -n zensical python=3.14
conda activate zensical
conda install -c conda-forge zensical

  1. A Python virtual environment is a folder in your project directory that contains its own copy of Python and any Python packages the project needs. By installing Zensical and its dependencies into a virtual environment you ensure that it does not interfere with other projects on your computer that also use Python. ↩