Skip to content

Setting up a blog with MkDocs and Material for MkDocs

I wanted a way to create blog posts on various subjects (Python, Kubernetes, AWS), and considered a few options. The reason I landed on MkDocs together with Material for MkDocs was the support for embedding files in blog posts in what I thought was a sensible way (allowing to embed files from a Git repo). I had seen it used in several places for documentation (e.g. FastAPI and Pydantic). Looking at some other alternatives, I didn't see a way of embedding code snippets or files which I found to be any better than what MkDocs/MkDocs . Maybe a bit more research would have lead me there, but I wanted to start blogging.

Initial setup

The Material for MkDocs getting started guide is a good starting point. Following it, I got this:

Blog - initial look

Nice! So I did the static site generation using mkdocs build and ended up with a site/ folder:

site
├── 404.html
├── assets
│   ├── images
│   │   └── favicon.png
│   ├── javascripts
│   │   ├── bundle.d7c377c4.min.js
│   │   ├── bundle.d7c377c4.min.js.map
│   │   ├── lunr
│   │   │   ├── min
│   │   │   │   ├── lunr.ar.min.js
│   │   │   │   ├── lunr.da.min.js
│   │   │   │   ├── lunr.de.min.js
│   │   │   │   ├── ...
│   │   │   ├── tinyseg.js
│   │   │   └── wordcut.js
│   │   └── workers
│   │       ├── search.f886a092.min.js
│   │       └── search.f886a092.min.js.map
│   └── stylesheets
│       ├── main.50c56a3b.min.css
│       ├── main.50c56a3b.min.css.map
│       ├── palette.06af60db.min.css
│       └── palette.06af60db.min.css.map
├── index.html
├── search
│   └── search_index.json
├── sitemap.xml
└── sitemap.xml.gz

Getting the base site published

I decided to go with Cloudflare Pages because I wanted some experience with their platform, and they have a very generous free tier. GitHub Pages seems to be the most common way, but I didn't believe Cloudflare to be much more complex. MkDocs for Material's first suggestions is to use GitHub Pages or GitLab Pages and further references an article suggesting to use Cloudflare's build feature for deployment.

Cloudflare themself provides a few options - e.g. the Wrangler CLI OR C3, and they have their own guide on using MkDocs to create the site (this resembles the aforementioned article).

I already had a Cloudflare account registered (free tier), so I used that. Then I found their to "Workers & Pages" section and I could here upload a directory – which I did – and the page was online (after a few minutes for the new DNS entry to propagate).

After looking some more I found that Wrangler could be used to do this from the CLI - it seemed like something that would match my workflow better than the git/GitHub integration Cloudflare offers – as I could deploy straight from my machine. In a team setting this wouldn't be my approach, but here I'm all by myself, so I get to live a little dangerous. Anyways, Cloudflare Pages does support a preview environment version of your page, so that seems to make experimenting even safer.

Making it my blog

Up to now the content of the home page was the placeholder created by MkDocs, and I used a Cloudflare domain name. I had a goal to 1) change the content of the index page and 2) use my own domain (krsb.net).

Changing the content was a matter of updating the

My domain is managed through Gandi. I didn't find a way to tell Cloudflare Pages to use krsb.net as the domain.

According to reddit user throwaway234f32423df:

You can't host an apex domain on Cloudflare Pages if you're not using Cloudflare DNS. You can host on a subdomain such as www, though, and use various methods to redirect the apex domain to the subdomain.

So I went with blog.krsb.net for now, and have Gandi do a redirect from krsb.net to blog.krsb.net (it's not a DNS feature, so was glad to find this possibility being offered).

After customizing

The mkdocs.yaml:

site_name: Homepage of Kristoffer Bakkejord
site_url: https://blog.krsb.net/
theme:
  name: material
extra:
  social:
    - icon: fontawesome/brands/mastodon
      link: https://fosstodon.org/@kbakk
  generator: false
copyright: Copyright © 2024 Kristoffer Bakkejord
plugins:
  - blog:
      blog_dir: .
markdown_extensions:
  - attr_list
  - md_in_html
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

What's next

I'd like to make it look at bit less like a documentation site, so maybe I'll dive into styling it – but then again, I'm no designer, so maybe as it is now is sufficient. I'll try to generate more content. The primary aim was to have somewhere I could publish these posts – MkDocs and Material for MkDocs made that easy, together with Cloudflare for hosting.