Debian Codegraph @

docs/extensions/md_in_html.md

raw
1 title: Markdown in HTML Extension
2
3 # Markdown in HTML
4
5 ## Summary
6
7 An extension that parses Markdown inside of HTML tags.
8
9 ## Syntax
10
11 By default, Markdown ignores any content within a raw HTML block-level element. With the `md-in-html` extension
12 enabled, the content of a raw HTML block-level element can be parsed as Markdown by including a `markdown` attribute
13 on the opening tag. The `markdown` attribute will be stripped from the output, while all other attributes will be
14 preserved.
15
16 The `markdown` attribute can be assigned one of three values: [`"1"`](#markdown1), [`"block"`](#block), or [`"span"`](#span).
17
18 !!! note
19
20 The expressions "block-level" and "span-level" as used in this document refer to an element's designation
21 according to the HTML specification. Whereas the `"span"` and `"block"` values assigned to the `markdown`
22 attribute refer to the Markdown parser's behavior.
23
24 ### `markdown="1"` { #markdown1 }
25
26 When the `markdown` attribute is set to `"1"`, then the parser will use the default behavior for that specific tag.
27
28 The following tags have the `block` behavior by default: `article`, `aside`, `blockquote`, `body`, `colgroup`,
29 `details`, `div`, `dl`, `fieldset`, `figcaption`, `figure`, `footer`, `form`, `group`, `header`, `hgroup`, `hr`,
30 `iframe`, `main`, `map`, `menu`, `nav`, `noscript`, `object`, `ol`, `output`, `progress`, `section`, `table`,
31 `tbody`, `tfoot`, `thead`, `tr`, `ul` and `video`.
32
33 For example, the following:
34
35 ```
36 <div markdown="1">
37 This is a *Markdown* Paragraph.
38 </div>
39 ```
40
41 ... is rendered as:
42
43 ``` html
44 <div>
45 <p>This is a <em>Markdown</em> Paragraph.</p>
46 </div>
47 ```
48
49 The following tags have the `span` behavior by default: `address`, `dd`, `dt`, `h[1-6]`, `legend`, `li`, `p`, `td`,
50 and `th`.
51
52 For example, the following:
53
54 ```
55 <p markdown="1">
56 This is not a *Markdown* Paragraph.
57 </p>
58 ```
59
60 ... is rendered as:
61
62 ``` html
63 <p>
64 This is not a <em>Markdown</em> Paragraph.
65 </p>
66 ```
67
68 ### `markdown="block"` { #block }
69
70 When the `markdown` attribute is set to `"block"`, then the parser will force the `block` behavior on the contents of
71 the element so long as it is one of the `block` or `span` tags.
72
73 The content of a `block` element is parsed into block-level content. In other words, the text is rendered as
74 paragraphs, headers, lists, blockquotes, etc. Any inline syntax within those elements is processed as well.
75
76 For example, the following:
77
78 ```
79 <section markdown="block">
80 # A header.
81
82 A *Markdown* paragraph.
83
84 * A list item.
85 * A second list item.
86
87 </section>
88 ```
89
90 ... is rendered as:
91
92 ``` html
93 <section>
94 <h1>A header.</h1>
95 <p>A <em>Markdown</em> paragraph.</p>
96 <ul>
97 <li>A list item.</li>
98 <li>A second list item.</li>
99 </ul>
100 </section>
101 ```
102
103 !!! warning
104
105 Forcing elements to be parsed as `block` elements when they are not by default could result in invalid HTML.
106 For example, one could force a `<p>` element to be nested within another `<p>` element. In most cases it is
107 recommended to use the default behavior of `markdown="1"`. Explicitly setting `markdown="block"` should be
108 reserved for advanced users who understand the HTML specification and how browsers parse and render HTML.
109
110 ### `markdown="span"` { #span }
111
112 When the `markdown` attribute is set to `"span"`, then the parser will force the `span` behavior on the contents
113 of the element so long as it is one of the `block` or `span` tags.
114
115 The content of a `span` element is not parsed into block-level content. In other words, the content will not be
116 rendered as paragraphs, headers, etc. Only inline syntax will be rendered, such as links, strong, emphasis, etc.
117
118 For example, the following:
119
120 ```
121 <div markdown="span">
122 # *Not* a header
123 </div>
124 ```
125
126 ... is rendered as:
127
128 ``` html
129 <div>
130 # <em>Not</em> a header
131 </div>
132 ```
133
134 ### Ignored Elements
135
136 The following tags are always ignored, regardless of any `markdown` attribute: `canvas`, `math`, `option`, `pre`,
137 `script`, `style`, and `textarea`. All other raw HTML tags are treated as span-level tags and are not affected by this
138 extension.
139
140 ### Nesting
141
142 When nesting multiple levels of raw HTML elements, a `markdown` attribute must be defined for each block-level
143 element. For any block-level element which does not have a `markdown` attribute, everything inside that element is
144 ignored, including child elements with `markdown` attributes.
145
146 For example, the following:
147
148 ```
149 <article id="my-article" markdown="1">
150 # Article Title
151
152 A Markdown paragraph.
153
154 <section id="section-1" markdown="1">
155 ## Section 1 Title
156
157 <p>Custom raw **HTML** which gets ignored.</p>
158
159 </section>
160
161 <section id="section-2" markdown="1">
162 ## Section 2 Title
163
164 <p markdown="1">**Markdown** content.</p>
165
166 </section>
167
168 </article>
169 ```
170
171 ... is rendered as:
172
173 ```html
174 <article id="my-article">
175 <h1>Article Title</h1>
176 <p>A Markdown paragraph.</p>
177 <section id="section-1">
178 <h2>Section 1 Title</h2>
179 <p>Custom raw **HTML** which gets ignored.</p>
180 </section>
181 <section id="section-2">
182 <h2>Section 2 Title</h2>
183 <p><strong>Markdown</strong> content.</p>
184 </section>
185 </article>
186 ```
187
188 When the value of an element's `markdown` attribute is more permissive that its parent, then the parent's stricter
189 behavior is enforced. For example, a `block` element nested within a `span` element will be parsed using the `span`
190 behavior. However, if the value of an element's `markdown` attribute is the same as, or more restrictive than, its
191 parent, the the child element's behavior is observed. For example, a `block` element may contain either `block`
192 elements or `span` elements as children and each element will be parsed using the specified behavior.
193
194 ### Tag Normalization
195
196 While the default behavior is for Markdown to not alter raw HTML, as this extension is parsing the content of raw HTML elements, it will do some normalization of the tags of block-level elements. For example, the following raw HTML:
197
198 ```
199 <div markdown="1">
200 <p markdown="1">A Markdown paragraph with *no* closing tag.
201 <p>A raw paragraph with *no* closing tag.
202 </div>
203 ```
204
205 ... is rendered as:
206
207 ``` html
208 <div>
209 <p>A Markdown paragraph with <em>no</em> closing tag.
210 </p>
211 <p>A raw paragraph with *no* closing tag.
212 </p>
213 </div>
214 ```
215
216 Notice that the parser properly recognizes that an unclosed `<p>` tag ends when another `<p>` tag begins or when the
217 parent element ends. In both cases, a closing `</p>` was added to the end of the element, regardless of whether a
218 `markdown` attribute was assigned to the element.
219
220 To avoid any normalization, an element must not be a descendant of any block-level element which has a `markdown`
221 attribute defined.
222
223 !!! warning
224
225 The normalization behavior is only documented here so that document authors are not surprised when their carefully
226 crafted raw HTML is altered by Markdown. This extension should not be relied on to normalize and generate valid
227 HTML. For the best results, always include valid raw HTML (with both opening and closing tags) in your Markdown
228 documents.
229
230 ## Usage
231
232 From the Python interpreter:
233
234 ``` pycon
235 >>> import markdown
236 >>> html = markdown.markdown(text, extensions=['md_in_html'])
237 ```