Separate Markdown parsing in HTML to separate extension (#859)

Move Markdown parsing from the extra extension to a separate
extension called md_in_html.

3 files changed, 147 insertions, 129 deletions

diff --git a/docs/extensions/extra.md b/docs/extensions/extra.md
index cf30e56..3316b7a 100644
--- a/docs/extensions/extra.md
+++ b/docs/extensions/extra.md
@@ -15,6 +15,7 @@ The supported extensions include:
 * [Fenced Code Blocks](fenced_code_blocks.md)
 * [Footnotes](footnotes.md)
 * [Tables](tables.md)
+* [Markdown in HTML](md_in_html.md)
 
 See each individual extension for syntax documentation. Extra and all its
 supported extensions are included in the standard Markdown library.
@@ -35,113 +36,3 @@ therefore, not part of Python-Markdown Extra. If you really would
 like Extra to include additional extensions, we suggest creating
 your own clone of Extra under a different name
 (see the [Extension API](api.md)).
-
-### Markdown Inside HTML Blocks
-
-Unlike the other Extra features, this feature is built into the markdown core and
-is turned on when `markdown.extensions.extra` is enabled.
-
-The content of any raw HTML block element can be Markdown-formatted simply by
-adding a `markdown` attribute to the opening tag. The markdown attribute will be
-stripped from the output, but all other attributes will be preserved.
-
-If the markdown value is set to `1` (recommended) or any value other than `span`
-or `block`, the default behavior will be executed: `p`,`h[1-6]`,`li`,`dd`,`dt`,
-`td`,`th`,`legend`, and `address` elements skip block parsing while others do not.
-If the default is overridden by a value of `span`, *block parsing will be skipped*
-regardless of tag. If the default is overridden by a value of `block`,
-*block parsing will occur* regardless of tag.
-
-#### Simple Example:
-
-```md
-This is *true* markdown text.
-
-<div markdown="1">
-This is *true* markdown text.
-</div>
-```
-
-#### Result:
-
-```html
-<p>This is <em>true</em> markdown text.</p>
-<div>
-<p>This is <em>true</em> markdown text.</p>
-</div>
-```
-
-### Nested Markdown Inside HTML Blocks
-
-Nested elements are more sensitive and must be used cautiously. To avoid
-unexpected results:
-
-* Only nest elements within block mode elements.
-* Follow the closing tag of inner elements with a blank line.
-* Only have one level of nesting.
-
-#### Complex Example:
-
-```md
-<div markdown="1" name="Example">
-
-The text of the `Example` element.
-
-<div markdown="1" name="DefaultBlockMode">
-This text gets wrapped in `p` tags.
-</div>
-
-The tail of the `DefaultBlockMode` subelement.
-
-<p markdown="1" name="DefaultSpanMode">
-This text *is not* wrapped in additional `p` tags.
-</p>
-
-The tail of the `DefaultSpanMode` subelement.
-
-<div markdown="span" name="SpanModeOverride">
-This `div` block is not wrapped in paragraph tags.
-Note: Subelements are not required to have tail text.
-</div>
-
-<p markdown="block" name="BlockModeOverride">
-This `p` block *is* foolishly wrapped in further paragraph tags.
-</p>
-
-The tail of the `BlockModeOverride` subelement.
-
-<div name="RawHtml">
-Raw HTML blocks may also be nested.
-</div>
-
-</div>
-
-This text is after the markdown in HTML.
-```
-
-#### Complex Result:
-
-```html
-<div name="Example">
-<p>The text of the <code>Example</code> element.</p>
-<div name="DefaultBlockMode">
-<p>This text gets wrapped in <code>p</code> tags.</p>
-</div>
-<p>The tail of the <code>DefaultBlockMode</code> subelement.</p>
-<p name="DefaultSpanMode">
-This text <em>is not</em> wrapped in additional <code>p</code> tags.</p>
-<p>The tail of the <code>DefaultSpanMode</code> subelement.</p>
-<div name="SpanModeOverride">
-This <code>div</code> block is not wrapped in paragraph tags.
-Note: Subelements are not required to have tail text.</div>
-<p name="BlockModeOverride">
-<p>This <code>p</code> block <em>is</em> foolishly wrapped in further paragraph tags.</p>
-</p>
-<p>The tail of the <code>BlockModeOverride</code> subelement.</p>
-<div name="RawHtml">
-Raw HTML blocks may also be nested.
-</div>
-
-</div>
-<p>This text is after the markdown in HTML.</p>
-```
diff --git a/docs/extensions/index.md b/docs/extensions/index.md
index 26b117b..bbdf248 100644
--- a/docs/extensions/index.md
+++ b/docs/extensions/index.md
@@ -35,25 +35,26 @@ maintained here and all bug reports should be made to the project. If you
 have a typical install of Python-Markdown, these extensions are already
 available to you using the "Entry Point" name listed in the second column below.
 
-Extension                            | Entry Point    | Dot Notation
------------------------------------- | -------------- | ------------
-[Extra]                              | `extra`        | `markdown.extensions.extra`
-&nbsp; &nbsp; [Abbreviations][]      | `abbr`         | `markdown.extensions.abbr`
-&nbsp; &nbsp; [Attribute Lists][]    | `attr_list`    | `markdown.extensions.attr_list`
-&nbsp; &nbsp; [Definition Lists][]   | `def_list`     | `markdown.extensions.def_list`
-&nbsp; &nbsp; [Fenced Code Blocks][] | `fenced_code`  | `markdown.extensions.fenced_code`
-&nbsp; &nbsp; [Footnotes][]          | `footnotes`    | `markdown.extensions.footnotes`
-&nbsp; &nbsp; [Tables][]             | `tables`       | `markdown.extensions.tables`
-[Admonition][]                       | `admonition`   | `markdown.extensions.admonition`
-[CodeHilite][]                       | `codehilite`   | `markdown.extensions.codehilite`
-[Legacy Attributes][]                | `legacy_attr`  | `markdown.extensions.legacy_attr`
-[Legacy Emphasis][]                  | `legacy_em`    | `markdown.extensions.legacy_em`
-[Meta-Data]                          | `meta`         | `markdown.extensions.meta`
-[New Line to Break]                  | `nl2br`        | `markdown.extensions.nl2br`
-[Sane Lists]                         | `sane_lists`   | `markdown.extensions.sane_lists`
-[SmartyPants]                        | `smarty`       | `markdown.extensions.smarty`
-[Table of Contents]                  | `toc`          | `markdown.extensions.toc`
-[WikiLinks]                          | `wikilinks`    | `markdown.extensions.wikilinks`
+Extension                          | Entry Point    | Dot Notation
+---------------------------------- | -------------- | ------------
+[Extra]                            | `extra`        | `markdown.extensions.extra`
+&nbsp; &nbsp; [Abbreviations]      | `abbr`         | `markdown.extensions.abbr`
+&nbsp; &nbsp; [Attribute Lists]    | `attr_list`    | `markdown.extensions.attr_list`
+&nbsp; &nbsp; [Definition Lists]   | `def_list`     | `markdown.extensions.def_list`
+&nbsp; &nbsp; [Fenced Code Blocks] | `fenced_code`  | `markdown.extensions.fenced_code`
+&nbsp; &nbsp; [Footnotes]          | `footnotes`    | `markdown.extensions.footnotes`
+&nbsp; &nbsp; [Markdown in HTML]   | `md_in_html`   | `markdown.extensions.md_in_html`
+&nbsp; &nbsp; [Tables]             | `tables`       | `markdown.extensions.tables`
+[Admonition]                       | `admonition`   | `markdown.extensions.admonition`
+[CodeHilite]                       | `codehilite`   | `markdown.extensions.codehilite`
+[Legacy Attributes]                | `legacy_attr`  | `markdown.extensions.legacy_attr`
+[Legacy Emphasis]                  | `legacy_em`    | `markdown.extensions.legacy_em`
+[Meta-Data]                        | `meta`         | `markdown.extensions.meta`
+[New Line to Break]                | `nl2br`        | `markdown.extensions.nl2br`
+[Sane Lists]                       | `sane_lists`   | `markdown.extensions.sane_lists`
+[SmartyPants]                      | `smarty`       | `markdown.extensions.smarty`
+[Table of Contents]                | `toc`          | `markdown.extensions.toc`
+[WikiLinks]                        | `wikilinks`    | `markdown.extensions.wikilinks`
 
 [Extra]: extra.md
 [Abbreviations]: abbreviations.md
@@ -68,6 +69,7 @@ Extension                            | Entry Point    | Dot Notation
 [Legacy Emphasis]: legacy_em.md
 [Meta-Data]: meta_data.md
 [New Line to Break]: nl2br.md
+[Markdown in HTML]: md_in_html.md
 [Sane Lists]: sane_lists.md
 [SmartyPants]: smarty.md
 [Table of Contents]: toc.md
diff --git a/docs/extensions/md_in_html.md b/docs/extensions/md_in_html.md
new file mode 100644
index 0000000..b57197b
--- /dev/null
+++ b/docs/extensions/md_in_html.md
@@ -0,0 +1,125 @@
+title: Markdown in HTML Extension
+
+# Markdown in HTML
+
+## Summary
+
+An extensions that parses Markdown inside of HTML tags.
+
+## Usage
+
+From the Python interpreter:
+
+```pycon
+>>> import markdown
+>>> html = markdown.markdown(text, extensions=['md_in_html'])
+```
+
+Unlike the other Extra features, this feature is built into the markdown core and
+is turned on when `markdown.extensions.extra` or `markdown.extensions.md_in_html`
+is enabled.
+
+The content of any raw HTML block element can be Markdown-formatted simply by
+adding a `markdown` attribute to the opening tag. The markdown attribute will be
+stripped from the output, but all other attributes will be preserved.
+
+If the markdown value is set to `1` (recommended) or any value other than `span`
+or `block`, the default behavior will be executed: `p`,`h[1-6]`,`li`,`dd`,`dt`,
+`td`,`th`,`legend`, and `address` elements skip block parsing while others do not.
+If the default is overridden by a value of `span`, *block parsing will be skipped*
+regardless of tag. If the default is overridden by a value of `block`,
+*block parsing will occur* regardless of tag.
+
+#### Simple Example:
+
+```md
+This is *true* markdown text.
+
+<div markdown="1">
+This is *true* markdown text.
+</div>
+```
+
+#### Result:
+
+```html
+<p>This is <em>true</em> markdown text.</p>
+<div>
+<p>This is <em>true</em> markdown text.</p>
+</div>
+```
+
+### Nested Markdown Inside HTML Blocks
+
+Nested elements are more sensitive and must be used cautiously. To avoid
+unexpected results:
+
+* Only nest elements within block mode elements.
+* Follow the closing tag of inner elements with a blank line.
+* Only have one level of nesting.
+
+#### Complex Example:
+
+```md
+<div markdown="1" name="Example">
+
+The text of the `Example` element.
+
+<div markdown="1" name="DefaultBlockMode">
+This text gets wrapped in `p` tags.
+</div>
+
+The tail of the `DefaultBlockMode` subelement.
+
+<p markdown="1" name="DefaultSpanMode">
+This text *is not* wrapped in additional `p` tags.
+</p>
+
+The tail of the `DefaultSpanMode` subelement.
+
+<div markdown="span" name="SpanModeOverride">
+This `div` block is not wrapped in paragraph tags.
+Note: Subelements are not required to have tail text.
+</div>
+
+<p markdown="block" name="BlockModeOverride">
+This `p` block *is* foolishly wrapped in further paragraph tags.
+</p>
+
+The tail of the `BlockModeOverride` subelement.
+
+<div name="RawHtml">
+Raw HTML blocks may also be nested.
+</div>
+
+</div>
+
+This text is after the markdown in HTML.
+```
+
+#### Complex Result:
+
+```html
+<div name="Example">
+<p>The text of the <code>Example</code> element.</p>
+<div name="DefaultBlockMode">
+<p>This text gets wrapped in <code>p</code> tags.</p>
+</div>
+<p>The tail of the <code>DefaultBlockMode</code> subelement.</p>
+<p name="DefaultSpanMode">
+This text <em>is not</em> wrapped in additional <code>p</code> tags.</p>
+<p>The tail of the <code>DefaultSpanMode</code> subelement.</p>
+<div name="SpanModeOverride">
+This <code>div</code> block is not wrapped in paragraph tags.
+Note: Subelements are not required to have tail text.</div>
+<p name="BlockModeOverride">
+<p>This <code>p</code> block <em>is</em> foolishly wrapped in further paragraph tags.</p>
+</p>
+<p>The tail of the <code>BlockModeOverride</code> subelement.</p>
+<div name="RawHtml">
+Raw HTML blocks may also be nested.
+</div>
+
+</div>
+<p>This text is after the markdown in HTML.</p>
+```