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](https://zensical.org/docs/get-started/).  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.

```sh
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.

```sh
# 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
```

### Deploy NGINX Webserver
We need to deploy NGINX as a webserver, because when using reverse proxies like Traefik, it seems to not get along with Zensical at all.  Attempts to resolve this all failed, so putting the statically-built copies of site data that Zensical generates into NGINX's root directory is the second-best solution I came up with.  Traefik can be reasonably expected to behave when interacting with NGINX versus Zensical's built-in webserver.

```sh
sudo apt install -y nginx
sudo rm -f /etc/nginx/sites-enabled/default
sudo tee /etc/nginx/sites-available/zensical.conf > /dev/null <<'EOF'
server {
    listen 80;
    listen [::]:80;
    server_name _;

    root /srv/zensical/site;
    index index.html;

    # Primary document handling
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Static asset caching (safe for docs)
    location ~* \.(css|js|png|jpg|jpeg|gif|svg|ico|woff2?)$ {
        expires 7d;
        add_header Cache-Control "public, max-age=604800, immutable";
        try_files $uri =404;
    }

    # Prevent access to source or metadata
    location ~* \.(toml|md)$ {
        deny all;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/zensical.conf /etc/nginx/sites-enabled/zensical.conf
sudo nginx -t
sudo systemctl reload nginx
sudo systemctl enable nginx
```

### Configure Zensical to Hotload Changes
Since NGINX has taken over hosting the webpages, this does not need to be accessible from other servers, only NGINX itself which runs on the same host as Zensical.  We only want to use the `zensical serve` command to keep a watchdog on the documentation folder and automatically rebuild the static site content when changes are detected.  These changes are then served by NGINX's webserver.  *We don't care about the IP:port exposed by this built-in Zensical server.

```sh
zensical serve
```