1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
.. _renderers:
Renderers
=========
Mistune has several built-in renderers, including:
- :class:`mistune.renderers.html.HTMLRenderer`
- :class:`mistune.renderers.markdown.MarkdownRenderer`
- :class:`mistune.renderers.rst.RSTRenderer`
You're welcome to contribute more renderers.
Customize HTMLRenderer
----------------------
You can customize HTML output with your own renderers. Take an example, we're going
to add an inline math syntax like below:
.. code::
`$a^2=4$`
To render this syntax, we can create a subclass of ``mistune.HTMLRenderer``:
.. code-block:: 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$`'))
Available methods
~~~~~~~~~~~~~~~~~
Here is a a list of available renderer functions for ``HTMLRenderer``, including methods on plugins:
.. code-block::
# 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)
RestructuredText Renderer
-------------------------
The ``RSTRenderer`` can be used to convert markdown text to RestructuredText.
.. code-block:: python
from mistune.renderers.rst import RSTRenderer
convert_rst = mistune.create_markdown(renderer=RSTRenderer())
convert_rst(your_markdown_text)
Markdown Renderer
-----------------
The ``MarkdownRenderer`` can be used to reformat your Markdown text.
.. code-block:: python
from mistune.renderers.markdown import MarkdownRenderer
format_markdown = mistune.create_markdown(renderer=MarkdownRenderer())
format_markdown(your_markdown_text)
With plugins
~~~~~~~~~~~~
The original ``MarkdownRenderer`` can **ONLY** render the basic Markdown syntax.
If you're using plugins, you would need to customize ``MarkdownRenderer`` with
extra render methods. Take an example, you are going to add the :ref:`strikethrough`
plugin:
.. code-block:: 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=MarkdownRenderer(), plugins=['strikethrough'])
format_markdown(your_markdown_text)
Default methods
~~~~~~~~~~~~~~~
Here is a a list of default renderer functions of ``MarkdownRenderer``:
.. code-block::
# 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)
|
