# Raw HTML blocks proposals -- comments wanted

**URL:** <https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983>\
**Category:** Spec\
**Created:** [December 26, 2014, 9:19pm UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983 "2014-12-26T21:19:38Z")\
**Posts on this page:** 20\
**Page:** 3

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [March 3, 2015, 7:15pm UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/42 "2015-03-03T19:15:47Z")

</div>

> [@codinghorror](#):
>
> I think that’s a pretty big drawback. Like… really big. As @vitaly noted even cut and paste HTML like
> 
> \<iframe width=“560” height=“315” src=“[//www.youtube.com/embed/tjuBV4NbCng](https://www.youtube.com/embed/tjuBV4NbCng)” frameborder=“0” allowfullscreen\>\</iframe\>
> 
> … will stop working.

Yes, this is true even on the hybrid proposal I suggest above, because `iframe`, like `del`, can be both “flow content” (block level) or “phrase content” (span level). On the other hand, the fact that `iframe` can be ~~flow~~ phrase content means that there are legitimate uses for an iframe inside a paragraph, and possibly even at the beginning of a paragraph. So, I think, we shouldn’t make it impossible for authors to write these things. The current proposal allows you to use an `iframe` either inside a paragraph (even at the beginning) or as an independent block. The author can choose, it’s just a matter of whether you put the opening tag on a line by itself.

In general, I’m against creating “blind spots” – things that are _impossible_ to express in CommonMark.

> [@codinghorror](#):
>
> I want to go back to first principles on this: is HTML itself changing so fast that hard-coding the list of tags is really all that bad?
> 
> In this complete list of the new tags in HTML 5, I count 28 new tags, things like \<article\> and \<progress\>. (I can’t find a similar list for HTML 5.1, maybe because the spec is still evolving.)
> 
> I understand the problem with span vs block level, but that problem has always existed with Markdown, has it not?

Yes, and it has been solved in a variety of ad hoc ways (or in some cases not solved). The hope was that we could do better, and have a principled solution.

As @vitaly notes, HTML5 already allows custom tags, and there have been [requests from users to deal with them better](https://github.com/jgm/CommonMark/issues/239).

In addition, we might consider the possibility that someone would target, say, DocBook or another XML format. (Creating a DocBook renderer for cmark or commonmark.js would be quite easy.) In that case they might like the ability to use raw DocBook on occasion. The present proposal supports this kind of thing.

---

<div class="post-metadata">

**Author:** ![lu\_zero](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/lu_zero/32/557_2.png) [@lu\_zero](https://talk.commonmark.org/u/lu_zero)\
**Post date:** [March 4, 2015, 12:34am UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/43 "2015-03-04T00:34:19Z")

</div>

let’s provide something to mark verbatim areas so it can be used in a generic way.

---

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [March 4, 2015, 1:38am UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/44 "2015-03-04T01:38:23Z")

</div>

+++ lu\_zero [Mar 04 15 00:44]:

> [1]lu\_zero  
> March 4
> 
> let’s provide something to mark verbatim areas so it can be used in a  
> generic way.

By “verbatim areas” I assume you mean stuff that should pass through to the output format unchanged, rather than things that should be escaped and put into pre or code tags. Assuming that’s right, I’m _really_ sympathetic. I think that this would have been a better design for Markdown – instead of allowing HTML to be plonked down anywhere, have some kind of explicit marker for it, at least for verbatim HTML blocks.

The problem is backwards compatibility. Unless we want to break with original Markdown in a more thoroughgoing way, we need to support HTML blocks without explicit markers.

---

<div class="post-metadata">

**Author:** ![codinghorror](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/codinghorror/32/2_2.png) [@codinghorror](https://talk.commonmark.org/u/codinghorror)\
**Post date:** [March 4, 2015, 5:38am UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/45 "2015-03-04T05:38:44Z")

</div>

I understand it is a hard problem with no easy answers @jgm but the “must place block tag on a line by itself” rule smacks of the “use two spaces at the end of a line for a line break” decision in original Markdown – it is impossible to discover without knowing the secret in advance. I just worry that it is very hard to figure this out and we are adding more secret handshakes.

It is a tiny bit better in that, unlike spaces, the tag is at least not invisible in the raw markup, I suppose.

And, to be fair, all the options seem bad in different ways here so there is no way to pick a best solution; all have tradeoffs.

---

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [March 4, 2015, 7:20am UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/46 "2015-03-04T07:20:00Z")

</div>

+++ codinghorror [Mar 04 15 05:48]:

> I understand it is a hard problem with no easy answers @jgm but the “must place block tag on a line by itself” rule smacks of the “use two spaces at the end of a line for a line break” decision in original Markdown – it is impossible to discover without knowing the secret in advance. I just worry that it is very hard to figure this out and we are adding more secret handshakes.

With the hybrid proposal, this would only matter for those few tags that can occur either as “flow content” or as “phrase content.” With, say, a `<div>` tag you wouldn’t need a single tag on a line. Perhaps that just makes it more confusing, since you need to know which tags behave this way. But that is already the case in, e.g. PHP Markdown, Markdown.pl, and showdown, where `<del>` behaves differently if you put it on a line by itself. [http://johnmacfarlane.net/babelmark2/?normalize=1&text=\<del\> hi \<%2Fdel\> \<del\>hi\<%2Fdel\>](http://johnmacfarlane.net/babelmark2/?normalize=1&text=%3Cdel%3E%0Ahi%0A%3C%2Fdel%3E%0A%0A%3Cdel%3Ehi%3C%2Fdel%3E%0A)

---

<div class="post-metadata">

**Author:** ![codinghorror](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/codinghorror/32/2_2.png) [@codinghorror](https://talk.commonmark.org/u/codinghorror)\
**Post date:** [March 7, 2015, 12:34am UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/47 "2015-03-07T00:34:04Z")

</div>

As long as it mirrors the current behaviors in some way, I am for it.

I just don’t want to add any more “mystery meat” than we currently have in Markdown by design™

---

<div class="post-metadata">

**Author:** ![zzzzBov](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/zzzzbov/32/218_2.png) [@zzzzBov](https://talk.commonmark.org/u/zzzzBov)\
**Post date:** [March 13, 2015, 7:21pm UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/48 "2015-03-13T19:21:19Z")

</div>

What about namespaced attributes for markdown directives

```
<div md:ignore=true>
    this will *not* have markdown parsed
</div>
<div md:ignore=false>
    this **will** have markdown parsed
</div>

```

could turn into

```
<div>
    this will *not* have markdown parsed
</div>
<div>
    <p>this <strong>will</strong> have markdown parsed</p>
</div>

```

Doing something like that would allow the markdown spec provide reasonable defaults, but allow users to override elements on an as-needed basis.

---

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [March 13, 2015, 10:13pm UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/49 "2015-03-13T22:13:14Z")

</div>

+++ zzzzBov [Mar 13 15 19:31]:

> [1]zzzzBov  
> March 13
> 
> ```
> What about namespaced attributes for markdown directives
> 
> ```
> 
> this will \*not\* have markdown parsed 
> 
> this \*\*will\*\* have markdown parsed 
> 
> ```
> could turn into
> 
> ```
> 
> this will \*not\* have markdown parsed 
> 
> this **will** have markdown parsed
> 
> ```
> Doing something like that would allow the markdown spec provide
> reasonable defaults, but allow users to override elements on an
> as-needed basis.
> 
> ```

This is what some implementations (e.g. PHP Markdown Extra) currently do. (The default is not to interpret the contents of block-level elements as Markdown, but you can override this by setting the attribute markdown=1. There are some ugly complexities about whether the attribute should propagate down to child elements.)

It isn’t needed with the current CommonMark spec, since you can get the same distinction by doing either:

```
<div>
this will *not* have markdown parsed
</div>

```

or

```
<div>

this *will* have markdown parsed.

</div>

```

---

<div class="post-metadata">

**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\
**Post date:** [May 30, 2015, 12:42am UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/50 "2015-05-30T00:42:34Z")

</div>

Any hope to see progress on this topic?

---

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [May 31, 2015, 8:00pm UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/51 "2015-05-31T20:00:07Z")

</div>

+++ vitaly [May 30 15 00:52]:

> Any hope to see progress on this topic?

Yes, this is a high priority for this summer. Soon, I hope.

---

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [June 8, 2015, 7:45pm UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/52 "2015-06-08T19:45:46Z")

</div>

Summary of the proposal I think is best, after discussion:

A **partial HTML tag** is any initial portion of a full HTML tag, as defined in the spec, split at a word boundary.

An **HTML block tag** is an HTML tag whose tag name is **not** in the following list: `a abbr area audio b bdi bdo br button canvas cite code command datalist del dfn em embed i iframe img input ins kbd keygen label map mark math meter noscript object output progress q ruby s samp script select small span strong sub sup svg textarea time u var video wbr text`. (These are tags that can be used in “phrasing content,” according to the HTML5 spec. Some of them can _also_ be used for block-level content.)

An **HTML block** starts with either (a) any HTML tag or partial tag on a line by itself, or (b) a complete HTML block tag followed by other content on the same line.

If the opening tag name is `<script`, `<style`, `<pre`, or `<!--`, the HTML block includes lines up to and including the first line containing a matching end tag, or the end of the document, if no such line is encountered.

Otherwise the block includes lines up to (and not including) the first blank line, or to the end of the document, if no blank line is encountered.

Example:

```auto
<del>x</del>

```

becomes

```auto
<p><del>x</del></p>

```

Why? `del` can be phrasing content, so in order to start an HTML block it needs to be on a line by itself. So,

```auto
<del>
x
</del>

```

becomes

```auto
<del>
x
</del>

```

If we leave a blank line after the `<del>` and before and after `</del>`, the contents will be interpreted as Markdown:

```auto
<del>

x

</del>

```

becomes

```auto
<del>
<p>x</p>
</del>

```

When we have tags that can’t be phrasing content, we can include several on one line, which should help with backwards compatibility:

```auto
<table><tr><td>
x
</td></tr></table>

```

is parsed as a raw HTML block.

---

<div class="post-metadata">

**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\
**Post date:** [June 9, 2015, 10:16am UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/53 "2015-06-09T10:16:07Z")

</div>

> [@jgm](#):
>
> An HTML block tag is an HTML tag whose tag name is not in the following list: a abbr area audio b bdi bdo br button canvas cite code command datalist del dfn em embed i iframe img input ins kbd keygen label map mark math meter noscript object output progress q ruby s samp script select small span strong sub sup svg textarea time u var video wbr text. (These are tags that can be used in “phrasing content,” according to the HTML5 spec. Some of them can also be used for block-level content.)

Can some custom tags be considered phrasing content? Since these tags are not in the white list, can they be used as part of a paragraph?

E.g.

`<my-custom-element>My custom element text</my-custom-element> followed by other paragraph text.`

Would this output

```auto
<p><my-custom-element>My custom element text</my-custom-element> followed by other paragraph text.</p>

```

or this?

```auto
<my-custom-element>My custom element text</my-custom-element> followed by other paragraph text.

```

---

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [June 9, 2015, 6:46pm UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/54 "2015-06-09T18:46:50Z")

</div>

@chrisalley - quite right, we should have a whitelist of tags that  
can only be block-level (= all the defined tags minus the ones in  
my list). That will allow custom tags to be used either block or  
inline.

Block tags =  
address  
article  
aside  
base  
basefont  
blockquote  
body  
caption  
center  
col  
colgroup  
dd  
details  
dialog  
dir  
div  
dl  
dt  
fieldset  
figcaption  
figure  
footer  
form  
frame  
frameset  
h1  
head  
header  
hr  
html  
legend  
li  
link  
main  
menu  
menuitem  
meta  
nav  
noframes  
ol  
optgroup  
option  
p  
param  
pre  
section  
source  
title  
summary  
table  
tbody  
td  
tfoot  
th  
thead  
title  
tr  
track  
ul

---

<div class="post-metadata">

**Author:** ![balpha](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/balpha/32/18_2.png) [@balpha](https://talk.commonmark.org/u/balpha)\
**Post date:** [June 15, 2015, 12:30pm UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/55 "2015-06-15T12:30:56Z")

</div>

Testing CommonMark on a bunch of Stack Exchange questions and answers, I’m seeing quite a few instances of this:

```markdown
Foo bar

<hr>
Quux [plonk](http://example.org)

```

where the HTML tag (under both the current and the proposed rules) prevents the subsequent Markdown from being interpreted.

Can we exclude the [void elements](http://www.w3.org/TR/html-markup/syntax.html#void-elements) from ever opening an HTML block?

---

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [June 15, 2015, 7:20pm UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/56 "2015-06-15T19:20:55Z")

</div>

If we just excluded void elements from opening an HTML block, then we’d still get the wrong parse, since if `<hr>` is interpreted as inline HTML, we’ll get everything in a paragraph:

`<p><hr> Quux etc.</p>`

One solution would be: if the line starts with a void element, then treat just this one line as an HTML block.

But of course, this would break on

```markdown
<hr><div>
My *html* block
</div>

```

I’m not terriby worried about this, because this doesn’t satisfy Gruber’s own official criterion for an HTML block, and the proposed fix would produce reasonable results here (the word “html” would be emphasized, but the tags would be okay.

---

<div class="post-metadata">

**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\
**Post date:** [June 15, 2015, 8:04pm UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/57 "2015-06-15T20:04:13Z")

</div>

Not very useful. That will work only if void element is not followed by another html tag - will not solve all possible cases. Partial solutions are evil.

IMHO, it’s more simple to patch such rare patterns in db.

---

<div class="post-metadata">

**Author:** ![balpha](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/balpha/32/18_2.png) [@balpha](https://talk.commonmark.org/u/balpha)\
**Post date:** [June 16, 2015, 5:51am UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/58 "2015-06-16T05:51:54Z")

</div>

> [@jgm](#):
>
> One solution would be: if the line starts with a void element, then treat just this one line as an HTML block.

Yes, that’s what I meant.

> [@vitaly](#):
>
> will not solve all possible cases. Partial solutions are evil.

Everything about HTML tag handling in CommonMark (or Markdown in general) is a partial solution that does not solve all possible cases.

---

<div class="post-metadata">

**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\
**Post date:** [June 16, 2015, 6:43pm UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/59 "2015-06-16T18:43:17Z")

</div>

> [@balpha](#):
>
> Everything about HTML tag handling in CommonMark (or Markdown in general) is a partial solution that does not solve all possible cases.

Spec solves problem how to allow HTML without need to create full weight html parser. I see no reason to make spec more complex than needed. Example with `<hr>` looks strange, because hr is already covered in md syntax. May be there are better examples or usage stat proofs, but i haven’t seen those.

---

<div class="post-metadata">

**Author:** ![vitaly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/vitaly/32/396_2.png) [@vitaly](https://talk.commonmark.org/u/vitaly)\
**Post date:** [June 25, 2015, 8:04am UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/60 "2015-06-25T08:04:48Z")

</div>

@jgm do we have any pending problems with latest html proposal? I don’t see any:

- handling empty lines in multiline comments - OK
- html5 custom tags (with dashes) - seems OK

Would be nice to see this update in spec. In any case, it’s _much_ better than existing.

---

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [June 26, 2015, 10:58pm UTC](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983/61 "2015-06-26T22:58:06Z")

</div>

@vitaly I’m planning to do this in the next few weeks.

[Previous page](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983.md?page=2)

[Next page](https://talk.commonmark.org/t/raw-html-blocks-proposals-comments-wanted/983.md?page=4)