Horizontal rules as (hierarchical) section breaks etc

Extensions
1

When Markdown was devised in 2004, there was no HTML5 and hence no <section> element type, just <hr>. Should a modern implementation (per user-select option or extension) treat one or all “horizontal line” markup as section breaks? Should it introduce new repeated character lines instead, e.g. ====, ####, .... or ''''?

# First chapter

----

# Second chapter

<section>
<h1>First chapter</h1>
</section><section>
<h1>Second chapter</h1>
</section>

Paged media

Slides

For slide-based presentations made with Markdown, horizontal lines (mostly dashed ones ---) have already been used to imply slide breaks: Remark, Slidify, IO Slides, Swipe, Landslide, Deckset, Pandoc, Biggie, but MarkdownPresenter uses a line with only an exclamation mark in it and Keydown even adds an English keyword !SLIDE. Slides are a good example of paged media, print-outs are another one.

Print

Leanpub and its offspring Markua, both tailored for traditional page-based publishing, support page breaks and book sections ‘frontmatter’, ‘mainmatter’ and ‘backmatter’ (like LaTeX’s ‘book’ document class). They do so with English keywords enclosed in curly braces as sole line content. Since Markua is still in the making, should Commonmark recommend a different approach?

{frontmatter}

TOC, imprint, preface etc.

{mainmatter}

Chapters

{pagebreak}

Sections etc.

{backmatter} 

Appendices, glossary, index, etc.

TOC, imprint, preface etc.

====

Chapters

----

Sections etc.

====

Appendices, glossary, index, etc.

Alternative markup

I have always fancied the simple scissors emoticon / ASCII art which could be used for page breaks unambiguously.

----8<----

<hr class="page">

hr.page {page-break-after: always; height: 0;}

Meta data

YAML markup blocks, mostly at the top of the document, use --- as fences (and sometimes ... as an ending fence), e.g. in Pandoc.

---
Title: Document title
---
Content

<html><head>
<title>Document title</title>
</head><body>
<p>Content</p>
</body></html>

Hierarchy

If horizontal lines were interpreted as section breaks, should different kinds of line characters imply different hierarchic levels of sections, e.g. *** ends a section at the current heading level, --- ends a top-level section?

# h1

top section

## h2

lower section

 * * *

top section again

<section><h1>h1</h1>
<p>top section</p>
  <section><h2>h2</h2>
  <p>lower section</p>
  </section>
<p>top section again</p>
</section>

PS: There is related Spec discussion at Horizontal Rule or Thematic Break?.

2

Related discussion: Explicit section not possible?

1 Like
3

Rethinking possible syntax harmonization while documenting existing extensions, I had an idea for a systematic approach regarding the Hierarchy section in my initial post from three years ago, which is a problem only dealt with in the initial post in the thread @chrisalley linked to.

Consideration

Markdown and Commonmark do not use the concept of empty paragraphs, empty headings or empty emphasized spans, but as part of a mental model they make some sense.

An underlined heading consists of the underline and one or more lines before it that would otherwise be parsed as a paragraph. If this paragraph is empty, the underline is considered a thematic break instead. This line of thinking works only for --- and longer uninterrupted lines of hyphens right now. It becomes either a relative and generic empty heading or an absolute second-level empty heading.

The empty emphases in foo ____ bar and foo **** bar are rendered as their verbatim markers, but if they are the sole content of a paragraph they become indistinguishable from thematic breaks. In vanilla Commonmark, the only difference between underscore _ and asterisk * emphasis is in intra-word markup, but if we consider a sensible extension that aligns asterisks with more semantic (HTML) markup <em> and <strong>, and underscores with more presentational markup <i>/<u> and <b>, then a line of asterisks associates more with an explicit section break </section><section> and a line of underscores sounds more like a traditional horizontal rule <hr>.

Conclusion (= TL;DR)

  • ----: empty heading section break – continue in new anonymous sibling section
  • ****: structural section break – continue in parent section afterwards
  • ____: visual hr break
# Foo            # Foo            # Foo
Bar              Bar              Bar
## Baz           ## Baz           ## Baz
----             ****             ____
Quuz             Quuz             Quuz
.
<section>        <section>        <section>
 <h1>Foo</h1>     <h1>Foo</h1>     <h1>Foo</h1>
 <p>Bar</p>       <p>Bar</p>       <p>Bar</p>
 <section>        <section>        <section>
  <h2>Baz</h2>     <h2>Baz</h2>     <h2>Baz</h2>
 </section>       </section>
 <section>                          <hr/>
  <p>Quuz</p>      <p>Quuz</p>      <p>Quuz</p>
 </section>                        </section>
</section>       </section>       </section>

Related Topic

Fenced Flowerbox headings, especially at the second level, can reuse thematic breaks.

# Parent      ## Sibling    ### Nephew
---------     ---------     ---------
Flowerbox     Flowerbox     Flowerbox
---------     ---------     ---------

This falls back gracefully if the parser disposes all empty sections after it has finished parsing the document.

Explicit Section Breaks

First pass:

                                               <section>
<section>              <section>                <section>
<h1>Parent</h1>        <h2>Sibling</h2>         <h3>Nephew</h3>
</section><section>    </section><section>      </section><section>
 <section>             </section><section>      </section>
                                               </section><section>
 <h2>Flowerbox</h2>    <h2>Flowerbox</h2>      <h2>Flowerbox</h2>
 </section>            </section>              </section>
</section>

Final pass:

                                               <section>
<section>              <section>                <section>
<h1>Parent</h1>        <h2>Sibling</h2>         <h3>Nephew</h3>
</section><section>    </section>               </section>
 <section>             <section>               </section><section>
 <h2>Flowerbox</h2>    <h2>Flowerbox</h2>      <h2>Flowerbox</h2>
 </section>            </section>              </section>
</section>

Implicit Section Breaks

If only headings are used to generate sections.

                                               <section>
<section>              <section>                <section>
<h1>Parent</h1>        <h2>Sibling</h2>         <h3>Nephew</h3>
<hr/>                  <hr/>                    <hr/>
                       </section>               </section>
 <section>             <section>               </section><section>
 <h2>Flowerbox</h2>    <h2>Flowerbox</h2>      <h2>Flowerbox</h2>
 </section>            </section>              </section>
</section>

Vanilla Commonmark

<h1>Parent</h1>        <h2>Sibling</h2>        <h3>Nephew</h3>
<hr/>                  <hr/>                   <hr/>
<h2>Flowerbox</h2>     <h2>Flowerbox</h2>      <h2>Flowerbox</h2>
2 Likes
4

Thanks for this. I have a need for this too. I’ve been writing prose and memoirs in Markdown for the last decade, I must have something like ~200,000 words under my belt or something like it. Will I publish some day… Nothing fancy in the formatting, just that I indeed separate sections with HR’s (eg right before H2’s), but sometimes need them as thematic breaks between paragraphs.

1 Like