Posts

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 Ordered List Styles 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

Terminology Checks in Docs-as-Code Editors

If you’re writing documentation using a docs-as-code approach, chances are you’re using editors like Visual Studio Code or Notepad++. I use both regularly. One feature I often miss in these tools is built-in terminology checking. In this post, I’ll show you how to set up a script that runs in the background and checks your text against a simple termbase in real time. About this Use Case While Visual Studio Code offers some options to check your content against certain rules using the Markdownlint plugin, I couldn’t find many options for Notepad++ aside from a simple spell check.

Saturday, November 9, 2024 | 6 minutes Read

Index Websites with Google Search Console

In this post I’d like to show you how to use the Google Search Console to index your website. The Google Search Console offers tools and reports to help you measure your site’s search traffic and performance, fix issues, and improve Google Search results. For a website to show up in a search engines (e.g. Google, Bing, etc.), the website needs to be indexed by the search engine. This can take between a few days, weeks to even months if indexing is not explicitly requested using the Google Search Console.

Saturday, August 10, 2024 | 3 minutes Read

UX Writing Checklist

UX Writing refers to text in user interfaces that explains what features do, and tells a user what action will occur by interacting with that element. Lately I’ve been very interested in UX Writing (probably because the UI texts in the products I usually document tend to be… improvable). So a few weeks ago I attended a workshop where I learned some basics and where the attendees were encouraged to create their own checklist for UX Writing as a takeaway.

Friday, July 5, 2024 | 4 minutes Read

Integrate a Microsoft Copilot Chatbot with MkDocs

In this post I’d like to show you how to integrate a custom Microsoft Copilot Studio Chatbot with MkDocs. The goal is to provide a chatbot on all pages of the documentation, that is trained with the content of the documentation, see screenshot. About this Approach You can connect to a copilot with a custom canvas that is hosted as a standalone web app in your MkDocs project. This option is best if you need to embed a customized iFrame across multiple web pages / documentation pages.

Wednesday, June 5, 2024 | 5 minutes Read

Auto-Generate Markdown Content Using Power Automate

In this post I’d like to show you how to use Microsoft Power Automate to generate markdown content for your MkDocs project. Power Automate is a cloud-based process automation service that can be used to create automated workflows to synchronize and collect data, get notifications, start approvals, and more. About this Use Case There are multiple reasons to automate content creation. In our case, we wanted to make it easier for non-developers to publish news in the “Latest News” section of our HelpCenter, see screenshot below.

Tuesday, May 7, 2024 | 5 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

Introduction

Hi and welcome to my blog, where I post random stuff that I deal with during my work as a technical writer in a software company. My Role As mentioned above, I work as a technical writer at a software company. When I started this job in 2021, I was a career changer (former application engineer). While I had some experience writing software documentation, I wasn’t trained in the field of writing / documenting.

Basic

Friday, April 19, 2024 | 1 minute Read