Useful MkDocs Plugins I Discovered This Week

My blog is built using MkDocs, which I also use daily in my role as a technical writer. I chose it for a few reasons for both my blog and the docs projects I manage: being familiar with Python made it easy to get up and running, and it's a natural fit for projects where contributors and users are Python developers. One of the other things I love about MkDocs is how easily it can be extended with plugins written in Python. This week I discovered a couple of plugins and plugin features which helped me solve some specific problems I encountered.

Redirects

Having a friendly URL that accurately describes the page is important for discoverability of a page. I've worked on products where feature names or functionality change and it's necessary to have a new URL that accurately reflects the new page content. MkDocs Redirects solved this problem for me this week. Super easy implementation. Also great as its config in the mkdocs.yml file in the docs project makes it easy to see at a glance what's changed over time and what old links are still being maintained.

Snippets

Content going stale is one of the biggest challenges as a technical writer. When writing, I don't like to repeat content across different pages, as it becomes a maintenance burden. If one instance is missed during an update there's a good chance it will confuse users or diminish trust in the docs. But there are often times when I'll want the same content across multiple pages, whether that be for some marketing effort or to introduce a concept that's important for all pages of the same type. This was a problem I encountered this week, and Snippets solved it for me perfectly. Another great example of how easy it is to extend a MkDocs site.

Code Block Line Highlighting

My blog here and some docs sites I work on use Material for MkDocs. So many things I love about it and I'm always discovering new features. Recently, I've been thinking a lot when writing tutorials about how I can give users a full runnable example for code (or a full prompt example for AI-based tools), but at the same time highlight the important code changes from section to section. I think the full code example is important as many users want to run it, iterate over it, and run it again, and that's how they learn. This week, I discovered the ability to highlight specific lines in code and have been using it to highlight the code that applies to the specific topic I'm guiding the user through. Super simple but super impactful.