Add HTML-in-md page

jpsca · jpsca · commit cf93dc02f716 · 2026-02-02T18:57:18.000-05:00
diff --git a/docs/content/markdown/html.md b/docs/content/markdown/html.md
@@ -3,118 +3,31 @@ title: HTML
 icon: icons/html.svg
 ---
 
-Markdown is a subset of HTML; anything that cannot be expressed in Markdown can always be expressed directly with raw HTML.
-HTML is much less readable than plain Markdown, so you should only use it as a last resort.
+Markdown is a subset of HTML; anything that cannot be expressed in Markdown can always be expressed directly with raw HTML. HTML is much less readable than plain Markdown, so you should only use it as a last resort.
 
-Use blank lines to separate block-level HTML elements, like `<div>`, `<table>`, `<p>`, etc., from the surrounding content.
-
-## Markdown in HTML
-
-By default, Markdown ignores any content within a raw HTML block-level element. However, you can enable parsing of the content inside a raw HTML block-level element as Markdown by including a `markdown` attribute on the opening tag. The markdown attribute will be stripped from the output, while all other attributes will be preserved.
-
-The markdown attribute can be assigned one of three values: "1", "block", or "span".
-
-### `markdown="1"`
-
-When the markdown attribute is set to "1", the parser will use the default behavior for that specific tag.
-
-The following tags have block behavior by default: `article`, `aside`, `blockquote`, `body`, `colgroup`, `details`, `div`, `dl`, `fieldset`, `figcaption`, `figure`, `footer`, `form`, `group`, `header`, `hgroup`, `hr`, `iframe`, `main`, `map`, `menu`, `nav`, `noscript`, `object`, `ol`, `output`, `progress`, `section`, `table`, `tbody`, `tfoot`, `thead`, `tr`, `ul`, and `video`.
-
-/// example | Default "block" markdown parsing
-
-```md
-<div markdown="1">
-This is a *Markdown* Paragraph.
-</div>
-```
-
-renders as:
-
-```html
-<div>
-<p>This is a <em>Markdown</em> Paragraph.</p>
-</div>
-```
+The content inside HTML tags is treated differently depending if the HTML tags are inline or blocks.
 
-///
+## Inline syntax
 
-The following tags have span behavior by default: `address`, `dd`, `dt`, `h[1-6]`, `legend`, `li`, `p`, `td`, and `th`.
-
-/// example | Default "span" markdown parsing
+Only inline syntax, such as links, strong, emphasis, etc., is rendered as regular Markdown code. For example:
 
 ```md
-<p markdown="1">
-This is not a *Markdown* Paragraph.
-</p>
+So <span class="special">**many** _books_</span>. So little time.
 ```
 
 renders as:
 
 ```html
-<p>
-This is not a <em>Markdown</em> Paragraph.
-</p>
+<p>So <span class="special"><strong>>many<strong>
+  <em>books</em></span>. So little time.<p>
 ```
 
-///
-
-Note how an implicit paragraph was added in the first example but not in the second.
-
-### `markdown="block"`
-
-When the markdown attribute is set to "block", the parser will force block behavior on the contents of the element, as long as it is one of the block or span tags.
+## Block syntax
 
-The content of a block element is parsed into block-level content. In other words, the text is rendered as paragraphs, headers, lists, blockquotes, etc. Any inline syntax within those elements is processed as well.
-
-:::: div example
-**Example: Forced "block" markdown parsing**
+For any block-level element everything inside that element is ignored, including child elements. For example:
 
 ```md
-<section markdown="block">
-# A header.
-
-A *Markdown* paragraph.
-
-* A list item.
-* A second list item.
-
-</section>
-```
-
-renders as:
-
-```html
-<section>
-<h1>A header.</h1>
-<p>A <em>Markdown</em> paragraph.</p>
-<ul>
-<li>A list item.</li>
-<li>A second list item.</li>
-</ul>
-</section>
-```
-
-::::
-
-::: warning
-Forcing elements to be parsed as `block` elements when they are not by default could result in invalid HTML.
-
-For example, one could force a `<p>` element to be nested within another `<p>` element. In most cases, it is
-recommended to use the default behavior of `markdown="1"`.
-:::
-
-
-### `markdown="span"`
-
-When the markdown attribute is set to "span", the parser will force span behavior on the contents of the element, as long as it is one of the block or span tags.
-
-The content of a span element is not parsed into block-level content. In other words, the content will not be rendered as paragraphs, headers, etc. Only inline syntax will be rendered, such as links, strong, emphasis, etc.
-
-:::: div example
-**Example: Forced "span" markdown parsing**
-
-```md
-<div markdown="span">
+<div>
 # *Not* a header
 </div>
 ```
@@ -127,53 +40,30 @@ renders as:
 </div>
 ```
 
-::::
-
-
-## Nesting
+Use blank lines to separate block-level HTML elements, like `<div>`, `<table>`, `<p>`, etc., from the surrounding content.
 
-When nesting multiple levels of raw HTML elements, a markdown attribute must be defined for each block-level element. For any block-level element that does not have a markdown attribute, everything inside that element is ignored, including child elements with markdown attributes.
+### Indentation
 
-:::: div example
-**Example: Markdown in nested HTML
+Block-level HTML elements must have no indentation at all. Unless they are inside a list elementy, in which case must be indented only the same as the list text.
 
 ```md
-<article id="my-article" markdown="1">
-# Article Title
-
-A Markdown paragraph.
-
-<section id="section-1" markdown="1">
-## Section 1 Title
-
-<p>Custom raw **HTML** which gets ignored.</p>
+<p class="a">Not indented</p>
 
-</section>
-
-<section id="section-2" markdown="1">
-## Section 2 Title
-
-<p markdown="1">**Markdown** content.</p>
-
-</section>
-
-</article>
+- lorem
+- ipsum
+  <p class="b">barely indented</p>
+- sit amet
 ```
 
-renders as:
+renders (approximately) as:
 
 ```html
-<article id="my-article">
-<h1>Article Title</h1>
-<p>A Markdown paragraph.</p>
-<section id="section-1">
-<h2>Section 1 Title</h2>
-<p>Custom raw **HTML** which gets ignored.</p>
-</section>
-<section id="section-2">
-<h2>Section 2 Title</h2>
-<p><strong>Markdown</strong> content.</p>
-</section>
-</article>
+<p class="a">Not indented</p>
+<ul>
+  <li>lorem</li>
+  <li>ipsum
+    <p class="b">barely indented</p>
+  </li>
+  <li>sit amet</li>
+</ul>
 ```
-::::
diff --git a/docs/docs.py b/docs/docs.py
@@ -30,7 +30,7 @@
             "markdown/code.md",
             "markdown/tables.md",
             "markdown/attributes.md",
-            # "markdown/html.md",
+            "markdown/html.md",
         ],
     },
     {
diff --git a/tests/test_mdjx.py b/tests/test_mdjx.py
@@ -16,7 +16,7 @@
 # <Test>This **is** a test</Test>
 
 # <Test class="hi">Hello world</Test>
-# """.strip())
+# """.rstrip())
 
 #     docs = Docs(tmp_root, pages=["test.md"])
 #     docs.catalog.add_folder(tmp_root / "comp")
@@ -27,7 +27,7 @@
 # <h2 >This **is** a test</h2>
 
 # <h2 class="hi">Hello world</h2>
-# """.strip()
+# """
 #     result = (tmp_root / "build" / "docs" / "test" / "index.html").read_text()
 #     print(result)
 #     assert result == expected
@@ -44,7 +44,7 @@
 #   "Test": "test.jinja"
 # ---
 # <Test markdown="span" class="hi">This **is** a test</Test>
-# """.strip())
+# """.rstrip())
 
 #     docs = Docs(tmp_root, pages=["test.md"])
 #     docs.catalog.add_folder(tmp_root / "comp")
@@ -53,7 +53,7 @@
 #     expected = """
 # <h1>Test Page</h1>
 # <h2 class="hi">This <strong>is</strong> a test</h2>
-# """.strip()
+# """
 #     result = (tmp_root / "build" / "docs" / "test" / "index.html").read_text()
 #     print(result)
 #     assert result == expected
@@ -70,7 +70,7 @@
 #   "Test": "test.jinja"
 # ---
 # <Test markdown="1" class="hi">This **is** a test</Test>
-# """.strip())
+# """.rstrip())
 
 #     docs = Docs(tmp_root, pages=["test.md"])
 #     docs.catalog.add_folder(tmp_root / "comp")
@@ -79,7 +79,7 @@
 #     expected = """
 # <h1>Test Page</h1>
 # <h2 class="hi"><p>This <strong>is</strong> a test</p></h2>
-# """.strip()
+# """
 #     result = (tmp_root / "build" / "docs" / "test" / "index.html").read_text()
 #     print(result)
 #     assert result == expected
@@ -96,7 +96,7 @@
 #   "Test": "test.jinja"
 # ---
 # <Test class="hi" />
-# """.strip())
+# """.rstrip())
 
 #     docs = Docs(tmp_root, pages=["test.md"])
 #     docs.catalog.add_folder(tmp_root / "comp")
@@ -105,7 +105,7 @@
 #     expected = """
 # <h1>Test Page</h1>
 # <h2 class="hi">Hello</h2>
-# """.strip()
+# """
 #     result = (tmp_root / "build" / "docs" / "test" / "index.html").read_text()
 #     print(result)
 #     assert result == expected
@@ -127,7 +127,7 @@
 # <Test />
 # <Test></Test>
 # ```
-# """.strip())
+# """.rstrip())
 
 #     docs = Docs(tmp_root, pages=["test.md"])
 #     docs.catalog.add_folder(tmp_root / "comp")
@@ -140,7 +140,7 @@
 # <div class="language-text highlight"><pre><code>&lt;Test /&gt;
 # &lt;Test&gt;&lt;/Test&gt;
 # </code></pre></div>
-# """.strip()
+# """
 #     result = (tmp_root / "build" / "docs" / "test" / "index.html").read_text()
 #     print(result)
 #     assert result == expected
@@ -163,7 +163,7 @@
 # {% if test %}Nor this {%- endif %}
 
 # {# or this #}
-# """.strip())
+# """.rstrip())
 
 #     docs = Docs(tmp_root, pages=["test.md"])
 #     docs.catalog.add_folder(tmp_root / "comp")
@@ -176,7 +176,7 @@
 # <p>{{ this is not a variable }}</p>
 # <p>{% if test %}Nor this {%- endif %}</p>
 # <p>{# or this #}</p>
-# """.strip()
+# """
 #     result = (tmp_root / "build" / "docs" / "test" / "index.html").read_text()
 #     print(result)
 #     assert result == expected

Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,7 @@`
`30`	`30`	`"markdown/code.md",`
`31`	`31`	`"markdown/tables.md",`
`32`	`32`	`"markdown/attributes.md",`
`33`		`- # "markdown/html.md",`
	`33`	`+ "markdown/html.md",`
`34`	`34`	`],`
`35`	`35`	`},`
`36`	`36`	`{`