Discovering MkDocs

I just discovered the MkDocs project. It allows you to transform Markdown files into static websites. You can also customize it with themes and plugins.

I wanted to create a POC (Proof of Concept) and eventually decided it was an opportunity to build a site to share my different procedures and my experiences with POCs that I do on a daily basis.

Here is my first article on how to create this site with MkDocs.

Installing MkDocs

I always recommend creating a Python venv.

This procedure was performed on a Linux OS (Pop!_OS 22.04).

Install the python mkdocs package

pip3 install mkdocs

It seems that in our case, there is a PATH issue

[Optional] Debugging PATH Issue

This can be fixed by adding the following to the PATH:

export PATH="$HOME/.local/bin:$PATH"

Creating the blog project and starting it on localhost

Configure MkDocs and start a server that serves the site locally. This is convenient for testing as it updates automatically.

mkdocs new blog
cd blog/
mkdocs serve

I place a Markdown file in the docs/ folder.

There you go, your Markdown file is rendered, but one step remains.

You can also create HTML files with this command :

mkdocs build

Testing the HTML files opened directly in Firefox

Installing a template

I will install the "material" template with this command

pip3 install mkdocs-material

I have tested other templates like Cinder Theme for MkDocs which are also very nice.

Activating the template

The site customization is done via the mkdocs.yml file, which we will edit:

vim mkdocs.yml

I will rename the site, activate the template, and configure my menus with this code:

site_name: Be Cloud, code it !
theme: 
  name: material
  logo: logo_b_cloud_code_it_transp.png
  favicon: favicon.ico

nav:
  - Accueil: index.md
  - Articles: article/articles.md
  - Procédure: procedure/procedure.md
  - A Propos: a-propos.md

I also take the opportunity to add a logo and a favicon.

And the structure for the other pages of the site.

Adding comments

How to add Mastodon comments to MkDocs

Adding image zoom

Install this plugin

pip install mkdocs-glightbox

In the mkdocs.yml file, add

plugins:
- glightbox

To Be continue

I rebuild and deliver this version of the site with this command

mkdocs build

A quick FileZilla transfer and it's delivered.

Comment

Commentez cet article de blog en utilisant un compte compatible Fediverse (Mastodon ou similaire).