MkDocs Style Customization of Code and Blockquote

MkDocs Style Customization of Code and Blockquote

Takahiro Iwasa
Takahiro Iwasa
3 min read

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.

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

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 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 '
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.

if __name__ == "__main__":

> Hello World
' >> docs/

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

Open 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.


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 in your browser and you should see the documentation like the following.

Takahiro Iwasa

Takahiro Iwasa

Software Developer at KAKEHASHI Inc.
Involved in the requirements definition, design, and development of cloud-native applications using AWS. Now, building a new prescription data collection platform at KAKEHASHI Inc. Japan AWS Top Engineers 2020-2023.