Documentation

Building it

The documentation is created by using mdBook, which generates Markdown files and generates HTML pages for them. The documentation can be build by running:

nix build .#docs # plain simple

The files can then be found at ./result/, which is a symlink to the corresponding path in /nix/store. mdBook is also able automatically serve the current content and update it automatically whenever a change is detected. This makes testing and previewing content easy.

mdbook serve --open # the latter additionally opens the website in a browser

Useful information

mdBook syntax

While the general syntax for writing Markdown applies to mdBook, it has several extensions beyond the standard CommonMark specification.

• Markdown syntax
• mdBook specific features

Especially importing code blocks as Markdown is really handy to keep content always up-to-date and helps providing a full text searchable code documentation.

Updating mdBook plugins contents

Some of the mdBook parts are plugins that need their content to be updated from time to time. Namely, thats:

• mdbook-admonish: run mdbook-admonish inside the docs folder
• mdbook-emojicodes: works without CSS, so no updates needed
• mdbook-catppuccin: run mdbook-catppuccin inside the docs folder (might need to grab binary from its website, no Nix package available yet)

Deployment

Deployment to Cloudflare pages automated and happens whenever a commit to main occurs. A GitHub actions workflow builds and pushes it to the cf-pages branch, which will then be used by the Cloudflare pages app to deploy the new version from.

---
name: Cloudflare pages
on:
  push:
    branches: [main]
    paths: [docs/**, README.md]
permissions:
  contents: write
jobs:
  build-and-deploy:
    concurrency: ci-${{ github.ref }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v4
      - name: Setup mdBook 📜
        uses: peaceiris/actions-mdbook@v2
        with:
          mdbook-version: latest
      - name: Install further deps 📦
        run: |
          sudo apt-get install -y --no-install-recommends cargo
          cargo install mdbook-admonish
          cargo install mdbook-emojicodes
          PATH=$HOME/.cargo/bin:$PATH
      - name: Install and Build 🔧
        run: cd docs && mdbook build
      - name: Deploy 🚀
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: cf-pages
          publish_dir: docs/book

Issues and their solution

Sidebar or something else on the documentation doesn't work as expected

Chances are that the custom CSS parts need to be rebased to a newer version. They can be found in ./docs/theme/css and the only addition we made here is to use the Fira Sans font instead of the default one. To rebase against a newer version comment out dditional-css in ./docs/book.toml and move the css folder somewhere else temporarily. After that, run mdbook build inside the docs folder. The new CSS files can now be found inside the ./docs/book/css folder. Copy those to the ./docs/theme/css folder and alter the occurrences of font settings to include Fira Sans (or run a diff to find out where). After uncommenting additional-css in book.toml, run mdbook build again to verify nothing got broken along the way.