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.