Headings options¤

heading¤

• Type str ""

A custom string to use as the heading of the root object (i.e. the object specified directly after the identifier :::). This will override the default heading generated by the plugin. See also the toc_label option.

::: path.to.module
    options:
      heading: "My fancy module"

heading_level¤

• Type int 2

The initial heading level to use.

When injecting documentation for an object, the object itself and its members are rendered. For each layer of objects, we increase the heading level by 1.

The initial heading level will be used for the first layer. If you set it to 3, then headings will start with <h3>.

If the heading for the root object is not shown, then the initial heading level is used for its members.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          heading_level: 2

::: path.to.module
    options:
      heading_level: 3

parameter_headings¤

Insiders 1.6.0

• Type bool False

Whether to render headings for function/method parameters.

With this option enabled, each function/method parameter (including parameters of __init__ methods merged in their parent class with the merge_init_into_class option) gets a permalink, an entry in the Table of Contents, and an entry in the generated objects inventory. The permalink and inventory entry allow cross-references from internal and external pages.

The identifier used in the permalink and inventory is of the following form: path.to.function(param_name). To manually cross-reference a parameter, you can therefore use this Markdown syntax:

- Class parameter: [`param`][package.module.Class(param)]
- Method parameter: [`param`][package.module.Class.method(param)]
- Function parameter: [`param`][package.module.function(param)]
- Variadic positional parameters: [`*args`][package.module.function(*args)]
- Variadic keyword parameters: [`**kwargs`][package.module.function(**kwargs)]

Enabling this option along with signature_crossrefs will automatically render cross-references to parameters in class/function/method signatures and attributes values.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          parameter_headings: false

::: path.to.module
    options:
      parameter_headings: true

get_version(dist: str = 'mkdocstrings-python') -> str

current_version: str = get_version(dist='mkdocstrings-python')

show_root_heading¤

• Type bool False

Show the heading of the object at the root of the documentation tree (i.e. the object referenced by the identifier after :::).

It is pretty common to inject documentation for one module per page, especially when following our automatic reference pages recipe. Since each page already has a title, usually being the module's name, we can spare one heading level by not showing the heading for the module itself (heading levels are limited to 6 by the HTML specification).

Sparing that extra level can be helpful when your objects tree is deeply nested (e.g. method in a class in a class in a module). If your objects tree is not deeply nested, and you are injecting documentation for many different objects on a single page, it might be preferable to render the heading of each object.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_root_heading: false

::: path.to.ClassA
    options:
      show_root_heading: true

::: path.to.ClassB
    options:
      show_root_heading: true

show_root_toc_entry¤

• Type bool True

If the root heading is not shown, at least add a ToC entry for it.

If you inject documentation for an object in the middle of a page, after long paragraphs, and without showing the root heading, then you will not be able to link to this particular object as it won't have a permalink and will be "lost" in the middle of text. In that case, it is useful to add a hidden anchor to the document, which will also appear in the table of contents.

In other cases, you might want to disable the entry to avoid polluting the ToC. It is not possible to show the root heading and hide the ToC entry.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_root_toc_entry: true

## Some heading

Lots of text.

::: path.to.object
    options:
      show_root_toc_entry: false

## Other heading.

More text.

show_root_full_path¤

• Type bool True

Show the full Python path for the root object heading.

The path of a Python object is the dot-separated list of names under which it is accessible, for example package.module.Class.method.

With this option you can choose to show the full path of the object you inject documentation for, or just its name. This option impacts only the object you specify, not its members. For members, see the two other options show_root_members_full_path and show_object_full_path.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_root_full_path: true

::: package.module.Class.method
    options:
      show_root_full_path: false

show_root_members_full_path¤

• Type bool False

Show the full Python path of the root members.

This option does the same thing as show_root_full_path, but for direct members of the root object instead of the root object itself.

To show the full path for every member recursively, see show_object_full_path.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_root_members_full_path: true

::: package.module
    options:
      show_root_members_full_path: false

show_object_full_path¤

• Type bool False

Show the full Python path of every object.

Same as for show_root_members_full_path, but for every member, recursively. This option takes precedence over show_root_members_full_path:

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_object_full_path: true

::: package.module
    options:
      show_object_full_path: false

show_category_heading¤

• Type bool False

When grouped by categories, show a heading for each category. These category headings will appear in the table of contents, allowing you to link to them using their permalinks.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          group_by_category: true
          show_category_heading: true

::: package.module
    options:
      group_by_category: true
      show_category_heading: false

show_symbol_type_heading¤

Insiders 1.1.0

• Type bool False

Show the symbol type in headings.

This option will prefix headings with , , , or types. See also show_symbol_type_toc.

To customize symbols, see Customizing symbol types.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_symbol_type_heading: true

::: package.module
    options:
      show_symbol_type_heading: false

show_symbol_type_toc¤

Insiders 1.1.0

• Type bool False

Show the symbol type in the Table of Contents.

This option will prefix items in the ToC with , , , or types. See also show_symbol_type_heading.

To customize symbols, see Customizing symbol types.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_symbol_type_toc: true

::: package.module
    options:
      show_symbol_type_toc: false

toc_label¤

• Type str ""

A custom string to use as the label in the Table of Contents for the root object (i.e. the one specified directly after the identifier :::). This will override the default label generated by the plugin. See also the heading option.

::: path.to.module
    options:
      heading: "My fancy module"
      toc_label: "My fancy module"