How I Publish These Notes

The main component that is responsible for publishing these notes is a project by the creators of the Rust language called mdBook. This basically converts Markdown files into HTML which can be published via the hosting provider of your choice.

Since I'm using GitLab for nearly all of my projects including this one, it was an easy choice for me to use GitLab Pages for hosting this site.

The sources of this site are publicly available. Just head over to the repository.

mdBook

The structure is mainly given by mdBook with two exceptions. By default mdBook will write the HTML output to a directory called book. I could have left it this way, but I decided to rename this directory to build, so I had to change this in the configuration file.

For GitLab Pages it is necessary that the HTML files can be found in the public directory and I used this directory as build directory before, but when I started to use mdbook-linkcheck to make sure that all the links are working, I realized that this creates one directory per renderer, which broke the deployment mechanism.

The second thing I do apart from the mdBook structure is that I store drafts for notes in the drafts directory, which is ignored by Git via the .gitignore file. After I finished working on a draft I copy it to the src directory and add it to the SUMMARY.md file.

So in the end the structure of this project looks like this on my machine:

> tree
.
├── README.md
├── book.toml
├── build
│   ├── html
│   │   └── (generated HTML, CSS, JS ...)
│   └── linkcheck
│       └── cache.json
├── drafts
│   ├── how-i-manage-my-git-config.md
│   └── how-i-organize-my-software-projects.md
└── src
    ├── README.md
    ├── SUMMARY.md
    ├── how-i-manage-my-pgp-key
    │   ├── 01-install-gnupg.md
    │   ├── 02-the-secure-environment.md
    │   ├── 03-generate-keys.md
    │   ├── 04-import-keys.md
    │   ├── 05-transfer-to-nitrokey.md
    │   └── index.md
    └── how-i-publish-these-notes.md

Docker Image

I've created a Docker image containing mdBook and mdbook-linkcheck to be able to build and deploy the site.

This is used as image in the GitLab CI configuration.

GitLab

Finally publishing the site is done by GitLab Pages, which relies on the CI (continuous integration) feature provided by GitLab. I just followed the documentation to make it work.

One thing I do differently is that I usually follow the GitLab Flow. So the pipeline for deploying the site only runs on the production branch. You can see that in the GitLab CI configuration file in the repository.

As GitLab Pages requires the HTML content in the public directory, I simply create the directory and copy all files into it in the deployment job.