| 1 |
# Themes |
| 2 |
|
| 3 |
*mkdocstrings* can support multiple MkDocs themes. |
| 4 |
It currently supports the |
| 5 |
*[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)* |
| 6 |
theme and, partially, the built-in MkDocs and ReadTheDocs themes. |
| 7 |
|
| 8 |
Each handler can fallback to a particular theme when the user selected theme is not supported. |
| 9 |
For example, the Python handler will fallback to the *Material for MkDocs* templates. |
| 10 |
|
| 11 |
## Customization |
| 12 |
|
| 13 |
There is some degree of customization possible in *mkdocstrings*. |
| 14 |
First, you can write custom templates to override the theme templates. |
| 15 |
Second, the provided templates make use of CSS classes, |
| 16 |
so you can tweak the look and feel with extra CSS rules. |
| 17 |
|
| 18 |
### Templates |
| 19 |
|
| 20 |
To use custom templates and override the theme ones, specify the relative path from your |
| 21 |
configuration file to your templates directory with the `custom_templates` global |
| 22 |
configuration option: |
| 23 |
|
| 24 |
```yaml title="mkdocs.yml" |
| 25 |
plugins: |
| 26 |
- mkdocstrings: |
| 27 |
custom_templates: templates |
| 28 |
``` |
| 29 |
|
| 30 |
Your directory structure must be identical to the provided templates one: |
| 31 |
|
| 32 |
``` |
| 33 |
π templates/ |
| 34 |
βββ΄π <HANDLER 1>/ |
| 35 |
β βββ π <THEME 1>/ |
| 36 |
β βββ π <THEME 2>/ |
| 37 |
βββ π <HANDLER 2>/ |
| 38 |
βββ π <THEME 1>/ |
| 39 |
βββ π <THEME 2>/ |
| 40 |
``` |
| 41 |
|
| 42 |
For example, check out the Python |
| 43 |
[template tree](https://github.com/mkdocstrings/python/tree/master/src/mkdocstrings_handlers/python/templates/) |
| 44 |
on GitHub. |
| 45 |
|
| 46 |
You don't have to replicate the whole tree, |
| 47 |
only the handlers, themes or templates you want to override. |
| 48 |
For example, to override some templates of the *Material* theme for Python: |
| 49 |
|
| 50 |
``` |
| 51 |
π templates/ |
| 52 |
βββ π python/ |
| 53 |
βββ π material/ |
| 54 |
βββ π parameters.html |
| 55 |
βββ π exceptions.html |
| 56 |
``` |
| 57 |
|
| 58 |
In the HTML files, replace the original contents with your modified version. |
| 59 |
In the future, the templates will use Jinja blocks, so it will be easier |
| 60 |
to modify small part of the templates without copy-pasting the whole files. |
| 61 |
|
| 62 |
See the documentation about templates for: |
| 63 |
|
| 64 |
- the Crystal handler: https://mkdocstrings.github.io/crystal/styling.html |
| 65 |
- the Python handler: https://mkdocstrings.github.io/python/usage/customization/#templates |
| 66 |
|
| 67 |
#### Debugging |
| 68 |
|
| 69 |
Every template has access to a `log` function, allowing to log messages as usual: |
| 70 |
|
| 71 |
```jinja |
| 72 |
{{ log.debug("A DEBUG message.") }} |
| 73 |
{{ log.info("An INFO message.") }} |
| 74 |
{{ log.warning("A WARNING message.") }} |
| 75 |
{{ log.error("An ERROR message.") }} |
| 76 |
{{ log.critical("A CRITICAL message.") }} |
| 77 |
``` |
| 78 |
|
| 79 |
### CSS classes |
| 80 |
|
| 81 |
Since each handler provides its own set of templates, with their own CSS classes, |
| 82 |
we cannot list them all here. See the documentation about CSS classes for: |
| 83 |
|
| 84 |
- the Crystal handler: https://mkdocstrings.github.io/crystal/styling.html#custom-styles |
| 85 |
- the Python handler: https://mkdocstrings.github.io/python/usage/customization/#css-classes |
| 86 |
|
| 87 |
### Syntax highlighting |
| 88 |
|
| 89 |
Code blocks that occur in the docstring of an item inserted with *mkdocstrings*, as well as code blocks (such as *Source code*) that *mkdocstrings* inserts itself, are syntax-highlighted according to the same rules as other normal code blocks in your document. See more details in [mkdocstrings.Highlighter][]. |
| 90 |
|
| 91 |
As for the CSS class used for code blocks -- it will also match the "normal" config, so the default (`.codehilite` or `.highlight`) will match your chosen Markdown extension for highlighting. |
| 92 |
|
| 93 |
IMPORTANT: **Changed in version 0.15.** |
| 94 |
The CSS class used to always be `.highlight`, but now it depends on the configuration. |
| 95 |
|
| 96 |
Long story short, you probably should add `pymdownx.highlight` to your `markdown_extensions`, and then use `.doc-contents .highlight` as the CSS selector in case you want to change something about *mkdocstrings'* code blocks specifically. |