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