Online documentation website with Zensical¶

With these instructions you can create online documentation on a website. The documentation is written in Markdown which is converted to a website with Zensical. The website is copied to a webserver using the Continues Integration tool in Gitlab.

Zensical is an Open Source toolchain to build static sites with markdown source files.

• https://zensical.org

This document explains how to setup Zensical and how to use it with Continues Integration (CI/CD) in Gitlab. With CI/CD it is very easy to automatically generate or update the static website which is build with Zensical.

In these instructions we will be using the already configured gitlab-runner server gitlab-imphys.tudelft.nl and web server qiweb.tudelft.nl.

Why use Zensical?¶

Since the start of 2026 MkDocs is no longer maintained and version 2 is not support Material for MkDocs. In respons the developers of Material for MkDocs created Zensical as an all-inclusive alternative for MkDocs. While still in early development it is very powerful and for not too complex MkDocs configuration can be used as a in-place replacement.

For new projects I suggest starting off directly with Zensical using the instructions on the website and this document.

Setup Zensical project¶

Zensical is a Python package and can easily be installed with uv. For more information on how to install and use uv see this page.

uv init <projectname> --python 3.14 --bare --description "<projectname>" --author-from git --vcs git
cd <projectname>
uv add zensical
uv run zensical new .
uv run zensical serve

You now have working Zensical environment and you can see the website that is initially generated with zensical new. There is a lot of information on this initial website!

Git setup¶

With uv init also a git repository has been initialized. This allows you from the start to manage your Zensical project in the git repository with commands like git add and git commit.

This repository must now be connected to the TU Delft gitlab server gitlab.tudelft.nl.

First create a New Repository on gitlab.tudelft.nl

1. Log in to gitlab.tudelft.nl using your TU Delft credentials.
2. Click New project (green button in the top-right corner).
3. Select Create blank project.
4. Enter a Project name (e.g., \<projectname>) and make sure your project is located in the ImPhys group in gitlab. This can also be in one of the subgroups inside ImPhys.
5. Ensure the repository is set to Private if the content should not (yet) be public.
6. Turn off Initialize repository with a README. You want an empty project!
7. Click Create project.

On the following website you find instructions on how to connect your Zensical repository to this new project in Gitlab. In our case follow the instructions for Push an existing folder.

After initializing git and connecting with gitlab you can now use commands like git add, git commit git push and git pull.

For more information how to use git and gitlab, please check the internet or use your favorite LLM…

CI/CD setup¶

The Continues Integration tool of gitlab allows us to automatically start the creation of the website with Zensical and the copying of this website to the webserver. This is configured in the yaml-script .gitlab-ci.yml.

Because your gitlab project is located in the ImPhys group in gitlab, the right gitlab-runner will execute this script. You can check which runners are available:

1. Go to your gitlab.tudelft.nl project
2. On the left side select Settings → CI/CD
3. Select Runners

You have to write the .gilab-ci.yml file in the root of your repository with the following content:

stages:
  - build
  - deploy

variables:
  UV_VERSION: "0.11.0"
  PYTHON_VERSION: "3.14"
  BASE_LAYER: trixie-slim
  # GitLab CI creates a separate mountpoint for the build directory,
  # so we need to copy instead of using hard links.
  UV_LINK_MODE: copy
  DEPLOY_SERVER: qiweb.tudelft.nl
  DEPLOY_USER: web
  DEPLOY_PATH: /home/web/projectname


build:
  stage: build
  tags:
    - docker
  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
  variables:
    UV_CACHE_DIR: .uv-cache
  cache:
    - key:
        files:
          - uv.lock
      paths:
        - $UV_CACHE_DIR
  script:
    - uv sync --frozen
    - uv run zensical build --clean
  after_script:
    - uv cache prune --ci
  artifacts:
    paths:
      - site
    expire_in: 1 week

deploy:
  stage: deploy
  image: alpine:latest
  script:
    - apk add --no-cache openssh-client rsync
    - eval $(ssh-agent -s)
    - echo "$CI" | tr -d '\r' | ssh-add - > /dev/null
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - ssh-keyscan $DEPLOY_SERVER >> ~/.ssh/known_hosts
    - chmod 644 ~/.ssh/known_hosts
    - rsync -rv --delete site/ $DEPLOY_USER@$DEPLOY_SERVER:$DEPLOY_PATH
    - ssh-add -D
    - rm -rf ~/.ssh

Replace <projectname> with your project name!

After git add .gitlab-ci.yml, git commit -m "CI/CD" and git push, gitlab will automatically start this script on the gitlab-imphys.tudelft.nl.

Website setup¶

For the last step contact the maintainer of the webserver qiweb.tudelft.nl (Bernd Rieger) and request your project website to be added enabled on the webserver.

The maintainer will have to create a soft-link in /var/www/html/ to your website /home/web/<projectname>

You can now visit your project website here: https://qiweb.tudelft.nl/<projectname>