Skip to content

#59: Source Code in MkDocs

A good illustration of source code is a must-have when you want to use MkDocs for your project documentation. Let us find out what we need to display code snippets.

Your usual way to format code does not work

You may be used to put your code between ` `. This works with some Markdown flavours, but in MkDocs that is converted in something rather unusable:

1
2
3
4
5
6
7
8
9
`def fizz_buzz(value):
    if(value % 3 == 0 and value % 5 == 0):
        return "FizzBuzz"
    elif (value % 3 == 0):
        return "Fizz"
    elif(value % 5 == 0):
        return "Buzz"
    else:
        return value`

The whole code is smashed together

If you want multiple lines of code, you need to put it between ```    ``` (3x ` instead of 1 per group):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 ```
def fizz_buzz(value):
    if(value % 3 == 0 and value % 5 == 0):
        return "FizzBuzz"
    elif (value % 3 == 0):
        return "Fizz"
    elif(value % 5 == 0):
        return "Buzz"
    else:
        return value
 ```

The code is now indented

This is better, but we can improve it a lot more.

Add markdown extensions to the Material theme

If this basic display for code is not enough, you need to add some additional markdown extensions to your mkdocs.yaml. They are bundled in the Material theme and should already be on your computer if you followed along the last post. Be aware of the 4 spaces to indent linenums_style instead of the usual two – it will not work without them:

1
2
3
4
5
6
7
8
site_name: My Docs
theme: 
  name: material
  logo: logo.svg
markdown_extensions:
  - pymdownx.highlight:
      linenums_style: pymdownx.inline
  - pymdownx.superfences

This configuration and the following examples work with the Material theme. Other themes have their own way to display code and you may need to install different extensions.

Syntax highlighting

To turn on syntax highlighting we need to specify which programming language we use. There is a long list of supported languages and for Python alone you get multiple options. For my examples I use python3:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 ``` python3
def fizz_buzz(value):
    if(value % 3 == 0 and value % 5 == 0):
        return "FizzBuzz"
    elif (value % 3 == 0):
        return "Fizz"
    elif(value % 5 == 0):
        return "Buzz"
    else:
        return value
 ```

Our code now uses syntax highlighting

Highlight lines of code

We can highlight lines of code by passing the line numbers to the hl_lines argument (the first line has the number 1):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 ``` python3 hl_lines="2 4 6"
def fizz_buzz(value):
    if(value % 3 == 0 and value % 5 == 0):
        return "FizzBuzz"
    elif (value % 3 == 0):
        return "Fizz"
    elif(value % 5 == 0):
        return "Buzz"
    else:
        return value
 ```

We now see a few lines marked in yellow

Show line numbers

We can show line numbers with the linenums argument, that we need to activate:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 ``` python3 linenums="1"
def fizz_buzz(value):
    if(value % 3 == 0 and value % 5 == 0):
        return "FizzBuzz"
    elif (value % 3 == 0):
        return "Fizz"
    elif(value % 5 == 0):
        return "Buzz"
    else:
        return value
 ```

We now can see the line numbers of our code sample

Put all together

We can use all those source code related features at once:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 ``` python3 linenums="1" hl_lines="2 4 6"
def fizz_buzz(value):
    if(value % 3 == 0 and value % 5 == 0):
        return "FizzBuzz"
    elif (value % 3 == 0):
        return "Fizz"
    elif(value % 5 == 0):
        return "Buzz"
    else:
        return value
 ```

Line numbers with syntax highlighting and marked lines

Conclusion

MkDocs is a great help for me. I can focus on writing the documentation and MkDocs takes care of the rest. I can highly recommend MkDocs because it hits the balance of flexibility and ease of use just right.