Skip to content

Customization¤

It is possible to customize the output of the generated documentation with CSS and/or by overriding templates.

CSS classes¤

Our templates add CSS classes to many HTML elements to make it possible for users to customize the resulting look and feel.

To add CSS rules and style mkdocstrings' output, put them in a CSS file in your docs folder, for example in docs/css/mkdocstrings.css, and reference this file in MkDocs' extra_css configuration option:

mkdocs.yml
extra_css:
- css/mkdocstrings.css

Example:

docs/css/mkdocstrings.css
.doc-section-title {
  font-weight: bold;
}

The following CSS classes are used in the generated HTML:

  • doc: on all the following elements
  • doc-children: on divs containing the children of an object
  • doc-object: on divs containing an object
    • doc-attribute: on divs containing an attribute
    • doc-class: on divs containing a class
    • doc-function: on divs containing a function
    • doc-module: on divs containing a module
  • doc-heading: on objects headings
    • doc-object-name: on spans wrapping objects names/paths in the heading
      • doc-KIND-name: as above, specific to the kind of object (module, class, function, attribute)
  • doc-contents: on divs wrapping the docstring then the children (if any)
    • first: same, but only on the root object's contents div
  • doc-labels: on spans wrapping the object's labels
    • doc-label: on small elements containing a label
      • doc-label-LABEL: same, where LABEL is replaced by the actual label
  • doc-section-title: on section titles (depend on the selected style for section rendering)
  • doc-section-item: on section items (depend on the selected style for section rendering)
  • doc-md-description: on divs containing HTML descriptions converted from Markdown docstrings
  • doc-symbol: on code tags of symbol types
    • doc-symbol-heading: on symbol types in headings
    • doc-symbol-toc: on symbol types in the ToC
    • doc-symbol-KIND: specific to the kind of object (module, class, function, method, attribute)

Example with colorful labels

.doc-label { border-radius: 15px; padding: 2px 8px; font-weight: bold; }
.doc-label-special { background-color: #3330E4; color: white; }
.doc-label-private { background-color: #F637EC; color: white; }
.doc-label-property { background-color: #FBB454; color: black; }
.doc-label-read-only { background-color: #FAEA48; color: black; }

special private property read-only

Symbol types¤

Colors¤

You can customize the colors of the symbol types (see show_symbol_type_heading and show_symbol_type_toc) by overriding the values of our CSS variables, for example:

docs/css/mkdocstrings.css
[data-md-color-scheme="default"] {
  --doc-symbol-parameter-fg-color: #df50af;
  --doc-symbol-attribute-fg-color: #0079ff;
  --doc-symbol-function-fg-color: #00dfa2;
  --doc-symbol-method-fg-color: #00dfa2;
  --doc-symbol-class-fg-color: #d1b619;
  --doc-symbol-module-fg-color: #ff0060;

  --doc-symbol-parameter-bg-color: #df50af1a;
  --doc-symbol-attribute-bg-color: #0079ff1a;
  --doc-symbol-function-bg-color: #00dfa21a;
  --doc-symbol-method-bg-color: #00dfa21a;
  --doc-symbol-class-bg-color: #d1b6191a;
  --doc-symbol-module-bg-color: #ff00601a;
}

[data-md-color-scheme="slate"] {
  --doc-symbol-parameter-fg-color: #ffa8cc;
  --doc-symbol-attribute-fg-color: #963fb8;
  --doc-symbol-function-fg-color: #6d67e4;
  --doc-symbol-method-fg-color: #6d67e4;
  --doc-symbol-class-fg-color: #46c2cb;
  --doc-symbol-module-fg-color: #f2f7a1;

  --doc-symbol-parameter-bg-color: #ffa8cc1a;
  --doc-symbol-attribute-bg-color: #963fb81a;
  --doc-symbol-function-bg-color: #6d67e41a;
  --doc-symbol-method-bg-color: #6d67e41a;
  --doc-symbol-class-bg-color: #46c2cb1a;
  --doc-symbol-module-bg-color: #f2f7a11a;
}

The [data-md-color-scheme="*"] selectors work with the Material for MkDocs theme. If you are using another theme, adapt the selectors to this theme if it supports light and dark themes, otherwise just override the variables at root level:

docs/css/mkdocstrings.css
:root {
  --doc-symbol-parameter-fg-color: #df50af;
  --doc-symbol-attribute-fg-color: #0079ff;
  --doc-symbol-function-fg-color: #00dfa2;
  --doc-symbol-method-fg-color: #00dfa2;
  --doc-symbol-class-fg-color: #d1b619;
  --doc-symbol-module-fg-color: #ff0060;

  --doc-symbol-parameter-bg-color: #df50af1a;
  --doc-symbol-attribute-bg-color: #0079ff1a;
  --doc-symbol-function-bg-color: #00dfa21a;
  --doc-symbol-method-bg-color: #00dfa21a;
  --doc-symbol-class-bg-color: #d1b6191a;
  --doc-symbol-module-bg-color: #ff00601a;
}

Preview

Try cycling through the themes to see the colors for each theme:

Names¤

You can also change the actual symbol names. For example, to use single letters instead of truncated types:

docs/css/mkdocstrings.css
.doc-symbol-parameter::after {
  content: "P";
}

.doc-symbol-attribute::after {
  content: "A";
}

.doc-symbol-function::after {
  content: "F";
}

.doc-symbol-method::after {
  content: "M";
}

.doc-symbol-class::after {
  content: "C";
}

.doc-symbol-module::after {
  content: "M";
}

Preview

  • Parameter:
  • Attribute:
  • Function:
  • Method:
  • Class:
  • Module:

Templates¤

Templates are organized into the following tree:

📁 theme/
├──  attribute.html
├──  attribute.html.jinja
├──  children.html
├──  children.html.jinja
├──  class.html
├──  class.html.jinja
├── 📁 docstring/
│   ├──  admonition.html
│   ├──  admonition.html.jinja
│   ├──  attributes.html
│   ├──  attributes.html.jinja
│   ├──  classes.html
│   ├──  classes.html.jinja
│   ├──  examples.html
│   ├──  examples.html.jinja
│   ├──  functions.html
│   ├──  functions.html.jinja
│   ├──  modules.html
│   ├──  modules.html.jinja
│   ├──  other_parameters.html
│   ├──  other_parameters.html.jinja
│   ├──  parameters.html
│   ├──  parameters.html.jinja
│   ├──  raises.html
│   ├──  raises.html.jinja
│   ├──  receives.html
│   ├──  receives.html.jinja
│   ├──  returns.html
│   ├──  returns.html.jinja
│   ├──  warns.html
│   ├──  warns.html.jinja
│   ├──  yields.html
│   └──  yields.html.jinja
├──  docstring.html
├──  docstring.html.jinja
├──  expression.html
├──  expression.html.jinja
├──  function.html
├──  function.html.jinja
├──  labels.html
├──  labels.html.jinja
├──  language.html
├──  language.html.jinja
├── 📁 languages/
│   ├──  en.html
│   ├──  en.html.jinja
│   ├──  ja.html
│   ├──  ja.html.jinja
│   ├──  zh.html
│   └──  zh.html.jinja
├──  module.html
├──  module.html.jinja
├──  signature.html
├──  signature.html.jinja
├── 📁 summary/
│   ├──  attributes.html
│   ├──  attributes.html.jinja
│   ├──  classes.html
│   ├──  classes.html.jinja
│   ├──  functions.html
│   ├──  functions.html.jinja
│   ├──  modules.html
│   └──  modules.html.jinja
├──  summary.html
└──  summary.html.jinja

See them in the repository. See the general mkdocstrings documentation to learn how to override them: https://mkdocstrings.github.io/theming/#templates.

Each one of these templates extends a base version in theme/_base. Example:

theme/class.html
{% extends "_base/class.html" %}

Some of these templates define Jinja blocks. allowing to customize only parts of a template without having to fully copy-paste it into your project:

templates/theme/class.html
{% extends "_base/class.html" %}
{% block contents %}
  {{ block.super }}
  Additional contents
{% endblock contents %}

Available blocks¤

Only the templates for the Material for MkDocs provide Jinja blocks. The following tables show the block names, description, and the Jinja context available in their scope.

module.html¤

  • heading: The module heading.
  • labels: The module labels.
  • contents: The module contents: docstring and children blocks.
  • docstring: The module docstring.
  • summary: The automatic summaries of members.
  • children: The module children.

Available context:

  • config: The handler configuration (dictionary).
  • module: The Module instance.

class.html¤

  • heading: The class heading.
  • labels: The class labels.
  • signature: The class signature.
  • contents: The class contents: bases, docstring, source and children blocks.
  • bases: The class bases.
  • docstring: The class docstring.
  • summary: The automatic summaries of members.
  • source: The class source code.
  • children: The class children.

Available context:

  • config: The handler configuration (dictionary).
  • class: The Class instance.

function.html¤

  • heading: The function heading.
  • labels: The function labels.
  • signature: The function signature.
  • contents: The function contents: docstring and source blocks.
  • docstring: The function docstring.
  • source: The function source code.

Available context:

  • config: The handler configuration (dictionary).
  • function: The Function instance.

attribute.html¤

  • heading: The attribute heading.
  • labels: The attribute labels.
  • signature: The attribute signature.
  • contents: The attribute contents: docstring block.
  • docstring: The attribute docstring.

Available context:

  • config: The handler configuration (dictionary).
  • attribute: The Attribute instance.

Docstring sections¤

In docstring/attributes.html, docstring/functions.html, docstring/classes.html, docstring/modules.html, docstring/other_parameters.html, docstring/parameters.html, docstring/raises.html, docstring/receives.html, docstring/returns.html, docstring/warns.html, and docstring/yields.html:

  • table_style: The section as a table.
  • list_style: The section as a list.
  • spacy_style: The section as a Spacy table.

Available context:

Syntax highlight in signatures¤

You can customize the colors in syntax highlighted signatures. If you are using the Material for MkDocs theme, here are some customization examples:

/* Fancier color for operators such as * and |. */
.doc-signature .o {
  color: var(--md-code-hl-special-color);
}

/* Fancier color for constants such as None, True, and False. */
.doc-signature .kc {
  color: var(--md-code-hl-constant-color);
}

/* Fancier color for built-in types (only useful when cross-references are used). */
.doc-signature .n > a[href^="https://docs.python.org/"][href*="/functions.html#"],
.doc-signature .n > a[href^="https://docs.python.org/"][href*="/stdtypes.html#"] {
  color: var(--md-code-hl-constant-color);
}

For other themes, use their own CSS variables, or use plain colors such as violet or #2987f2.

Style recommendations¤

Material¤

Here are some CSS rules for the Material for MkDocs theme:

/* Indentation. */
div.doc-contents:not(.first) {
  padding-left: 25px;
  border-left: .05rem solid var(--md-typeset-table-color);
}

/* Mark external links as such. */
a.external::after,
a.autorefs-external::after {
  /* https://primer.style/octicons/arrow-up-right-24 */
  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
  content: ' ';

  display: inline-block;
  vertical-align: middle;
  position: relative;

  height: 1em;
  width: 1em;
  background-color: currentColor;
}

a.external:hover::after,
a.autorefs-external:hover::after {
  background-color: var(--md-accent-fg-color);
}

ReadTheDocs¤

Here are some CSS rules for the built-in ReadTheDocs theme:

/* Indentation. */
div.doc-contents:not(.first) {
  padding-left: 25px;
  border-left: .05rem solid rgba(200, 200, 200, 0.2);
}