Mistune

https://mistune.lepture.com/en/latest/
Admin
Mistune is a fast yet powerful Python Markdown parser with renderers and plugins, compatible with...
Tokens:13,358
Snippets:169
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Ruby Plugin Example

Source: https://mistune.lepture.com/en/latest/api.html

Demonstrates the syntax for ruby markup support.

```markdown
[漢字(ㄏㄢˋㄗˋ)]
[漢(ㄏㄢˋ)字(ㄗˋ)]

[漢字(ㄏㄢˋㄗˋ)][link]
[漢字(ㄏㄢˋㄗˋ)](/url "title")

[link]: /url "title"

```

--------------------------------

### Ruby Syntax Examples

Source: https://mistune.lepture.com/en/latest/plugins.html

Examples of Markdown syntax for ruby tags and their corresponding HTML output.

```markdown
[漢字(ㄏㄢˋㄗˋ)]

[link]: /url

[漢字(ㄏㄢˋㄗˋ)][link]

[漢字(ㄏㄢˋㄗˋ)](/url)

[漢(ㄏㄢˋ)字(ㄗˋ)]
```

```html
<p><ruby><rb>漢字</rb><rt>ㄏㄢˋㄗˋ</rt></ruby></p>
<p><a href="/url"><ruby><rb>漢字</rb><rt>ㄏㄢˋㄗˋ</rt></ruby></a></p>
<p><a href="/url"><ruby><rb>漢字</rb><rt>ㄏㄢˋㄗˋ</rt></ruby></a></p>
<p><ruby><rb>漢</rb><rt>ㄏㄢˋ</rt></ruby><ruby><rb>字</rb><rt>ㄗˋ</rt></ruby></p>
```

--------------------------------

### Table Plugin Example

Source: https://mistune.lepture.com/en/latest/api.html

Demonstrates the standard Markdown table syntax.

```markdown
First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

```

--------------------------------

### Math Plugin Example

Source: https://mistune.lepture.com/en/latest/api.html

Shows the syntax for block and inline math expressions.

```markdown
Block math is surrounded by $$:

$$
f(a)=f(b)
$$

Inline math is surrounded by `$`, such as $f(a)=f(b)$

```

--------------------------------

### Install Mistune via pip

Source: https://mistune.lepture.com/en/latest/index.html

Use pip to install the specific version of Mistune.

```bash
$ pip install mistune==3.2.1
```

--------------------------------

### Task List Plugin Example

Source: https://mistune.lepture.com/en/latest/api.html

Shows the syntax for creating task lists in Markdown.

```markdown
- [ ] unchecked task
- [x] checked task

```

--------------------------------

### Definition List Plugin Example

Source: https://mistune.lepture.com/en/latest/api.html

Shows the syntax for definition lists and the corresponding HTML output.

```markdown
Apple
:   Pomaceous fruit of plants of the genus Malus in
    the family Rosaceae.

Orange
:   The fruit of an evergreen tree of the genus Citrus.

```

```html
<dl>
<dt>Apple</dt>
<dd>Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.</dd>

<dt>Orange</dt>
<dd>The fruit of an evergreen tree of the genus Citrus.</dd>
</dl>

```

--------------------------------

### Abbreviation Plugin Example

Source: https://mistune.lepture.com/en/latest/api.html

Demonstrates how to define and use abbreviations in Markdown.

```markdown
The HTML specification
is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium

```

```html
The <abbr title="Hyper Text Markup Language">HTML</abbr> specification
is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.

```

--------------------------------

### Insert Plugin Syntax

Source: https://mistune.lepture.com/en/latest/api.html

Example of the insert syntax supported by the plugin.

```markdown
^^insert me^^
```

--------------------------------

### Spoiler Syntax Examples

Source: https://mistune.lepture.com/en/latest/plugins.html

Examples of block and inline spoiler syntax and their corresponding HTML output.

```markdown
>! here is the spoiler content
>!
>! it will be hidden
```

```html
<div class="spoiler">
<p>here is the spoiler content</p>
<p>it will be hidden</p>
</div>
```

```markdown
this is the >! hidden text !<
```

```html
<p>this is the <span class="spoiler">hidden text</span></p>
```

--------------------------------

### Mark Plugin Syntax

Source: https://mistune.lepture.com/en/latest/api.html

Example of the mark syntax supported by the plugin.

```markdown
==mark me== ==mark \=\= equal==
```

--------------------------------

### Define a setex heading

Source: https://mistune.lepture.com/en/latest/api.html

Example of the setex style heading syntax.

```markdown
H1 title
========
```

--------------------------------

### Subscript Plugin Syntax

Source: https://mistune.lepture.com/en/latest/api.html

Example of the subscript syntax supported by the plugin.

```markdown
H~2~O is a liquid.
```

--------------------------------

### Superscript Plugin Syntax

Source: https://mistune.lepture.com/en/latest/api.html

Example of the superscript syntax supported by the plugin.

```markdown
2^10^ is 1024.
```

--------------------------------

### Mistune CLI Usage Examples

Source: https://mistune.lepture.com/en/latest/cli.html

Common patterns for converting Markdown strings, files, and using pipes.

```bash
$ python -m mistune -m "Hi **Markdown**"
<p>Hi <strong>Markdown</strong></p>
```

```bash
$ python -m mistune -f README.md
<p>...
```

```bash
$ cat README.md | python -m mistune
<p>...
```

--------------------------------

### Footnote Plugin Example

Source: https://mistune.lepture.com/en/latest/api.html

Demonstrates the input Markdown for footnotes and the resulting HTML output.

```markdown
That's some text with a footnote.[^1]

[^1]: And that's the footnote.

```

```html
<p>That's some text with a footnote.<sup class="footnote-ref" id="fnref-1"><a href="#fn-1">1</a></sup></p>
<section class="footnotes">
<ol>
<li id="fn-1"><p>And that's the footnote.<a href="#fnref-1" class="footnote">&#8617;</a></p></li>
</ol>
</section>

```

--------------------------------

### Define block level math syntax

Source: https://mistune.lepture.com/en/latest/advanced.html

Example of block-level math syntax.

```text
$$
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
$$
```

--------------------------------

### RST Directive Syntax

Source: https://mistune.lepture.com/en/latest/api.html

Example of the RST-style directive syntax.

```rst
.. directive-type:: directive value
   :option-key: option value
   :option-key: option value

   content text here
```

--------------------------------

### Define inline level math syntax

Source: https://mistune.lepture.com/en/latest/advanced.html

Example of inline-level math syntax.

```text
function $f$
```

--------------------------------

### Fenced Directive Syntax

Source: https://mistune.lepture.com/en/latest/api.html

Example of the fenced directive syntax.

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

content text here
```
```

--------------------------------

### Strikethrough Plugin Syntax

Source: https://mistune.lepture.com/en/latest/api.html

Example of the strikethrough markdown syntax supported by the plugin.

```markdown
~~This was mistaken text~~
```

```html
<del>This was mistaken text</del>
```

--------------------------------

### Define a link reference

Source: https://mistune.lepture.com/en/latest/api.html

Example of link reference syntax used in Markdown.

```markdown
a [link][example]

[example]: https://example.com "Optional title"
```

--------------------------------

### Add TOC Hook

Source: https://mistune.lepture.com/en/latest/api.html

Example of using the TOC hook to save items into the state environment.

```python
import mistune
from mistune.toc import add_toc_hook, render_toc_ul

md = mistune.create_markdown(...)
add_toc_hook(md)

html, state = md.parse(text)
toc_items = state.env['toc_items']
toc_html = render_toc_ul(toc_items)
```

--------------------------------

### Directive Syntax Styles

Source: https://mistune.lepture.com/en/latest/directives.html

Examples of the reStructuredText and fenced style directive syntax.

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

   content text here
```

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

content text here
```
```

--------------------------------

### Define a block quote syntax

Source: https://mistune.lepture.com/en/latest/api.html

Example of the block quote syntax parsed by the BlockParser.

```markdown
> a block quote starts
> with right arrows
```

--------------------------------

### Token structure examples

Source: https://mistune.lepture.com/en/latest/advanced.html

Tokens must contain a 'type' key; 'raw' content is not parsed by the inline parser, while 'text' is.

```python
{'type': 'thematic_break'}  # <hr>
{'type': 'paragraph', 'text': text}
{'type': 'block_code', 'raw': code}
{'type': 'heading', 'text': text, 'attrs': {'level': level}}
```

--------------------------------

### Define a fenced code block

Source: https://mistune.lepture.com/en/latest/api.html

Example of a fenced code block syntax.

```python
```python
def markdown(text):
    return mistune.html(text)
```
```

--------------------------------

### Table of Contents Directive

Source: https://mistune.lepture.com/en/latest/directives.html

Syntax for the TOC directive and an example of its usage in a document.

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

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

.. toc::

# H1 title

## H2 title

# H1 title
```

--------------------------------

### Define block level regex patterns

Source: https://mistune.lepture.com/en/latest/advanced.html

Patterns for block-level elements must start with a caret (^) and use a named group 'math_text'.

```python
# block level pattern MUST startswith ^
BLOCK_MATH_PATTERN = r'^ {0,3}\$\$[ \t]*\n(?P<math_text>.+?)\n\$\$[ \t]*$'

# regex represents:
BLOCK_MATH_PATTERN = (
  r'^ {0,3}'  # line can startswith 0~3 spaces just like other block elements defined in commonmark
  r'\$\$'  # followed by $$
  r'[ \t]*\n'  # this line can contain extra spaces and tabs
  r'(?P<math_text>.+?)'  # this is the math content, MUST use named group
  r'\n\$\$[ \t]*$'  # endswith $$ + extra spaces and tabs
)

# if you want to make the math pattern more strictly, it could be like:
BLOCK_MATH_PATTERN = r'^\$\$\n(?P<math_text>.+?)\n\$\$'
```

--------------------------------

### Nesting Directives with Colon Fences

Source: https://mistune.lepture.com/en/latest/api.html

Use matching lengths of colons to define the start and end of nested directives. It is recommended to use longer markers for outer fences and shorter markers for inner fences.

```markdown
::::{note} Nesting directives
You can nest directives by ensuring the start and end fence matching
the length. For instance, in this example, the admonition is started
with 4 colons, then it should end with 4 colons.

You can nest another admonition with other length of colons except 4.

:::{tip} Longer outermost fence
It would be better that you put longer markers for the outer fence,
and shorter markers for the inner fence. In this example, we put 4
colons outsie, and 3 colons inside.
:::
::::
```

--------------------------------

### Display Mistune CLI Help

Source: https://mistune.lepture.com/en/latest/cli.html

View available command line arguments and options.

```bash
$ python -m mistune -h
```

--------------------------------

### Parse Markdown into AST tokens

Source: https://mistune.lepture.com/en/latest/advanced.html

Demonstrates how to initialize a markdown object with the 'ast' renderer and traverse the resulting token tree.

```python
import mistune

markdown = mistune.create_markdown(renderer='ast')

tokens = markdown(
'''# Title

Subtitle
--------

Hello World!'''
)

stk = list(reversed(tokens))
while stk:
    token = stk.pop()
    print({k:v for k, v in token.items() if k != 'children'})
    if 'children' in token:
        for child in reversed(token['children']):
            stk.append(child)
```

--------------------------------

### Enable Insert Plugin

Source: https://mistune.lepture.com/en/latest/plugins.html

Demonstrates enabling the insert plugin using create_markdown or a custom Markdown instance.

```python
markdown = mistune.create_markdown(plugins=['insert'])
```

```python
from mistune.plugins.formatting import insert

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[insert])
```

--------------------------------

### Initialize a custom Markdown instance

Source: https://mistune.lepture.com/en/latest/api.html

Instantiate the Markdown class with a specific renderer for custom output formatting.

```python
from mistune import HTMLRenderer

md = Markdown(renderer=HTMLRenderer(escape=False))
md('hello **world**')
```

--------------------------------

### Add Plugins to Markdown

Source: https://mistune.lepture.com/en/latest/guide.html

Shows how to enable plugins like strikethrough during instance creation.

```python
markdown = mistune.create_markdown()
markdown('~~s~~')
# ==>
'<p>~~s~~</p>'

markdown = mistune.create_markdown(plugins=['strikethrough'])
markdown('~~s~~')
# ==>
'<p><del>s</del></p>'
```

--------------------------------

### Enable Mark Plugin

Source: https://mistune.lepture.com/en/latest/plugins.html

Demonstrates enabling the mark plugin using create_markdown or a custom Markdown instance.

```python
markdown = mistune.create_markdown(plugins=['mark'])
```

```python
from mistune.plugins.formatting import mark

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[mark])
```

--------------------------------

### Enable Abbr Plugin

Source: https://mistune.lepture.com/en/latest/plugins.html

Demonstrates enabling the abbreviation plugin using create_markdown or a custom Markdown instance.

```python
markdown = mistune.create_markdown(plugins=['abbr'])
```

```python
from mistune.plugins.abbr import abbr

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[abbr])
```

--------------------------------

### Create a Markdown Instance

Source: https://mistune.lepture.com/en/latest/guide.html

Initialize a Markdown instance without plugins, which defaults to escaping HTML tags.

```python
import mistune

markdown = mistune.create_markdown()
```

--------------------------------

### Using RSTRenderer

Source: https://mistune.lepture.com/en/latest/renderers.html

Shows how to initialize the RSTRenderer to convert Markdown text into RestructuredText.

```APIDOC
## RSTRenderer

### Description
The `RSTRenderer` converts markdown input into RestructuredText format.

### Example
```python
from mistune.renderers.rst import RSTRenderer

convert_rst = mistune.create_markdown(renderer=RSTRenderer())
convert_rst(your_markdown_text)
```
```

--------------------------------

### mistune.create_markdown(renderer='ast')

Source: https://mistune.lepture.com/en/latest/advanced.html

Initializes a markdown parser that returns an AST (list of tokens) instead of rendered HTML.

```APIDOC
## mistune.create_markdown(renderer='ast')

### Description
Creates a markdown parser instance configured to output an Abstract Syntax Tree (AST) represented as a list of dictionaries.

### Parameters
- **renderer** (str) - Required - Must be set to 'ast' to enable AST token generation.

### Usage Example
```python
import mistune
markdown = mistune.create_markdown(renderer='ast')
tokens = markdown('Hello World!')
```
```

--------------------------------

### mistune.create_markdown(escape, hard_wrap, renderer, plugins)

Source: https://mistune.lepture.com/en/latest/api.html

Creates a reusable Markdown instance based on specified configuration.

```APIDOC
## mistune.create_markdown(escape=True, hard_wrap=False, renderer='html', plugins=None)

### Description
Create a Markdown instance based on the given condition. This method is used when you want to re-use a Markdown instance.

### Parameters
- **escape** (bool) - Optional - If using html renderer, escape html. Default: True.
- **hard_wrap** (bool) - Optional - Break every new line into <br>. Default: False.
- **renderer** (Literal['html', 'ast'] | BaseRenderer | None) - Optional - renderer instance. Default: 'html'.
- **plugins** (Iterable[str | Plugin] | None) - Optional - List of plugins.

### Example
```python
markdown = create_markdown(escape=False, hard_wrap=True)
markdown('.... your text ...')
```
```

--------------------------------

### Table Plugin Usage

Source: https://mistune.lepture.com/en/latest/plugins.html

Demonstrates various table formatting styles and methods to enable the plugin in a custom Markdown instance.

```markdown
First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell
```

```markdown
| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |
```

```markdown
 Left Header |  Center Header  | Right Header
:----------- | :-------------: | ------------:
 Conent Cell |  Content Cell   | Content Cell


| Left Header |  Center Header  | Right Header  |
| :---------- | :-------------: | ------------: |
| Conent Cell |  Content Cell   | Content Cell  |
```

```python
markdown = mistune.create_markdown(plugins=['table'])
```

```python
from mistune.plugins.table import table

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[table])
```

--------------------------------

### Create a reusable Markdown instance

Source: https://mistune.lepture.com/en/latest/api.html

Use create_markdown to configure a parser instance that can be reused for multiple inputs.

```python
markdown = create_markdown(
    escape=False,
    hard_wrap=True,
)
# re-use markdown function
markdown('.... your text ...')
```

--------------------------------

### Generate Abstract Syntax Tree

Source: https://mistune.lepture.com/en/latest/guide.html

Configure the parser to output an AST instead of HTML by setting the renderer to None or 'ast'.

```python
markdown = mistune.create_markdown(renderer=None)
```

```python
text = 'hello **world**'
markdown(text)
# ==>
[
    {
        'type': 'paragraph',
        'children': [
            {'type': 'text', 'raw': 'hello '},
            {'type': 'strong', 'children': [{'type': 'text', 'raw': 'world'}]}
        ]
    }
]
```

```python
markdown = mistune.create_markdown(renderer='ast')
```

--------------------------------

### mistune.plugins.def_list.def_list

Source: https://mistune.lepture.com/en/latest/api.html

A plugin to support definition lists in Markdown.

```APIDOC
## mistune.plugins.def_list.def_list(md)

### Description
A mistune plugin to support def list, spec defined at https://michelf.ca/projects/php-markdown/extra/#def-list.

### Parameters
- **md** (Markdown) - Required - Markdown instance
```

--------------------------------

### Using MarkdownRenderer

Source: https://mistune.lepture.com/en/latest/renderers.html

Shows how to use the MarkdownRenderer to reformat Markdown text, including how to extend it for plugins.

```APIDOC
## MarkdownRenderer

### Description
The `MarkdownRenderer` is used to reformat Markdown text. When using plugins, you may need to subclass it to define how new tokens are rendered.

### Example
```python
from mistune.renderers.markdown import MarkdownRenderer

class MyRenderer(MarkdownRenderer):
    def strikethrough(self, token, state):
        return '~~' + self.render_children(token, state) + '~~'

format_markdown = mistune.create_markdown(renderer=MyRenderer(), plugins=['strikethrough'])
format_markdown(your_markdown_text)
```
```

--------------------------------

### Enable Math Plugin

Source: https://mistune.lepture.com/en/latest/plugins.html

Methods to enable the math plugin for rendering block and inline math expressions.

```python
markdown = mistune.create_markdown(plugins=['math'])
```

```python
from mistune.plugins.math import math

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[math])
```

--------------------------------

### Customizing HTMLRenderer

Source: https://mistune.lepture.com/en/latest/renderers.html

Demonstrates how to subclass HTMLRenderer to add custom logic for specific syntax, such as inline math.

```APIDOC
## Customizing HTMLRenderer

### Description
Subclass `mistune.HTMLRenderer` to override specific rendering methods. This allows for custom HTML output based on the parsed tokens.

### Example
```python
from mistune import HTMLRenderer

class MyRenderer(HTMLRenderer):
    def codespan(self, text):
        if text.startswith('$') and text.endswith('$'):
            return '<span class="math">' + escape(text) + '</span>'
        return '<code>' + escape(text) + '</code>'

# use customized renderer
markdown = mistune.create_markdown(renderer=MyRenderer())
print(markdown('hi `$a^2=4$`'))
```
```

--------------------------------

### Footnotes Plugin Usage

Source: https://mistune.lepture.com/en/latest/plugins.html

Demonstrates footnote syntax and methods to enable the plugin in a custom Markdown instance.

```markdown
content in paragraph with footnote[^1] markup.

[^1]: footnote explain
```

```python
markdown = mistune.create_markdown(plugins=['footnotes'])
```

```python
from mistune.plugins.footnotes import footnotes

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[footnotes])
```

--------------------------------

### Strikethrough Plugin Usage

Source: https://mistune.lepture.com/en/latest/plugins.html

Demonstrates strikethrough syntax and methods to enable the plugin in a custom Markdown instance.

```markdown
~~here is the content~~
```

```python
markdown = mistune.create_markdown(plugins=['strikethrough'])
```

```python
from mistune.plugins.formatting import strikethrough

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[strikethrough])
```

--------------------------------

### Enable URL plugin

Source: https://mistune.lepture.com/en/latest/plugins.html

Configures the URL plugin to automatically convert raw URLs into links.

```python
markdown = mistune.create_markdown(plugins=['url'])
```

```python
from mistune.plugins.url import url

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[url])
```

--------------------------------

### Enable task_lists plugin

Source: https://mistune.lepture.com/en/latest/plugins.html

Configures the task_lists plugin to support GitHub-style todo items.

```python
markdown = mistune.create_markdown(plugins=['task_lists'])
```

```python
from mistune.plugins.task_lists import task_lists

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[task_lists])
```

--------------------------------

### Include Directive

Source: https://mistune.lepture.com/en/latest/directives.html

Syntax for embedding content from external files.

```markdown
.. include:: hello.md
```

--------------------------------

### Enable def_list plugin

Source: https://mistune.lepture.com/en/latest/plugins.html

Configures the def_list plugin to support HTML definition lists.

```python
markdown = mistune.create_markdown(plugins=['def_list'])
```

```python
from mistune.plugins.def_list import def_list

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[def_list])
```

--------------------------------

### mistune.plugins.formatting.insert

Source: https://mistune.lepture.com/en/latest/api.html

A mistune plugin to add <ins> tag support.

```APIDOC
## mistune.plugins.formatting.insert(md)

### Description
A mistune plugin to add <ins> tag.

### Parameters
- **md** (Markdown) - Required - Markdown instance
```

--------------------------------

### Customize Renderer for Syntax Highlighting

Source: https://mistune.lepture.com/en/latest/guide.html

Extend HTMLRenderer to integrate Pygments for code block syntax highlighting.

```python
import mistune
from pygments import highlight
from pygments.lexers import get_lexer_by_name
from pygments.formatters import html


class HighlightRenderer(mistune.HTMLRenderer):
    def block_code(self, code, info=None):
        if info:
            lexer = get_lexer_by_name(info, stripall=True)
            formatter = html.HtmlFormatter()
            return highlight(code, lexer, formatter)
        return '<pre><code>' + mistune.escape(code) + '</code></pre>'

markdown = mistune.create_markdown(renderer=HighlightRenderer())

print(markdown('```python
assert 1 == 1
```'))
```

--------------------------------

### Enable Ruby Plugin

Source: https://mistune.lepture.com/en/latest/plugins.html

Methods to enable the ruby plugin in a custom Mistune Markdown instance.

```python
markdown = mistune.create_markdown(plugins=['ruby'])
```

```python
from mistune.plugins.ruby import ruby

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[ruby])
```

--------------------------------

### Configure Markdown with Directives

Source: https://mistune.lepture.com/en/latest/directives.html

Wrap directive plugins within FencedDirective or RSTDirective before passing them to the plugins parameter.

```python
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(),
    ]),
])
```

--------------------------------

### mistune.plugins.formatting.strikethrough

Source: https://mistune.lepture.com/en/latest/api.html

A mistune plugin to support strikethrough syntax (~~text~~).

```APIDOC
## mistune.plugins.formatting.strikethrough(md)

### Description
A mistune plugin to support strikethrough. Spec defined by GitHub flavored Markdown.

### Parameters
- **md** (Markdown) - Required - Markdown instance
```

--------------------------------

### create_markdown()

Source: https://mistune.lepture.com/en/latest/api.html

Creates a Markdown parser instance.

```APIDOC
## create_markdown()

### Description
Creates and returns a configured Markdown parser instance.

### Signature
`create_markdown(renderer=None, plugins=None, escape=True)`
```

--------------------------------

### Configure Fenced Directive

Source: https://mistune.lepture.com/en/latest/api.html

How to add the FencedDirective to the Markdown instance.

```python
import mistune
from mistune.directives import FencedDirective, Admonition

md = mistune.create_markdown(plugins=[
    # ...
    FencedDirective([Admonition()]),
])
```

```python
directive = FencedDirective([Admonition()], ':')
```

--------------------------------

### Handle HTML Escaping

Source: https://mistune.lepture.com/en/latest/guide.html

Demonstrates the difference between escaped and non-escaped HTML output.

```python
markdown('<div>hello</div>')
# ==>
'<p>&lt;div&gt;hello&lt;/div&gt;</p>'
```

```python
markdown = mistune.create_markdown(escape=False)
markdown('<div>hello</div>')
# ==>
'<div>hello</div>'
```

--------------------------------

### Configure RST Directive

Source: https://mistune.lepture.com/en/latest/api.html

How to add the RSTDirective to the Markdown instance.

```python
import mistune
from mistune.directives import RSTDirective, Admonition

md = mistune.create_markdown(plugins=[
    # ...
    RSTDirective([Admonition()]),
])
```

--------------------------------

### mistune.plugins.formatting.mark

Source: https://mistune.lepture.com/en/latest/api.html

A mistune plugin to add <mark> tag support.

```APIDOC
## mistune.plugins.formatting.mark(md)

### Description
A mistune plugin to add <mark> tag.

### Parameters
- **md** (Markdown) - Required - Markdown instance
```

--------------------------------

### mistune.plugins.formatting.superscript

Source: https://mistune.lepture.com/en/latest/api.html

A mistune plugin to add <sup> tag support.

```APIDOC
## mistune.plugins.formatting.superscript(md)

### Description
A mistune plugin to add <sup> tag.

### Parameters
- **md** (Markdown) - Required - Markdown instance
```

--------------------------------

### Customize MarkdownRenderer with plugins

Source: https://mistune.lepture.com/en/latest/renderers.html

Extend MarkdownRenderer to support additional syntax provided by plugins.

```python
from mistune.renderers.markdown import MarkdownRenderer

class MyRenderer(MarkdownRenderer):
    def strikethrough(self, token, state):
        return '~~' + self.render_children(token, state) + '~~'

format_markdown = mistune.create_markdown(renderer=MyRenderer(), plugins=['strikethrough'])
format_markdown(your_markdown_text)
```

--------------------------------

### List of HTMLRenderer methods

Source: https://mistune.lepture.com/en/latest/renderers.html

Available renderer functions for HTMLRenderer, including those provided by plugins.

```python
# inline level
text(self, text)
link(self, text, url, title=None)
image(self, alt, url, title=None)
emphasis(self, text)
strong(self, text)
codespan(self, text)
linebreak(self)
softbreak(self)
inline_html(self, html)

# block level
paragraph(self, text)
heading(self, text, level, **attrs)
blank_line(self)
thematic_break(self)
block_text(self, text)
block_code(self, code, info=None)
block_quote(self, text)
block_html(self, html)
block_error(self, html)
list(self, text, ordered, **attrs)
list_item(self, text, **attrs)

# provided by strikethrough plugin
strikethrough(self, text)

# provided by mark plugin
mark(self, text)

# provided by insert plugin
insert(self, text)

# provided by subscript plugin
subscript(self, text)

# provided by abbr plugin
abbr(self, text, title)

# provided by ruby plugin
ruby(self, text, rt)

# provided by task_lists plugin
task_list_item(self, text, checked=False, **attrs)

# provide by table plugin
table(self, text)
table_head(self, text)
table_body(self, text)
table_row(self, text)
table_cell(self, text, align=None, head=False)

# provided by footnotes plugin
footnote_ref(self, key, index)
footnotes(self, text)
footnote_item(self, text, key, index)

# provide by def_list plugin
def_list(self, text)
def_list_head(self, text)
def_list_item(self, text)

# provide by math plugin
block_math(self, text)
inline_math(self, text)
```

--------------------------------

### mistune.plugins.formatting.subscript

Source: https://mistune.lepture.com/en/latest/api.html

A mistune plugin to add <sub> tag support.

```APIDOC
## mistune.plugins.formatting.subscript(md)

### Description
A mistune plugin to add <sub> tag.

### Parameters
- **md** (Markdown) - Required - Markdown instance
```

--------------------------------

### mistune.plugins.task_lists.task_lists

Source: https://mistune.lepture.com/en/latest/api.html

A plugin to support task lists in Markdown, following GitHub flavored Markdown.

```APIDOC
## mistune.plugins.task_lists.task_lists(md)

### Description
A mistune plugin to support task lists. Spec defined by GitHub flavored Markdown.

### Parameters
- **md** (Markdown) - Required - Markdown instance
```

--------------------------------

### mistune.unikey(s)

Source: https://mistune.lepture.com/en/latest/api.html

Generates a unique key for links and footnotes.

```APIDOC
## mistune.unikey(s)

### Parameters
- **s** (str) - Required - The input string.
```

--------------------------------

### Reformat Markdown Files

Source: https://mistune.lepture.com/en/latest/cli.html

Use the markdown renderer to reformat an existing file.

```bash
$ python -m mistune -f README.md -r markdown -o README.md
```

--------------------------------

### Enable Table of Contents

Source: https://mistune.lepture.com/en/latest/directives.html

Register the TableOfContents plugin within the directive handler.

```python
import mistune
from mistune.directives import RSTDirective, TableOfContents

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

--------------------------------

### mistune.plugins.abbr.abbr

Source: https://mistune.lepture.com/en/latest/api.html

A plugin to support abbreviations in Markdown.

```APIDOC
## mistune.plugins.abbr.abbr(md)

### Description
A mistune plugin to support abbreviations, spec defined at https://michelf.ca/projects/php-markdown/extra/#abbr.

### Parameters
- **md** (Markdown) - Required - Markdown instance
```

--------------------------------

### Convert Markdown to HTML

Source: https://mistune.lepture.com/en/latest/cli.html

Default behavior for converting a Markdown file to HTML output.

```bash
$ python -m mistune -f README.md
```

--------------------------------

### Enable Superscript Plugin

Source: https://mistune.lepture.com/en/latest/plugins.html

Methods to enable the superscript plugin for rendering <sup> tags.

```python
markdown = mistune.create_markdown(plugins=['superscript'])
```

```python
from mistune.plugins.formatting import superscript

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[superscript])
```

--------------------------------

### Enable Subscript Plugin

Source: https://mistune.lepture.com/en/latest/plugins.html

Methods to enable the subscript plugin for rendering <sub> tags.

```python
markdown = mistune.create_markdown(plugins=['subscript'])
```

```python
from mistune.plugins.formatting import subscript

renderer = mistune.HTMLRenderer()
markdown = mistune.Markdown(renderer, plugins=[subscript])
```

--------------------------------

### html()

Source: https://mistune.lepture.com/en/latest/api.html

Converts Markdown text to HTML.

```APIDOC
## html()

### Description
A convenience function to convert Markdown text directly into HTML.

### Signature
`html(text, renderer=None, plugins=None)`
```

--------------------------------

### Utilities

Source: https://mistune.lepture.com/en/latest/api.html

Utility functions for string and URL escaping.

```APIDOC
## Utility Functions

### escape(s, quote=True)
Escapes special characters in a string.

### escape_url(link)
Escapes a URL string.

### safe_entity(s)
Ensures entities are safe.

### unikey(s)
Generates a unique key for elements.
```

--------------------------------

### Implement plugin renderers

Source: https://mistune.lepture.com/en/latest/advanced.html

Renderer functions convert tokens into HTML strings based on the token type and attributes.

```python
def render_hr(renderer):
    # token with only type, like:
    # {'type': 'hr'}
    return '<hr>'

def render_math(renderer, text):
    # token with type and (text or raw), e.g.:
    # {'type': 'block_math', 'raw': 'a^b'}
    return '<div class="math">$$' + text + '$$</div>'

def render_link(renderer, text, **attrs):
    # token with type, text or raw, and attrs
    href = attrs['href']
    return f'<a href="{href}">{text}</a>'
```

--------------------------------

### Convert Markdown to HTML

Source: https://mistune.lepture.com/en/latest/guide.html

The simplest way to convert Markdown text to HTML using default settings.

```python
import mistune

mistune.html(YOUR_MARKDOWN_TEXT)
```

--------------------------------

### Use MarkdownRenderer

Source: https://mistune.lepture.com/en/latest/renderers.html

Reformat markdown text using MarkdownRenderer.

```python
from mistune.renderers.markdown import MarkdownRenderer

format_markdown = mistune.create_markdown(renderer=MarkdownRenderer())
format_markdown(your_markdown_text)
```

--------------------------------

### List of MarkdownRenderer methods

Source: https://mistune.lepture.com/en/latest/renderers.html

Default renderer functions available in MarkdownRenderer.

```python
# inline level
text(self, token, state)
link(self, token, state)
image(self, token, state)
emphasis(self, token, state)
strong(self, token, state)
codespan(self, token, state)
linebreak(self, token, state)
softbreak(self, token, state)
inline_html(self, token, state)

# block level
paragraph(self, token, state)
heading(self, token, state)
blank_line(self, token, state)
thematic_break(self, token, state)
block_text(self, token, state)
block_code(self, token, state)
block_quote(self, token, state)
block_html(self, token, state)
block_error(self, token, state)
list(self, token, state)
```

--------------------------------

### AstRenderer Replacement

Source: https://mistune.lepture.com/en/latest/upgrade.html

Use the 'ast' renderer option in create_markdown instead of the removed AstRenderer class.

```python
import mistune

md = mistune.create_markdown(renderer='ast') # or render=None
md('...markdown text...')
```

--------------------------------

### Enable Admonitions

Source: https://mistune.lepture.com/en/latest/directives.html

Register the Admonition plugin within the directive handler.

```python
import mistune
from mistune.directives import Admonition

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

--------------------------------

### Inline element AST token structures

Source: https://mistune.lepture.com/en/latest/advanced.html

Reference for the dictionary structure of inline AST tokens like text, emphasis, and links.

```python
{ 'type': 'linebreak' }
{ 'type': 'softbreak' }
{ 'type': 'text', 'raw': str }
{ 'type': 'emphasis', 'children': list[dict] }
{ 'type': 'strong', 'children': list[dict] }
{ 'type': 'codespan', 'raw': str }
{ 'type': 'inline_html', 'raw': str }

# links and images
#
# 'children' contains elements in the link text section. If you
# write something like [**text**](url), **text** goes to 'children'.
# This behavior is identical for both images and links, but the HTML
# renderer extracts only the text part of children when actually
# putting it into 'alt' attribute (e.g., ![**text**](url) returns
# <img src="url" alt="text">, not <img src="url" alt="**text**">)
#
# for reference links and images (like [text][label], [label], etc.),
# 'ref' and 'label' are also given. Both contain the same content,
# but 'ref' is an uppercase version, while 'label' is case-sensitive.
#
{
    'type': 'image',
    'children': list[dict],    # link text
    'attrs': {
        'url': str,
        'title': str | None    # is None if not given
    },
    'ref': str,     # omitted if not reference links and images
    'label': str    # omitted if not reference links and images
}
{
    'type': 'link',
    'children': list[dict],    # link text
    'attrs': {
        'url': str,
        'title': str | None    # is None if not given
    },
    'ref': str,     # omitted if not reference links and images
    'label': str    # omitted if not reference links and images
}
```

--------------------------------

### mistune.plugins.table.table

Source: https://mistune.lepture.com/en/latest/api.html

A plugin to support tables in Markdown.

```APIDOC
## mistune.plugins.table.table(md)

### Description
A mistune plugin to support table, spec defined at https://michelf.ca/projects/php-markdown/extra/#table.

### Parameters
- **md** (Markdown) - Required - Markdown instance
```

--------------------------------

### Image Directive

Source: https://mistune.lepture.com/en/latest/directives.html

Syntax for inserting images using the fenced style.

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

--------------------------------

### mistune.plugins.math.math

Source: https://mistune.lepture.com/en/latest/api.html

A plugin to support mathematical expressions in Markdown.

```APIDOC
## mistune.plugins.math.math(md)

### Description
A mistune plugin to support math. The syntax is used by many markdown extensions.

### Parameters
- **md** (Markdown) - Required - Markdown instance
```

--------------------------------

### Use Unix PIPE with Mistune

Source: https://mistune.lepture.com/en/latest/cli.html

Pipe text directly into the Mistune command.

```bash
$ echo "foo **bar**" | python -m mistune
```

--------------------------------

### mistune.plugins.ruby.ruby

Source: https://mistune.lepture.com/en/latest/api.html

A plugin to support the <ruby> tag in Markdown.

```APIDOC
## mistune.plugins.ruby.ruby(md)

### Description
A mistune plugin to support <ruby> tag. The syntax is defined at https://lepture.com/en/2022/markdown-ruby-markup.

### Parameters
- **md** (Markdown) - Required - Markdown instance
```

--------------------------------

### Access link reference state

Source: https://mistune.lepture.com/en/latest/api.html

Shows how link references are stored within the state.env dictionary.

```python
state.env['ref_links']['example'] = {
    'url': 'https://example.com',
    'title': "Optional title",
}
```

--------------------------------

### Register a custom plugin

Source: https://mistune.lepture.com/en/latest/advanced.html

The plugin function receives the Markdown instance and registers block/inline parsers and HTML renderers.

```python
def math(md):
    md.block.register('block_math', BLOCK_MATH_PATTERN, parse_block_math, before='list')
    md.inline.register('inline_math', INLINE_MATH_PATTERN, parse_inline_math, before='link')
    if md.renderer and md.renderer.NAME == 'html':
        md.renderer.register('block_math', render_block_math)
        md.renderer.register('inline_math', render_inline_math)
```

--------------------------------

### Block element AST token structures

Source: https://mistune.lepture.com/en/latest/advanced.html

Reference for the dictionary structure of block-level AST tokens including headings, lists, and block quotes.

```python
{ 'type': 'blank_line' }
{ 'type': 'thematic_break' }
{ 'type': 'paragraph', 'children': list[dict] }

# 'block_text' is a special text block that occurs in 'tight' lists.
#
# when a list is tight (i.e., there is no blank line between any list
# items or their children), and if a leaf list item contains only a
# paragraph, that paragraph's 'type' is changed to 'block_text'
# ('children' remains the same).
#
# block_texts are immediately put between <li>...</li>, where paragraphs
# (occurring in 'loose' lists) are rendered like <li><p>...</p></li>.
#
{ 'type': 'block_text', 'children': list[dict] }

# 'style' can be 'atx' or 'setext'
{
    'type': 'heading',
    'children': list[dict],
    'attrs': {'level': int},
    'style': str
}

{ 'type': 'block_quote', 'children': list[dict] }
{ 'type': 'block_html', 'raw': str }
{ 'type': 'block_code', 'raw': str, 'style': 'indent' }

# fenced block code
{
    'type': 'block_code',
    'raw': str,
    'style': 'fenced',
    'marker': str,
    'attrs': {'info': str}    # appears if info string is given
}
```

--------------------------------

### Admonition Syntax

Source: https://mistune.lepture.com/en/latest/directives.html

Syntax for creating admonitions using either reStructuredText or fenced styles.

```markdown
.. warning::

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

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

--------------------------------

### Define AST structures for Mistune plugins

Source: https://mistune.lepture.com/en/latest/advanced.html

Representations of AST node types for various Markdown extensions.

```python
# strikethrough, mark, insert, superscript, and subscript plugin
{ 'type': 'strikethrough', 'children': list[dict] }
{ 'type': 'mark', 'children': list[dict] }
{ 'type': 'insert', 'children': list[dict] }
{ 'type': 'superscript', 'children': list[dict] }
{ 'type': 'subscript', 'children': list[dict] }

# footnotes plugin
{ 'type': 'footnote_ref', 'raw': str, 'attrs': {'index': int} }
{
    'type': 'footnotes',
    'children': [
        {
            'type': 'footnote_item',
            'children': [{'type': 'paragraph', 'children': list[dict]}],
            'attrs': {'key': str, 'index': int}
        },
        ...
    ]
}

# table plugin
{
    'type': 'table',
    'children': [
        {
            'type': 'table_head',
            'children': [
                {
                    'type': 'table_cell',
                    'children': list[dict],
                    'attrs': {
                        # 'align' is 'center', 'left', 'right', or None
                        'align': str | None,
                        'head': True
                    }
                },
                ...
            ]
        },
        {
            'type': 'table_body',
            'children': {
                'type': 'table_row',
                'children': [
                    {
                        'type': 'table_cell',
                        'children': list[dict],
                        'attrs': {
                            # 'align' is 'center', 'left', 'right', or None
                            'align': str | None,
                            'head': False
                        }
                    },
                    ...
                ]
            }
        }
    ]
}

# url plugin does not add new elements
# (it uses 'link' element just like normal links)

# task_lists plugin
#
# task_list_item appears in the same contexts as list_item.
#
{
    'type': 'task_list_item',
    'children': list[dict],
    'attrs': {'checked': bool}
}

# def_list plugin
#
# similar to regular lists, sole paragraphs in def_list_items are
# converted to 'block_texts' if the definition list is tight.
#
{
    'type': 'def_list',
    'children': [
        { 'type': 'def_list_head', 'children': list[dict] },
        { 'type': 'def_list_item', 'children': list[dict] },
        ...
    ]
}

# abbr plugin
{
    'type': 'abbr',
    'children': [{'type': 'text', 'raw': str}],
    'attrs': {'title': str}
}

# math plugin
{ 'type': 'block_math', 'raw': str }
{ 'type': 'inline_math', 'raw': str }

# ruby plugin
{ 'type': 'ruby', 'raw': str, 'attrs': {'rt': str} }

# spoiler plugin
{ 'type': 'block_spoiler', 'children': list[dict] }
{ 'type': 'inline_spoiler', 'children': list[dict] }
```

--------------------------------

### List element AST token structure

Source: https://mistune.lepture.com/en/latest/advanced.html

Reference for the dictionary structure of list AST tokens.

```python
{
    'type': 'list',
    'children': [{'type': 'list_item', 'children': list[dict]}, ...],
    'tight': bool,    # whether the list is 'tight' or 'loose'
    'bullet': str,    # list marker character
    'attrs': {
        'depth': int,
        'ordered': bool,    # whether the list is ordered or unordered
        'start': int    # appears if the list is ordered and start != 1
    }
}
```

--------------------------------

### Implement block parsing function

Source: https://mistune.lepture.com/en/latest/advanced.html

Parsers extract content from the regex match and append a token to the state.

```python
def parse_block_math(block, m, state):
    text = m.group('math_text')
    # use ``state.append_token`` to save parsed block math token
    state.append_token({'type': 'block_math', 'raw': text})
    # return the end position of parsed text
    # since python doesn't count ``$``, we have to +1
    # if the pattern is not ended with `$`, we can't +1
    return m.end() + 1
```

--------------------------------

### Convert Markdown to RestructuredText

Source: https://mistune.lepture.com/en/latest/cli.html

Use the -r rst flag to specify the RestructuredText renderer.

```bash
$ python -m mistune -f README.md -r rst
```

--------------------------------

### mistune.html(text)

Source: https://mistune.lepture.com/en/latest/api.html

Converts markdown formatted text into HTML without escaping.

```APIDOC
## mistune.html(text)

### Description
Turn markdown text into HTML without escaping.

### Parameters
- **text** (str) - Required - markdown formatted text

### Example
```python
text = '**hello** <span>world</span>'
mistune.html(text)
# => '<p><strong>hello</strong> <span>world</span></p>'
```
```

--------------------------------

### Plugin Method Signature Changes

Source: https://mistune.lepture.com/en/latest/upgrade.html

Updated parameter signatures for plugin methods in v3.

```python
-    abbr(self, key, definition)
+    abbr(self, text: str, title: str)

-    task_list_item(self, text: str, level: int, checked: bool)
+    task_list_item(self, text: str, checked: bool)
```

--------------------------------

### HTMLRenderer Method Signature Changes

Source: https://mistune.lepture.com/en/latest/upgrade.html

Updated parameter signatures for custom HTML renderer methods in v3.

```python
-    link(self, link, text=None, title=None)
+    link(self, text, url, title=None)

-    image(self, src, alt="", title=None)
+    image(self, text, url, title=None)

-    heading(self, text, level)
+    heading(self, text, level, **attrs)

-    list(self, text, ordered, level, start=None)
+    list(self, text, ordered, **attrs)

-    list_item(self, text, level)
+    list_item(self, text)

-    table_cell(self, text, align=None, is_head=False)
+    table_cell(self, text, align=None, head=False)
```

--------------------------------

### Admonition Types

Source: https://mistune.lepture.com/en/latest/directives.html

List of supported admonition directive names.

```text
attention  caution  danger  error
hint  important  note  tip  warning
```

--------------------------------

### Use RSTRenderer

Source: https://mistune.lepture.com/en/latest/renderers.html

Convert markdown text to RestructuredText using RSTRenderer.

```python
from mistune.renderers.rst import RSTRenderer

convert_rst = mistune.create_markdown(renderer=RSTRenderer())
convert_rst(your_markdown_text)
```
Tokens:
Raw