Horizontal rule triggers Heading 2 #365

New Issue

claunia · 2026-01-29T14:35:00Z

claunia commented

2026-01-29 14:35:00 +00:00

Originally created by @rpc-scandinavia on GitHub (May 17, 2020).

When converting MarkDown to HTML.
This:

Line one.
---
Line two.

Becomes:

<h2>Line one.</h2>
<p>Line two.</p>

Instead of:

<p>Line one.</p>
<hr />
<p>Line two.</p>

Finally this works:

Line one.
***
Line two.

I understand that with the H1 and H2 with = and -, the = or - should be the same length as the heading, like this:

This is a heading
=================

But this is not
---

YOU
---

I do not know whether or not the last one, should be a heading 2 or a horizontal rule. Both have alternatives like ## and ***.

Originally created by @rpc-scandinavia on GitHub (May 17, 2020). When converting MarkDown to HTML. This: ``` Line one. --- Line two. ``` Becomes: ``` <h2>Line one.</h2> <p>Line two.</p> ``` Instead of: ``` <p>Line one.</p> <hr /> <p>Line two.</p> ``` Finally this works: ``` Line one. *** Line two. ``` I understand that with the H1 and H2 with = and -, the = or - should be the same length as the heading, like this: ``` This is a heading ================= But this is not --- YOU --- ``` I do not know whether or not the last one, should be a heading 2 or a horizontal rule. Both have alternatives like ## and ***.

claunia added the question invalid labels 2026-01-29 14:35:00 +00:00

claunia closed this issue

2026-01-29 14:35:01 +00:00

claunia commented

2026-01-29 14:35:02 +00:00

@MihaZupan commented on GitHub (May 17, 2020):

This behavior is as defined in the CommonMark spec, see Example 29.

See comparison between different parsers.

The solution is to add blank lines if you use ---, or to use a different character for the thematic break (_ or *).

Line one.

---

Line two.

or

Line one.
___
Line two.

turns into

<p>Line one.</p>
<hr>
<p>Line two.</p>

I understand that with the H1 and H2 with = and -, the = or - should be the same length as the heading

It can be of any length as per example 53.

@MihaZupan commented on GitHub (May 17, 2020): This behavior is as defined in the CommonMark spec, see [Example 29](https://spec.commonmark.org/0.29/#example-29). See [comparison between different parsers](https://babelmark.github.io/?text=Line+one.%0A---%0ALine+two.%0A%0ALine+one.%0A%0A---%0A%0ALine+two.). The solution is to add blank lines if you use `---`, or to use a different character for the thematic break (`_` or `*`). ```md Line one. --- Line two. ``` or ```md Line one. ___ Line two. ``` turns into ```html <p>Line one.</p> <hr> <p>Line two.</p> ``` > I understand that with the H1 and H2 with = and -, the = or - should be the same length as the heading It can be of any length as per [example 53](https://spec.commonmark.org/0.29/#example-53).

claunia commented

2026-01-29 14:35:03 +00:00

@rpc-scandinavia commented on GitHub (May 17, 2020):

On this page they show that --- is a horizontal rule:

https://commonmark.org/help/

@rpc-scandinavia commented on GitHub (May 17, 2020): On this page they show that --- is a horizontal rule: [https://commonmark.org/help/](https://commonmark.org/help/)

claunia commented

2026-01-29 14:35:03 +00:00

@rpc-scandinavia commented on GitHub (May 17, 2020):

And:

Markdig is a fast, powerful, CommonMark compliant, extensible Markdown processor for .NET.

Written on this GitHub page.

@rpc-scandinavia commented on GitHub (May 17, 2020): And: > Markdig is a fast, powerful, CommonMark compliant, extensible Markdown processor for .NET. Written on this GitHub page.

claunia commented

2026-01-29 14:35:03 +00:00

@MihaZupan commented on GitHub (May 17, 2020):

See example 29 I linked above, it explains exactly this case.

If a line of dashes that meets the above conditions for being a thematic break could also be interpreted as the underline of a setext heading, the interpretation as a setext heading takes precedence. Thus, for example, this is a setext heading, not a paragraph followed by a thematic break:

Foo
---
bar

<h2>Foo</h2>
<p>bar</p>

On this page they show that --- is a horizontal rule:
https://commonmark.org/help/

And even in the example they add that extra blank line

@MihaZupan commented on GitHub (May 17, 2020): See example 29 I linked above, it explains exactly this case. > If a line of dashes that meets the above conditions for being a thematic break could also be interpreted as the underline of a setext heading, the interpretation as a setext heading takes precedence. Thus, for example, this is a setext heading, not a paragraph followed by a thematic break: ```md Foo --- bar ``` ```html <h2>Foo</h2> <p>bar</p> ``` > On this page they show that --- is a horizontal rule: https://commonmark.org/help/ And even in the example they add that extra blank line

claunia commented

2026-01-29 14:35:03 +00:00

@MihaZupan commented on GitHub (May 17, 2020):

And:
Markdig is a fast, powerful, CommonMark compliant, extensible Markdown processor for .NET.
Written on this GitHub page.

I agree with that statement 100%

@MihaZupan commented on GitHub (May 17, 2020): > And: > Markdig is a fast, powerful, CommonMark compliant, extensible Markdown processor for .NET. > Written on this GitHub page. I agree with that statement 100%

claunia commented

2026-01-29 14:35:04 +00:00

@rpc-scandinavia commented on GitHub (May 17, 2020):

Example 29 shows that:

you
---
yes

Should become H2, but NOT:

Fire
---
Truck

Only when the upper line is 3 characters long.

@rpc-scandinavia commented on GitHub (May 17, 2020): Example 29 shows that: ``` you --- yes ``` Should become H2, but NOT: ``` Fire --- Truck ``` Only when the upper line is 3 characters long.

claunia commented

2026-01-29 14:35:04 +00:00

@xoofx commented on GitHub (May 17, 2020):

See babelmark for how it behaves

As @MihaZupan said, it is per the spec. All CommonMark implementations are following that.

@xoofx commented on GitHub (May 17, 2020): See babelmark for how [it behaves](https://babelmark.github.io/?text=you%0A---%0Ayes%0A%0AFire%0A---%0ATruck) As @MihaZupan said, it is per the spec. All CommonMark implementations are following that.

claunia commented

2026-01-29 14:35:04 +00:00

@rpc-scandinavia commented on GitHub (May 17, 2020):

Example 53 is the opposite of what their HELP page shows, it says that "---" and "***" is a horizontal rule. It also shows that the headers use the same length for the text and the "-"s or "="s.

@rpc-scandinavia commented on GitHub (May 17, 2020): Example 53 is the opposite of what their HELP page shows, it says that "---" and "***" is a horizontal rule. It also shows that the headers use the same length for the text and the "-"s or "="s.

claunia commented

2026-01-29 14:35:05 +00:00

@xoofx commented on GitHub (May 17, 2020):

Example 53 is the opposite of what their HELP page shows, it says that "---" and "***" is a horizontal rule. It also shows that the headers use the same length for the text and the "-"s or "="s.

It's not invalid. You are focusing on a corner case. If you want a --- to be interpreted as an horizontal line, it would require a separating blank line before the preceding paragraph.

CommonMark/Markdown is full of corner cases, that's why there is a CommonMark spec for that.

@xoofx commented on GitHub (May 17, 2020): > Example 53 is the opposite of what their HELP page shows, it says that "---" and "***" is a horizontal rule. It also shows that the headers use the same length for the text and the "-"s or "="s. It's not invalid. You are focusing on a corner case. If you want a `---` to be interpreted as an horizontal line, it would require a separating blank line before the preceding paragraph. CommonMark/Markdown is full of corner cases, that's why there is a CommonMark spec for that.

claunia commented

2026-01-29 14:35:05 +00:00

@MihaZupan commented on GitHub (May 17, 2020):

It's an example reference table to demonstrate language features. It can't include all specific corner cases of the language - that's why a specification document exists, and it is the spec that is the source of truth as to how parsers should behave.

It also shows that the headers use the same length for the text and the "-"s or "="s.

That is how it's usually written because it looks better in monospaced font - that does not mean it's required.

@MihaZupan commented on GitHub (May 17, 2020): It's an example reference table to demonstrate language features. It can't include all specific corner cases of the language - that's why a specification document exists, and it is the spec that is the source of truth as to how parsers should behave. > It also shows that the headers use the same length for the text and the "-"s or "="s. That is how it's usually written because it looks better in monospaced font - that does not mean it's required.

claunia commented

2026-01-29 14:35:05 +00:00

@rpc-scandinavia commented on GitHub (May 17, 2020):

I understand all that when I read the spec, that there are corner cases and behaviour decisions has been made - but the help page was the first place I looked when trying to test my program, and I expect that is what users do too.

@rpc-scandinavia commented on GitHub (May 17, 2020): I understand all that when I read the spec, that there are corner cases and behaviour decisions has been made - but the help page was the first place I looked when trying to test my program, and I expect that is what users do too.

claunia commented

2026-01-29 14:35:06 +00:00

@rpc-scandinavia commented on GitHub (May 17, 2020):

Anyway, I just thought there was an error.
Thank you for the great software.

@rpc-scandinavia commented on GitHub (May 17, 2020): Anyway, I just thought there was an error. Thank you for the great software.

claunia commented

2026-01-29 14:35:06 +00:00

@xoofx commented on GitHub (May 17, 2020):

I understand all that when I read the spec, that there are corner cases and behaviour decisions has been made - but the help page was the first place I looked when trying to test my program, and I expect that is what users do too.

Yeah, it's not really their fault. A help page is not supposed to start to enter corner cases.
And frankly, Markdown is full of that, that's why sometimes users are confused and also why it's so difficult to get a parser right.

@xoofx commented on GitHub (May 17, 2020): > I understand all that when I read the spec, that there are corner cases and behaviour decisions has been made - but the help page was the first place I looked when trying to test my program, and I expect that is what users do too. Yeah, it's not really their fault. A help page is not supposed to start to enter corner cases. And frankly, Markdown is full of that, that's why sometimes users are confused and also why it's so difficult to get a parser right.

claunia referenced this issue

2026-01-29 14:48:47 +00:00

[PR #431] [MERGED] Escape URLs scheme #1026

claunia referenced this issue

2026-01-29 14:48:50 +00:00

[PR #431] Escape URLs scheme #1031

Sign in to join this conversation.