Nicole Rappe
776eb2a973
All checks were successful
GitOps Automatic Deployment / GitOps Automatic Deployment (push) Successful in 7s
53 lines
2.9 KiB
Markdown
53 lines
2.9 KiB
Markdown
## 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
|
|
```
|
|
|
|
### 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.
|
|
|
|
```sh
|
|
zensical serve -a 0.0.0.0:80
|
|
```
|
|
|
|
mkdir -p /srv/zensical/server |