1

As the undermentioned demonstrates, significant interest in a hierarchy-independent heading tag exists for the WHATWG’s Living Standard HTML5 specification:

However, Markdown’s heading syntaxes (the 1 to 6 × #, and -/= underlines) always correlate to a specific depth.

The latter underlines could feasibly be redefined to little backward incompatibility. However, they’re definitely the less popular syntaxes, and for good reason - # is more concise, and doesn’t need to be modified when the heading content is modified.

Consequently, does anyone have any good ideas for what the Markdown syntax could be, if h (more like when) is implemented?

2

For Commonmark, HTML is just one of several possible output formats, although it is special in that most of its elements can be used within a CM document verbatim. There does not need to be a 1:1 mapping to all HTML elements from pure CM syntax, and there never has been. If <h> got added to HTML, CM processors could very well start generating documents (or more likely fragments) that used the new element based on the existing CM heading syntaxes (prefixed ATX and underlined Setext), just as they could output <section>s today. For that, I have suggested increased control of sectioning by repurposing the horizontal rule / thematic break syntaxes in Horizontal rules as (hierarchical) section breaks etc

  • ----: empty heading section break – continue in new anonymous sibling section
  • ****: structural section break – continue in parent section afterwards
  • ____: visual hr break

Anyway, if one absolutely wanted to add an explicit way to generate a <h> element (without just using it) to CM, I think seven hash marks would do:

####### Hi, I'm becoming an `<h>` in HTML output #######

####### Me too

<h>I've always been one</h>
.
<h>Hi, I'm becoming an <code>&lt;h&gt;</code> in HTML output</h>
<h>Me too</h>
<h>I've always been one</h>
1 Like
3

@Crissov, that’s exactly the kind of suggestion I was looking for. I hadn’t thought of that at all. Thank you.

It’s certainly not concise, but it’d probably be more intuitive and consistent than any alternative implementation.

If this Discourse instance used the solution plugin, I’d mark your comment as it.

4

HTML is just one of several possible output formats

Talking of alternate target formats, how would a depth-agnostic heading be rendered in LaTeX? How would it know when to decrease or increase the level? In HTML it makes sense because there can be wrapping elements such as <section>, <main>, etc.

5

@samwilson, I presume you ask because LaTeX does not have a hierarchy-agnostic heading tag either? If so, that’s a shame - do you know whether such a tag for it has been requested anywhere, too?

6

I think the problem with this discussion is that it sees Markdown as source code for HTML, rather as plain text content meant for consumption as-is (i.e. it is already its own rendering!).

If you see it as the latter as I do, also as it was originally envisioned[1], and also as CommonMark reaffirmed[2], then current headings work perfectly. If your content has no hierarchy, then use only level one headings. If you have headings that are nested, then use the appropriate sub-heading level. This works perfectly for humans reading the plain text as-is.

The linked HTML issue, that “using specific heading levels (<h4>) is it couples components to their containing context” is not relevant for Markdown as Markdown isn’t meant for constructing HTML pages with React components or any other HTML component.

Not unless by “component” you mean “a piece of text content that can get embedded within other content”. But even there, that’s the responsibility of the renderer that is doing the embedding. What I wrote about element IDs applies equally to heading levels:

It is the responsibility of the embedding context to respect and protect my scope. Whether in its rendering it avoids ID collisions by altering its IDs or mine, or demotes my heading levels to avoid multiple H1s, it is its business, its job to make it work.

There should be a clear separation of concerns between authoring content and publishing mechanics. I shouldn’t have to manage the technicalities of an output format while authoring in a format that is supposed to be independent and portable. As the content author, the only thing that matters is that I have a semantically unambiguous and intuitive way to create internal links. I don’t care how they are ultimately rendered.

…just change the last two sentences to “As the content author, the only thing that matters is that I have a semantically unambiguous and intuitive way to create hierarchical structure. I don’t care how they are ultimately rendered as long as that hierarchy is respected”.

@Crissov I think you get this:

But the syntax you describe for headingless sections goes back to treating Markdown as a source for HTML. I say that because the syntax you propose has the notion of hierarchy, but that won’t be evident to the human plain text reader, not unless they internalize your rules. The only natural ways for plain text to represent hierarchy are indentation, borders (e.g. block quote’s left border), or headings with heading levels. In other words, I don’t think your semantics for **** works, and the distinction between ---- and ____ doesn’t make sense for Markdown, which should only deal with semantic breaks, not presentation (e.g. horizontal rules).

See also What's a good way to go up one header / section? - #2 by vas

  1. The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. Daring Fireball: Markdown ↩︎

  2. CommonMark spec: What is Markdown ↩︎

7

@vas, that’s not true, and I’m quite surprised that you purport it to be. Do you never have nested headings past 6 levels deep? The way that I’ve nested headings is by doing what YAML does - embed lists:

# Title

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

## Heading

1. ## Heading

   Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

1. ## Heading

   1. ## Heading

      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

   1. ## Heading

      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

## Heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

## Heading

1. ## Heading

   Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

1. ## Heading

   Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Hopefully the aforementioned demonstrates why including the hierarchical position within the heading is redundant - the nested <ol>s do that for me.

It’s also why I requested the undermentioned:

Specifically, pleasantly formatted inline HTML is impossible with indented lists, because the indentation cannot span a line break in the HTML, lest it be considered to be an indented code block (<pre>).

This has been endlessly corroborated:

How would you accomplish this? The undermentioned?

# Title

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

## Heading

### Heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

### Heading

#### Heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

#### Heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

That’s not particularly readable in plain text format.

8

My words you quote are directed at @Crissov and his proposed syntax. Please see context.

Content intended for human consumption should not be nested 6 levels deep, much less even deeper.[1][2][3] The only content I’ve ever seen that has super deep nested headings are legal documents, and even there I don’t think I’ve ever seen anything 6 levels deep. At some point, for human intelligability, you break the content into separate documents.

And honestly, I have no clue what you are trying to accomplish in your example. But whatever it is you are trying to do, you are employing indentation to represent hierarchy, one of the natural (for humans) means to represent hierarchy in plain text that I listed. Thus the level in the heading becomes irrelevant, you can use # or ##. As I point out, it is the responsibility of the renderer to properly translate this to HTML, LaTeX, PDF or whatever.

  1. [ Why don’t Tufte classes have subsubsections? ↩︎

  2. It is also notable that the Feynman lectures (3 volumes) write about all of physics in 1800 pages, using only 2 levels of hierarchical headings: chapters and A-level heads in the text. It also uses the methodology of sentences which then cumulate sequentially into paragraphs , rather than the grunts of bullet points. Undergraduate Caltech physics is very complicated material, but it didn’t require an elaborate hierarchy to organize. A useful decision rule in thinking and showing is “What would Feynman do?” - from Book design: advice and examples | Edward Tufte ↩︎

  3. How many heading levels are there in your document? - Reinout van Rees ↩︎

1 Like
9

@vas, I’m glad you agree. However, my point was merely that this syntax would be useful inside Markdown for the same reason, considering that methods like that can be employed. It’s not merely useful when converting to HTML. Using ## works, but it’s ultimately not quite correct.

10

We don’t agree. I am saying Markdown does not need any new syntax to support rendering of headings with the proposed <h> tag.

For example, this:

# Heading

## Subheading

has a default CommonMark rendering of:

<h1>Heading</h1>
<h2>Subheading</h2>

But if the content were embedded within an <h2> section of some other content, it would be perfectly legitimate if not advisable for it to be rendered as:

<h3>Heading</h3>
<h4>Subheading</h4>

If the desire were to render with <h> headings , that would be fine too:

<section>
  <h>Heading</h>
  <section>
    <h>Subheading</h>
  </section>
</section>

It’s important to think of Markdown abstractly and semantically, not as source code for HTML.

It’s not redundant, if you think of it abstractly. # simply signifies a heading. ## signifies a heading that is a subheading of the previous #, or just a heading if there were none. Yes, the default rendering into HTML is <h1> and <h2>, but those are just default renderings.

Finally, keep in mind the :loudspeaker: banner at the top of the site. If you dismissed it and have forgotten what it said, clear your cookies or reopen in a private browser window. CommonMark isn’t going to add new features. Discussion of ideas or extensions is fine, as long as it is understood it’s not going to become part of the CommonMark spec. I’m not in charge here. I’m just relaying information that is well established if you’ve been around here and read many posts, especially those by @jgm, who is in charge.

11

@vas, perhaps I should read the CM specification.

Does this mean that unlike the WHATWG’s HTML5 Living Standard, # doesn’t need to be unique per document? If so, indeed - I suppose CommonMark implements the proposed <h>'s equivalent already.

However, if all of what you state is accurate, why would there be solely up to 6 levels of indentation permitted? One would expect me to be able to do #######. You state that CommonMark should be considered separate to HTML, yet its deficiencies appear to match HTML’s 1:1.

To my knowledge, extensions appear to negate that, hence the OP’s tag of Extensions.