Skip to content


Code blocks in admonitions (in docstrings or else) are not rendered correctly¤

To render code blocks in admonitions, you need to add the pymdownx.superfences extensions to the list of Markdown extensions in mkdocs.yml. For example:

!!! note
    Some text.

    echo "some code"
- admonition
- codehilite
- pymdownx.superfences

For code blocks in docstrings, make sure to escape newlines (\n -> \\n), or prefix the entire docstring with 'r' to make it a raw-docstring: r""". Indeed, docstrings are still strings and therefore subject to how Python parses strings.

Footnotes are duplicated or overridden¤

Before version 0.14, footnotes could be duplicated over a page. Please upgrade to version 0.14 or higher.

See also:

A warning like this one:

WARNING - Documentation file 'reference/parsers/' contains a link to 'reference/parsers/pytkdocs.parsers.docstrings.Section' which is not found in the documentation files.

...generally means you used parentheses () instead of brackets [] for a cross-reference. Notice the dots in reference/parsers/pytkdocs.parsers.docstrings.Section? It shows that it's probably a cross-reference, not a direct link. It's probably written like [Section](pytkdocs.parsers.docstrings.Section) in the docs, when it should be [Section][pytkdocs.parsers.docstrings.Section].

Some objects are not rendered (they do not appear in the generated docs)¤

  • Make sure the configuration options of the handler are correct. Check the documentation for Handlers to see the available options for each handler.
  • Also make sure your documentation in your source code is formatted correctly. For Python code, check the supported docstring styles page.
  • Re-run the Mkdocs command with -v, and carefully read any traceback.

Tabs in docstrings (from pymdownx.tabbed) are not working properly¤

Before version 0.14, multiple tab blocks injected on the same page would result in broken links: clicking on a tab would bring the user to the wrong one. Please upgrade to version 0.14 or higher.

See also:

If you are stuck on a version before 0.14, and want to use multiple tab blocks in one page, use this workaround.

JavaScript workaround

Put the following code in a .js file, and list it in MkDocs' extra_javascript:

// Credits to Nikolaos Zioulis (@zuru on GitHub)
function setID(){
    var tabs = document.getElementsByClassName("tabbed-set");
    for (var i = 0; i < tabs.length; i++) {
        children = tabs[i].children;
        var counter = 0;
        var iscontent = 0;
        for(var j = 0; j < children.length;j++){
            if(typeof children[j].htmlFor === 'undefined'){
                if((iscontent + 1) % 2 == 0){
                    // check if it is content
                    if(iscontent == 1){
                        btn = children[j].childNodes[1].getElementsByTagName("button");
                    // if not change the id
                    children[j].id = "__tabbed_" + String(i + 1) + "_" + String(counter + 1);
                    children[j].name = "__tabbed_" + String(i + 1);
                    // make default tab open
                    if(j == 0)
                // link to the correct tab
                children[j].htmlFor = "__tabbed_" + String(i+1) + "_" + String(counter + 1);
                counter ++;

This code will correctly reset the IDs for tabs on a same page.

The generated documentation does not look good¤

Please open an ticket on the bugtracker with a detailed explanation and screenshots of the bad-looking parts. Note that you can always customize the look of mkdocstrings blocks -- through both HTML and CSS.

Warning: could not find cross-reference target¤

New in version 0.15

Cross-linking used to include any Markdown heading, but now it's only for mkdocstrings identifiers by default. See Cross-references to any Markdown heading to opt back in.

Make sure the referenced object is properly rendered: verify your configuration options.

For false-positives, you can wrap the text in backticks (`) to prevent mkdocstrings from trying to process it.

Python specifics¤

Nothing is rendered at all¤

Is your package available in the Python path?

See Python handler: Finding modules.

LaTeX in docstrings is not rendered correctly¤

If you are using a Markdown extension like Arithmatex Mathjax or markdown-katex to render LaTeX, add r in front of your docstring to make sure nothing is escaped. You'll still maybe have to play with escaping to get things right.


def math_function(x, y):
    Look at these formulas:

    f(x) = \int_{-\infty}^\infty
    \hat f(\xi)\,e^{2 \pi i \xi x}

My docstrings in comments (#:) are not picked up¤

It's because we do not support type annotations in comments.

So instead of:

import enum

class MyEnum(enum.Enum):
    v1 = 1  #: The first choice.
    v2 = 2  #: The second choice.

You can use:

import enum

class MyEnum(enum.Enum):
    """My enum.

        v1: The first choice.
        v2: The second choice.

    v1 = 1
    v2 = 2


import enum

class MyEnum(enum.Enum):
    v1 = 1
    """The first choice."""

    v2 = 2
    """The second choice."""

My wrapped function shows documentation/code for its wrapper instead of its own¤

Use functools.wraps():

from functools import wraps

def my_decorator(function):
    """The decorator docs."""

    def wrapped_function(*args, **kwargs):
        function(*args, **kwargs)

    return wrapped_function

def my_function(*args, **kwargs):
    """The function docs."""
    print(*args, **kwargs)