docs/Servers/Documentation/Zensical.md

Purpose

After many years of Material for MKDocs being updated with new features and security updates, it finally reached EOL around the end of 2025. The project maintainers started pivoting to a new successor called Zensical. This document outlines my particular process for setting up a standalone documentation server within a virtual machine.

!!! info "Assumptions" It is assumed that you are deploying this server into Ubuntu Server 24.04.2 LTS (Minimal). It is also assumed that you are running

Setup Python Environment

The first thing we need to do is install the necessary python packages and install the zensical software stack inside of it.

sudo apt update && sudo apt upgrade -y
sudo apt install -y nano python3 python3.12-venv
mkdir -p /srv/zensical
cd /srv/zensical
source .venv/bin/activate
pip install zensical
zensical new .

Configure Zensical Settings

Now we want to set some sensible defaults for Zensical to style it to look as close to Material for MKDocs as possible.

# Scalar Keys
sed -i -E 's/^[[:space:]]*site_name[[:space:]]*=[[:space:]]*".*"/site_name = "Bunny Lab"/' zensical.toml
sed -i -E 's/^[[:space:]]*site_description[[:space:]]*=[[:space:]]*".*"/site_description = "Homelab Knowledgebase"/' zensical.toml
sed -i -E 's/^[[:space:]]*site_author[[:space:]]*=[[:space:]]*".*"/site_author = "Nicole Rappe"/' zensical.toml
sed -i -E 's|^[[:space:]]*#?[[:space:]]*(site_url[[:space:]]*=[[:space:]]*)".*"|\1"https://kb.bunny-lab.io/"|' zensical.toml

# Text inside the copyright triple-quoted string
sed -i -E 's/Copyright[[:space:]]*©[[:space:]]*2026[[:space:]]*The authors/Copyright \© 2026 Bunny Lab/g' zensical.toml

# Theme
sed -i -E 's/^[[:space:]]*#?[[:space:]]*(variant[[:space:]]*=[[:space:]]*)"classic"/\1"classic"/' zensical.toml

# Feature Toggles
sed -i -E 's/^[[:space:]]*#([[:space:]]*"content\.action\.edit",[[:space:]]*)/\1/' zensical.toml
sed -i -E 's/^[[:space:]]*#([[:space:]]*"content\.action\.view",[[:space:]]*)/\1/' zensical.toml
sed -i -E 's/^([[:space:]]*)"navigation\.footer",[[:space:]]*$/#\1"navigation.footer",/' zensical.toml
sed -i -E 's/^[[:space:]]*#[[:space:]]*("navigation\.instant\.progress",[[:space:]]*)/\1/' zensical.toml
sed -i -E 's/^([[:space:]]*)"navigation\.sections",[[:space:]]*$/#\1"navigation.sections",/' zensical.toml
sed -i -E 's/^[[:space:]]*#([[:space:]]*"navigation\.tabs",[[:space:]]*)/\1/' zensical.toml
sed -i -E 's/^[[:space:]]*#([[:space:]]*"navigation\.tabs\.sticky",[[:space:]]*)/\1/' zensical.toml

Launch Zensical Server

At this point, you can simply launch the server via the hotload-friendly serve mode. I have this configured to listen on 0.0.0.0 but you can set it to localhost or a LAN IP address like 192.168.3.8. You can adjust the port number if you want to.

zensical serve -a 0.0.0.0:80

mkdir -p /srv/zensical/server