Skip to content

Headings options¤

heading¤

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.

Not advised to be used as a global configuration option

This option is not advised to be used as a global configuration option, as it will override the default heading for all objects. It is recommended to use it only in specific cases where you want to override the heading for a specific object.

in docs/some_page.md (local configuration)
::: your-script
    options:
      heading: "My fancy module"

heading_level¤

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

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      shell:
        options:
          heading_level: 2
or in docs/some_page.md (local configuration)
::: your-script
    options:
      heading_level: 3

Preview

script (3)

Docstring of the script.

functionA (4)

Docstring of function A.

Docstring of the script.

functionA (3)

Docstring of function A.

show_symbol_type_heading¤

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.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      shell:
        options:
          show_symbol_type_heading: true
or in docs/some_page.md (local configuration)
::: your-script
    options:
      show_symbol_type_heading: false

Preview

script

Docstring of the script.

function

Docstring of the function.

script

Docstring of the script.

function

Docstring of the function.

show_symbol_type_toc¤

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.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      shell:
        options:
          show_symbol_type_toc: true
or in docs/some_page.md (local configuration)
::: your-script
    options:
      show_symbol_type_toc: false

Preview

  • script
  • function
  • script
  • function

toc_label¤

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.

Not advised to be used as a global configuration option

This option is not advised to be used as a global configuration option, as it will override the default label for all objects. It is recommended to use it only in specific cases where you want to override the label for a specific object.

Use with/without heading

If you use this option without specifying a custom heading, the default heading will be used in the page, but the label in the Table of Contents will be the one you specified. By providing both an option for heading and toc_label, we leave the customization entirely up to you.

in docs/some_page.md (local configuration)
::: your-script
    options:
      heading: "My fancy script"
      toc_label: "My fancy script"