Skip to content

Using MkDocs

As you can tell, this site is no longer based on Publii CMS (which is still a very good CMS). After spending a few hours with MkDocs, I've been tempted to use that instead, as I can do pretty much everything using Vim. I'm still migrating the content, so this site is a work in progress.

Using a static site generator might initially seem like a long-assed way of getting a basic site up, but once MkDocs is installed and running, and the site's customised, we only need to worry about a single configuration file and where to place the content. Markdown is less cumbersome than HTML, and since MkDocs renders content in partial views, it eliminates most the code duplication for the layout. I also really like having the option to use Vim, and also to import a post straight from Obsidian to MkDocs on occasion.

What I've done is followed parts of the official MkDocs guide and made a few experimental changes.

Getting Started

Assuming PIP is installed, the first step is to install MkDocs and a default material theme with the following:

pip install mkdocs-material

Setting up a working site is just a matter of creating a directory and running the following command to set up the template and configuration file inside it:

mkdocs new .

This generates a collection of files. One of these, mkdocs.yml, is the main configuration, in which all Markdown/HTML files we add are declared, the theme is specified and the extensions listed.

At this point, it's worth setting the site's theme by adding the following to mkdocs.yml:

theme:
  name: material

That's everything needed to get the template site working. To view it:

mkdocs serve

The site is accessible at localhost:8000. Usually the server will automatically reload it when a change is made, but sometimes it's necessary to Ctrl+C and run mkdocs serve again. The command line will point out any typos in the configuration file.

Customisation

I decided to modify the theme a little before adding content. This is enabled by overriding it with a CSS file. In the /docs directory, I created a subdirectory called 'style', and within that a style.css file.

This needs to be declared in the configuration by adding the following lines to mkdocs.yml:

extra_css:
  - stylesheets/extra.css

After that, it's a matter of using the browser's developer tools to find the elements to customised.

Overriding Layout Files

There are some basic things, such as the site's title, header, footer and layout, that we might want to change. For that, we need to create a directory in the root called 'overrides'. Anything here will either override the template files or add additional things to the layout.

In order to change the site's title, a main.html file with the following is needed:

{% extends "base.html" %}

{% block htmltitle %}
  <title>Michael's MkDocs</title>
{% endblock %}

This is as simple as adding entries to the nav section of the configuration, e.g.

nav:
    - Home: index.md
    - About: about.md

And elsewhere in the file, extend the theme section so it looks like:

theme:
  name: material
  custom_dir: overrides
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.indexes

What about content, such as blog entries, that we don't want listed in the main navigation menu? To do that, I created a /blog subdirectory in /docs, and added a simple Markdown file in it.

Then in the nav section file, I added:

    - Blog:
      - Hello World: blog/HelloWorld.md

Extensions

There are a number of Python extensions available to extend the Markdown. I'm using:

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - meta
  - attr_list

Build and Deploy

Add the following to the config file, under the site_name:

site_url: ""
use_directory_urls: false

This enables the site to be previewed in the file system, without having to use a test server. I did test my site on a local instance of nginx, just to be sure.

When ready, run the mkdocs build command to generate a /site directory that's populated with the content to be deployed to wherever you want the site hosted.