MkDocs

Virtual Environments for Docs Projects

After 4 years of maintaining a single MkDocs documentation project, it finally happened: I was tasked with setting up a second project. And this means handling different project dependencies. Working with documentation in a docs-as-code environment usually involves Static Site Generators such as MkDocs or Sphinx. These tools transform plain text files into documentation websites. But they usually also come with dependencies - and that’s where virtual environments come in. Virtual environments are self-contained workspaces for Python projects.

Saturday, September 27, 2025 | 3 minutes Read

List Recently Updated Pages in MkDocs

When maintaining documentation with MkDocs, it can be helpful to give readers a quick overview of what’s been updated recently. There are a few ways to convey this kind of information, like: Adding revision dates to the bottom of individual pages using the mkdocs-git-revision-date-localized-plugin Displaying a page status (e.g. “draft”, “new”, “updated”) next to the page title in the navigation via the status feature of the Material theme Adding a table containing git commit information using the mkdocs-git-latest-changes-plugin.

MkDocs

Saturday, July 26, 2025 | 4 minutes Read

How to Use Structured Data in MkDocs

Have you ever wondered how some documentation pages show up in search results with features like expandable FAQs, breadcrumb trails, or instructional step-by-steps? That’s the power of structured data. Structured data refers to a standardized format for providing information about a web page and classifying its content. It helps search engines understand the content of the page more accurately and display it in enhanced ways directly in search results. The Material theme for MkDocs already offers a solid foundation for SEO, but there are still ways to fine-tune and improve how individual pages are indexed and presented.

Friday, May 16, 2025 | 3 minutes Read

Custom List Style for Linear Workflows

So, today I want to talk a little bit about ordered lists in MkDocs and the Material theme. Recently, I felt the need to include some linear workflows in a few Knowledge Base articles. Most of these Knowledge Base articles contain How-To’s that involve tasks with a lot of steps or tasks that need to be performed in a 3rd-party software. For situations like this I like to group the steps into more digestible subtasks and list them as a “general workflow” before getting into the details.

Sunday, March 30, 2025 | 3 minutes Read

How to Structure an MkDocs Repository to host multiple Docs

In this post, I’ll walk you through how I set up multiple product documentations within a single GitHub repository. Here’s what I’ll cover: Creating a single repository to host multiple product documentations Setting up a shared assets folder (for images, files, and text snippets) Optional: Using variables to switch assets based on the selected product Optional: Creating a central batch file to serve one or more product documentations at once Keep in mind that this is just one approach to managing multiple projects in a single repository—other methods may suit different needs.

Thursday, December 12, 2024 | 8 minutes Read

Migrating from Jekyll to MkDocs

Our company (or rather I as the technical writer responsible for our documentation) recently decided to say goodbye to our current solution for creating documentation: Jekyll. Instead, we are now working on migrating our existing content to MkDocs. In this post I want to tell you a little bit about the reasons behind this decision. Status Quo Currently, we still use Jekyll 3 to build our documentation. Jekyll is a static site generator that uses static Markdown files and converts them to a website.

Saturday, April 20, 2024 | 4 minutes Read