How to build this site⚓︎
Both are great tools that build a static site starting from simple markdown documentation.
They provide many amazing features, perfectly documented in 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.
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:
cairosvg with pip:
Install the other dependencies depending on your system:
There are several package managers for Linux with varying availability per distribution.
Make sure Homebrew is installed, which is a modern package manager for macOS. Next, use the following command to install all necessary dependencies.
If you are on Ubuntu you can directly launch the
setup.sh script located in
It contains all the previously described steps.
In order to build the site, the following command must be launched in the root directory:
It is not necessary to explicitly build the site before serving or publishing but it can be useful to inspect the
site folder it 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.
In order to locally test the site it is possible to launch the following command in the root directory:
The site will be hosted at the address configured in
mkdcos.yml and almost any change in the
docs folder will trigger an automatic republish.
If the site is published through GitHub Pages, as it is in our case, it can be easily deployed with a single command:
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⚓︎
Most of the configurations reside in the
mkdcos.yml file, located in the root folder.
repo properties configure website and repository locations and meta tags for the website.
nav section defines the structure of the site and the location of each markdown document published.
plugins sections contain all the Material for MkDocs configurations currently used and the extensions required to make them work.
consent sections configure the usage of Google Analytics and govern cookie consent.
copyright sections define the content of the footer, copyright and social icons.
The few CSS customizations we use can be found in
It contains the color palette we picked and a slight increase in the width of the pages.
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.
Created: November 17, 2022