Styling MkDocs Code Blocks and Blockquotes

Takahiro Iwasa

Jan 9, 2023

3 min read

MkDocs

MkDocs is a powerful tool for creating documentation using Markdown. It offers flexibility for customizing styles to make your documentation visually appealing and professional. This post will guide you through customizing code block and blockquote styles.

You can install MkDocs using the following command:

pip install mkdocs

To create a new project, use:

mkdocs new sample-doc
cd sample-doc

Edit the index.md file and include a sample code block and blockquote using the following content. The sample text is generated by the Microsoft Word random text generator =rand().

echo '
```python
def print_text() -> None:
    text = """
Video provides a powerful way to help you prove your point. When you click Online Video, you can paste in the embed code for the video you want to add. You can also type a keyword to search online for the video that best fits your document.
To make your document look professionally produced, Word provides header, footer, cover page, and text box designs that complement each other. For example, you can add a matching cover page, header, and sidebar. Click Insert and then choose the elements you want from the different galleries.
Themes and styles also help keep your document coordinated. When you click Design and choose a new Theme, the pictures, charts, and SmartArt graphics change to match your new theme. When you apply styles, your headings change to match the new theme.
Save time in Word with new buttons that show up where you need them. To change the way a picture fits in your document, click it and a button for layout options appears next to it. When you work on a table, click where you want to add a row or a column, and then click the plus sign.
Reading is easier, too, in the new Reading view. You can collapse parts of the document and focus on the text you want. If you need to stop reading before you reach the end, Word remembers where you left off - even on another device.
"""
    print(text)


if __name__ == "__main__":
    print_text()
```

> Hello World
' >> docs/index.md

To test your documentation, run the following command:

$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.04 seconds
INFO     -  [20:24:33] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [20:24:33] Serving on http://127.0.0.1:8000/

Visit http://127.0.0.1:8000/ in your browser. You should see the documentation with default styles. Notice that the line height in code blocks might be too narrow, and blockquotes may lack any styling.

To improve the appearance, create a CSS file named extra.css in the sample-doc/docs/ directory with the following content:

code {
  line-height: 2;
}

blockquote {
  border-left: 4px solid gray;
  font-style: italic;
  padding-left: 1em;
}

Add this CSS file to your mkdocs.yml configuration file:

echo 'extra_css: [extra.css]' >> mkdocs.yml

Restart the MkDocs server with:

mkdocs serve

Open http://127.0.0.1:8000/ in your browser. You will see the updated documentation with:

• Improved line height in code blocks for better readability.
• Stylized blockquotes with a border and italicized text for emphasis.

Customizing MkDocs styles allows you to make your documentation more engaging and easier to read. With a few simple adjustments, your documentation can stand out and provide a professional impression.

For further customization ideas, refer to the official MkDocs documentation.

Happy Coding! 🚀