Skip to content

My Website

Across my lifetime, I have tried numerous mechanisms for my website with a basic blog system, including WordPress, Pelican, Jekyll, and even a home-grown solution on Google App Engine. I have now settled on MkDocs, which is definitely not intended for blogging, but I find it well-suited for the task.

Getting Started

I installed mkdocs with pip install mkdocs and created a new project using mkdocs new .. I also initialised a Git repository on GitLab to version all the configuration and content.


Now it's time for some configuration.


The first thing to do is pick a theme. I chose the popular and brilliant mkdocs-material. mkdocs-material To install, you can follow this guide for detailed instructions, but essentially: you use pip. (pip install mkdocs-material)

  name: 'material'
  custom_dir: 'theme'

The custom_dir line is so that we can override parts of the HTML.

We can make some tweaks to the rest of the appearance too, including colours, fonts, and many other options. Here's my final theme section:

  name: 'material'
  custom_dir: 'theme'
  language: en
    primary: 'blue'
    accent: 'blue'
    text: 'Noto Sans'
    code: 'Fira Code'  # needs some [extra setup]( to make this work
    icon: 'developer_board'
  feature: false
  favicon: 'assets/images/favicon2.png'

Extra Options

First let's set some basic options:

site_name: retnikt
site_url: ''
site_dir: 'public'  # this is needed for GitLab pages

I'm going to add a copyright to the footer and some social media links, and enable a few (lots of) Markdown extensions:

copyright:  retnikt 2019'
    - type: 'github'
      link: ''
    - type: 'twitter'
      link: ''
  - admonition
  - codehilite
  - footnotes
  - meta
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - markdown.extensions.attr_list
  - markdown.extensions.def_list
  - markdown.extensions.tables
  - markdown.extensions.abbr
  - pymdownx.extrarawhtml
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  - pymdownx.inlinehilite
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.progressbar
  - pymdownx.keys
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde
  - toc:
      permalink: true

Theme Overrides

I want to customise some of the theme components, particularly the footer. here is a list of all my tweaks, the sources for which you can find on GitLab:

  • Reference GitLab Pages in the footer (see Deploying below) (code)
  • Hide Next/Previous page arrows on the homepage (code)
  • Change the font stylesheet links to enable Fira Code (code)
  • Change the top of the navigation on the left to say "Navigation" instead of the page title (code)
  • Change "Table of contents" to just "Contents" (code)
  • Change the 404 page content (code)


To build the site locally, run mkdocs build. You can also use the live preview web server built in to mkdocs with mkdocs serve.


I am deploying my site on GitLab Pages, taking advantage of its continuous integration for building the site, similar to how GitHub can automatically deploy Jekyll sites. I based my file on this example. Note that you need to set the site_dir value in mkdocs.yml to public so that GitLab Pages can deploy, because it looks for the HTML in the CI public artifact folder. I set up my custom domain (instructions) and finalised my configuration.