Directives¶

A directive is a generic block of explicit markup that is powerful and extensible. In mistune v3, there are 2 styles of directives for now:

reStructuredText style
fenced style

Changed in version 3.0: Fenced style directive is added in 3.0. Because v3 has multiple styles of directives, developers can not add each directive into plugins parameter of mistune.create_markdown directly. Instead, each directive should be wrapped by:

import mistune
from mistune.directives import FencedDirective, RSTDirective
from mistune.directives import Admonition, TableOfContents

markdown = mistune.create_markdown(plugins=[
    'math',
    'footnotes',
    # ...
    FencedDirective([
        Admonition(),
        TableOfContents(),
    ]),
])

markdown = mistune.create_markdown(plugins=[
    'math',
    'footnotes',
    # ...
    RSTDirective([
        Admonition(),
        TableOfContents(),
    ]),
])

A reStructuredText style of directive is inspired by reStructuredText, and the syntax looks like:

.. directive-type:: title
   :option-key: option value
   :option-key: option value

   content text here

A fenced style of directive looks like a fenced code block, it is inspired by markdown-it-docutils. The syntax looks like:

```{directive-type} title
:option-key: option value
:option-key: option value

content text here
```

Developers can choose the directive style in their own favor.

Admonitions¶

The reStructuredText style syntax:

.. warning::

   You are looking at the **dev** documentation. Check out our
   [stable](/stable/) documentation instead.

The fenced style syntax:

```{warning}
You are looking at the **dev** documentation. Check out our
[stable](/stable/) documentation instead.
```

Admonitions contains a group of directive-name:

attention  caution  danger  error
hint  important  note  tip  warning

To enable admonitions:

import mistune
from mistune.directives import Admonition

markdown = mistune.create_markdown(
    plugins=[
        ...
        RSTDirective([Admonition()]),
        # FencedDirective([Admonition()]),
    ]
)

Table of Contents¶

.. toc:: Table of Contents
   :max-level: 3

TOC plugin is based on directive. It can add a table of contents section in the documentation. Let’s take an example:

Here is the first paragraph, and we put TOC below.

.. toc::

# H1 title

## H2 title

# H1 title

The rendered HTML will show a TOC at the .. toc:: position. To enable TOC plugin:

import mistune
from mistune.directives import RSTDirective, TableOfContents

markdown = mistune.create_markdown(
    plugins=[
        # ...
        RSTDirective([TableOfContents()]),
    ]
)

Include¶

.. include:: hello.md

include is a powerful plugin for documentation generator. With this plugin, we can embed contents from other files.

Image¶

```{image} https://domain/path.png
:alt: alt text
:width: 800
:height: 500
```

Figure¶

```{figure} https://domain/path.png
:alt: alt text
:width: 800
:height: 500
```