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.
This post is part of my journey to learn Python. You can find the other parts of this series here.
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` |
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 ``` |
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 https://improveandrepeat.com/2021/02/python-friday-58-customise-mkdocs#material .
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 ``` |
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 ``` |
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 ``` |
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 ``` |
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.
1 thought on “Python Friday #59: Source Code in MkDocs”