MkDocs Style Customization of Code and Blockquote

Takahiro Iwasa

Jan 8, 2023

3 min read

MkDocs

MkDocs, a tool for creating documentation using Markdown, allows users to customize the style. This post describes how to customize code block and blockquote style.

www.mkdocs.org

MkDocs

Project documentation with Markdown.

You can also find available themes on the official page. Please see the official MkDocs documentation for more details.

www.mkdocs.org

Choosing Your Theme - MkDocs

Installing MkDocs

Install MkDocs with the following command.

$ pip install mkdocs

Create a new project with the following command.

$ mkdocs new sample-doc
$ cd sample-doc

Default Style

Edit index.md and add a sample code block and blockquote with the following content. This sample text below was generated by 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

Start the built-in documentation server.

$ 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/

Open http://127.0.0.1:8000/ in your browser and you should see the documentation like the following.

By default, the line height may be too narrow, and the blockquote may not have any styling.

Customizing

Add extra.css with the following content to the sample-doc/docs/ directory.

code {
  line-height: 2;
}

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

Add the following line to your mkdocs.yml, which applies the CSS file to your site.

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

Open http://127.0.0.1:8000/ in your browser and you should see the documentation like the following.