Build a Manual with MkDocs #3: Writing Content — Code Blocks, Mermaid, and Admonitions

Framework MkDocs Documentation Static Site
3 min read

In #2 we laid out the skeleton of the docs with nav and search. Now it’s time to fill it in. Technical docs need more than plain prose. Commands belong in code blocks, flows in diagrams, and cautions in boxes that stand out, so readers can scan quickly.

This series, Build a Manual with MkDocs, runs in six parts.

  • #1: From Install to Your First Doc
  • #2: nav and Search — Shaping the Information Structure of Your Docs
  • #3: Writing Content — Code Blocks, Mermaid, and Admonitions ← this post
  • #4: Deploy on Cloudflare Pages and Connect a Domain
  • #5: Multilingual Docs and Versioning
  • #6: Maintenance — Search, Accessibility, and Documentation Culture

In this post we’ll cover three things: styling code blocks properly, drawing diagrams with Mermaid, and highlighting with admonitions. Most of these features are turned on through Markdown extensions, so we’ll configure those first.

Turning On Markdown Extensions #

Material’s rich expressiveness comes from the pymdownx extensions. Register the extensions you need in mkdocs.yml.

mkdocs.yml — Markdown extensions 
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

theme:
  name: material
  features:
    - content.code.copy   # Copy button on code blocks

Code Blocks — Titles and Line Highlighting #

Add options after the language in the code fence to add a title and highlighting.

Adding a title to a code block 
```python title="app.py" hl_lines="2" linenums="1"
def add(a, b):
    return a + b  # this line gets highlighted
```

title adds a filename banner, hl_lines specifies the lines to highlight, and linenums adds line numbers. The copy button is automatically attached to every code block by the content.code.copy feature we turned on above.

Diagrams — Mermaid #

Mermaid writes diagrams as code. Because it’s text, it’s version-controlled with Git and easy to edit. In MkDocs, you just register Mermaid with superfences.

mkdocs.yml — enabling Mermaid 
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Now opening a mermaid fence renders it as an actual diagram.

Mermaid flowchart 
```mermaid
flowchart LR
  A[Write] --> B[Build] --> C[Deploy]
```

Admonitions — Highlighting Cautions and Warnings #

Content that says “you really must read this” shouldn’t get buried in prose. Admonitions create highlight boxes. Write the type after !!!, then add the content with indentation.

Writing an admonition 
!!! warning "Caution"
    Always take a backup before applying this to production.

Types include note, tip, warning, danger, and more, each with its own color and icon, so information, caution, and danger are visually distinguished. Writing ??? instead makes a collapsible box.

Splitting into Tabs #

For content that branches, like per-OS commands, tabs are handy. Make them with the pymdownx.tabbed we turned on above.

Splitting into tabs 
=== "macOS"
    brew install our-product

=== "Windows"
    winget install our-product

Wrapping Up #

In this post we covered code blocks with titles and line highlighting, Mermaid diagrams managed as code, and admonitions and tabs that highlight cautions and warnings. By this point, you have docs that look good locally.

In the next post we’ll send these docs out into the world. We’ll go over deploying on Cloudflare Pages and connecting a custom domain so anyone can reach them.

X