Styling your docs
How to style and theme your documentation.
Built-in themes
Bootstrap
Read the Docs
The bootswatch themes
Custom themes
The bare minimum required for a custom theme is a base.html
template file. This should be placed in a directory at the same level as the mkdocs.yml
configuration file. Within mkdocs.yml
, specify the theme_dir
option and set it to the name of the directory containing base.html
. For example, given this example project layout:
mkdocs.yml
docs/
index.md
about.md
custom_theme/
base.html
...
You would include the following setting to use the custom theme directory:
theme_dir: 'custom_theme'
If used in combination with the theme
configuration value a custom theme can be used to replace only specific parts of a built-in theme. For example, with the above layout and if you set theme: mkdocs
then the base.html
file would replace that in the theme but otherwise it would remain the same. This is useful if you want to make small adjustments to an existing theme.
The simplest base.html
file is the following:
<!DOCTYPE html>
<html>
<head>
</head>
<body>
{{ content }}
</body>
</html>
Article content from each page specified in mkdocs.yml
is inserted using the {{ content }}
tag. Stylesheets and scripts can be brought into this theme as with a normal HTML file. Navbars and tables of contents can also be generated and included automatically, through the nav
and toc
objects, respectively. If you wish to write your own theme, it is recommended to start with one of the built-in themes and modify it accordingly.