How to build this site

This site is made with MkDocs and in particular with its extension Material for MkDocs.

Both are great tools that build a static site starting from simple markdown documentation.

They provide many amazing features, perfectly documented on their websites, with step-by-step tutorials to create a new site from scratch.

However, we would like to explain here all the prerequisites needed to build this very site and an overview of the principal customizations implemented.

Setup

The first thing to do in order to be able to build this site is to install Material for MkDocs, it will also install all dependencies: MkDocs, Markdown, Pygments and Python Markdown Extensions:

pip install mkdocs-material

In order to add the date of the last update and creation of a document at the bottom of each page, we enabled the git-revision-date-localized plugin, which can be installed with pip:

pip install mkdocs-git-revision-date-localized-plugin

Finally, two Python libraries must be installed to generate the social preview images, both of which are based on Cairo Graphics – Pillow and CairoSVG.

Install pillow and cairosvg with pip:

pip install pillow cairosvg

Install the other dependencies depending on your system:

Linux

There are several package managers for Linux with varying availability per distribution.

Ubuntu

apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev

If you are on Ubuntu you can directly launch the setup.sh script located in script folder! It contains all the previously described steps.

Fedora

yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel

openSUSE

zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel

Windows

The easiest way to get up and running with the Cairo Graphics library on Windows is by installing GTK+ since it has Cairo as a dependency. You can also download and install a precompiled GTK runtime.

macOS

Make sure Homebrew is installed, which is a modern package manager for macOS. Next, use the following command to install all necessary dependencies.

brew install cairo freetype libffi libjpeg libpng zlib

Building

In order to build the site, the following command must be launched in the root directory:

mkdocs build

It is not necessary to explicitly build the site before serving or publishing, but it can be useful to inspect the site folder that MkDocs creates to verify resource paths.

It is also useful for sites published without the aid of GitHub Pages since the site folder is the deployment unit.

Serving

In order to locally test the site, it is possible to launch the following command in the root directory:

mkdocs serve

The site will be hosted at the address configured in mkdocs.yml and almost any change in the docs folder will trigger an automatic republishing.

Publishing

If the site is published through GitHub Pages, as it is in our case, it can be easily deployed with a single command:

mkdocs gh-deploy --force

The site will soon appear at '<username>.github.io/<repository>'.

If you wish to publish the site using GitHub pages but on a custom domain, this guide contains all the available possibilities.

If you don't want to use GitHub pages, you can always build your site as explained before and upload the content of the site folder to your hosting provider.

Notable Configurations and Customizations

mkdocs.yml

Most of the configurations reside in the mkdcos.yml file, located in the root folder.

The site_* and repo properties configure website and repository locations and meta tags for the website.

The nav section defines the structure of the site and the location of each Markdown document published.

The theme, markdown_extensions and plugins sections contain all the Material for MkDocs configurations currently used and the extensions required to make them work.

The analytics and consent sections configure the usage of Google Analytics and govern cookie consent.

The social and copyright sections define the content of the footer, copyright and social icons.

extra.css

The few CSS customizations we use can be found in docs>stylesheets>extra.css.

It contains the color palette we picked and a slight increase in the width of the pages.

home.html

The homepage is written directly in HTML since we wanted it to be different from the rest of the site.

It can be found in docs>override and has its own customized style embedded.

How to deploy this site automatically

This repository makes use of 3 branches:

• main
• pre-deploy
• gh-pages

During the development process, you can write your site pages pushing them on the main branch or any other feature branch of your choice.

Then, in order to take advantage of the automatic deploy mechanism via github actions, these steps must be followed:

• push your code on the main branch
• merge your code into the pre-deploy branch
• push all the changes on the pre-deploy branch

The last action will trigger a pipeline execution that performs all the steps required to build and deploy the mkdocs documentation to the final website.