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.
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.
To install, you can follow this guide for detailed instructions, but essentially: you use pip. (
pip install mkdocs-material)
theme: name: 'material' custom_dir: 'theme'
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: name: 'material' custom_dir: 'theme' language: en palette: primary: 'blue' accent: 'blue' font: text: 'Noto Sans' code: 'Fira Code' # needs some [extra setup](https://gitlab.com/retnikt/retnikt.gitlab.io/blob/master/theme/main.html#L4) to make this work logo: icon: 'developer_board' feature: false favicon: 'assets/images/favicon2.png'
First let's set some basic options:
site_name: retnikt site_url: 'https://retnikt.uk/' 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' extra: social: - type: 'github' link: 'https://github.com/retnikt' - type: 'twitter' link: 'https://twitter.com/retnikt' markdown_extensions: - 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
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
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
.gitlab.ci.yml file on this example. Note that you need to set the
site_dir value in
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 retnikt.uk (instructions) and finalised my configuration.