Your MkDocs Site Can Look 10x Better with Material Theme

When I first stumbled upon Material for MkDocs, I was blown away by how polished it looked compared to plain MkDocs. You get a modern UI, great typography, built-in search, and a ton of customization options  and you can still keep everything in Markdown.

The first time I used it, though, I fell into the “Oh, I’ll just install it and be done” trap. Spoiler: Material for MkDocs can do a LOT more than just make your docs look nice. So in this post, I’ll walk you through not just installing it, but also adding some of my favorite features like syntax highlighting with line numbers, content tabs, callout boxes, diagrams, and a nice footer with social links. We’ll even push it to GitHub Pages at the end.

What is Material for MkDocs?

In simple terms, Material for MkDocs is a theme for MkDocs, which is a static site generator specifically designed for project documentation. Think of MkDocs as a tool that converts markdown files into a neat website and the Material theme makes that website look great, inspired by Google’s Material Design principles.

Why should you care? Because it gives your docs:

• Responsive design (works great on phones, tablets, and desktops)
• Built-in search
• Support for tabs, admonitions, and code highlighting
• Easy customization without diving deep into CSS
• A whole ecosystem of extensions to make your docs interactive and useful

So if you want to take your markdown files and turn them into a sleek website without much fuss, Material for MkDocs is the way to go.

Getting Started: Installing Material Theme

First things first, you need MkDocs and the Material theme installed. If you haven’t installed MkDocs yet, you can do it with pip:

Then install the Material theme:

Now create a new MkDocs project (or use an existing one):

Open your mkdocs.yml and set the theme to Material:

If you run the dev server with

You can open http://localhost:8000 in your browser and see your docs with the Material theme in action.

Fancy Code Blocks with Line Numbers and Highlighting

One of my favorite things about Material is how it handles code blocks. You can add line numbers and highlight specific lines, making examples super clear.

Here’s an example of a Python function with line numbers starting from 5 and highlighting lines 2 to 4:

Then in your markdown, you can add tabs like this:

This renders as clickable tabs in your docs, letting readers switch between different views or content types without scrolling endlessly.

Here’s an example with code tabs for Python and JavaScript:

Tabs are a neat way to organize content and keep your docs tidy.

Highlight Important Info with Admonitions (Callouts)

Ever want to draw attention to a note, warning, or tip? Material supports admonitions (also called callouts) for that.

Enable them in mkdocs.yml:

Then use them in markdown like this:

You can also make collapsible admonitions, perfect for FAQs or extra info that readers can expand only if they want:

These callouts make docs more engaging and easier to scan.

Drawing Diagrams with Mermaid

Sometimes words alone aren’t enough. Material lets you embed diagrams with Mermaid, which supports flowcharts, sequence diagrams, class diagrams, and more.

Enable Mermaid in mkdocs.yml:

Example flowchart markdown:

And here’s a sequence diagram example:

Setting up the footer

The footer of your project documentation provides an excellent spot to include links to websites or platforms your company uses as extra marketing channels. You can easily set these up through your mkdocs.yml configuration.

Add this to your mkdocs.yml:

icon  This property must contain a valid path to any icon bundled with the theme, or the build will not succeed. Some popular choices:

link  This property must be set to a relative or absolute URL including the URI scheme. All URI schemes are supported, including mailto and bitcoin:

namedomain name from link, if available This property is used as the link's title attribute and can be set to a discernable name to improve accessibility:

Publishing Your Docs on GitHub Pages

Last but not least, how do you get your docs live on the web? GitHub Pages is a popular choice, and Material makes it easy with GitHub Actions.

Create a file at .github/workflows/ci.yml with this content:

Push your changes to GitHub, and GitHub Actions will build and deploy your docs to GitHub Pages automatically.

While having a nice documentation site is one thing, it’s really important to keep your docs updated as your code changes. From personal experience, I know it’s hard to keep docs updated it’s boring and repetitive but it can’t be avoided.

That’s where a tool like DeepDocs helps. It’s a GitHub-native AI agent that helps engineering teams automate the boring task of keeping docs like READMEs, API references, SDK guides, and tutorials up-to-date with your changing code. And the best part is, it’s completely free to try.

Wrapping Up

Material for MkDocs offers a practical and flexible way to turn markdown files into clean, organized documentation sites. With built-in support for features like line numbers, highlighted code blocks, content tabs, and callouts, it helps you present information clearly and makes navigation easier for readers. The ability to include diagrams adds valuable visual context, which is often missing in plain text documentation. Plus, the straightforward integration with GitHub Pages means you can publish and update your docs without hassle.

While it might take some initial setup and getting used to the configuration options, once in place, Material for MkDocs can streamline your documentation workflow and improve the overall user experience. It strikes a good balance between customization and simplicity, making it a solid choice for projects of all sizes.