Styling your docs

How to style and theme your documentation.

MkDocs includes a number of different builtin themes and external themes which can easily be customised with extra CSS or JavaScript or you can create a custom theme for your documentation.

To use a theme that is included in MkDocs, simply add this to your mkdocs.yml config file.

theme: readthedocs

Replace readthedocs with any of the builtin themes listed below.

To create a new custom theme or more heavily customise an existing theme, see the custom themes section below.

Built-in themes

mkdocs

mkdocs

readthedocs

ReadTheDocs

Bootstrap and Bootswatch Themes

MkDocs also includes themes provided by two packages. MkDocs Bootstrap and MkDocs Bootswatch. The Bootstrap theme provides a theme based on Bootstrap and the Bootstrap theme provides 12 different themed Bootstrap themes based on the Bootswatch project.

Note

The Bootstrap and Bootswatch themes will not be included by default from MkDocs version 1.0. They will need to be installed manually with pip install mkdocs-bootstrap or pip install mkdocs-bootswatch.

Bootstrap

Bootstrap

Amelia

Cerulean

Cosmo

Cyborg

Flatly

Journal

Readable

Simplex

Slate

Spacelab

United

Yeti

Customising a Theme

The extra_css and extra_javascript configuration options can be used to make tweaks and customisations to existing themes. To use these, you simply need to include either CSS or JavaScript files within your documentation directory.

For example, to change the colour of the headers in your documentation, create a file called extra.css and place it next to the documentation Markdown. In that file add the following CSS.

h1 {
  color: red;
}

Note

If you are deploying your documentation with ReadTheDocs. You will need to explicitly list the CSS and JavaScript files you want to include in your config. To do this, add the following to your mkdocs.yml.

extra_css: [extra.css]

After making these changes, they should be visible when you run mkdocs serve - if you already had this running, you should see that the CSS changes were automatically picked up and the documentation will be updated.