Debian Codegraph @

docs/usage/theming.md

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