Info strings after # line suffixes in ATX headings

[Crissov]

Status quo

An ATX heading consists of a string of characters, parsed as inline content, between an opening sequence of 1–6 unescaped # characters and an optional closing sequence of any number of unescaped # characters.

[Highlighting mine.]

Valid heading suffixes from spec examples

## foo ##
  ###   bar    ###

# foo ##################################
##### foo ##

### foo ###     

Invalid heading suffixes

### foo ### b

# foo#

### foo \###
## foo #\##
# foo \#

Proposal

I wonder whether we can somewhat relax the rule for the closing sequence of # characters. I want to enable something like an info string for future extensions: If the number of unescaped # characters in the opening sequence is matched exactly by the number of unescaped # characters in a possible closing sequence with a space on both sides, the characters after this closing sequence form an info string and are not used verbatim for output.

Only example 44 would be affected by this change:

### foo ### b
.
<h3>foo</h3>

instead of

### foo ### b
.
<h3>foo ### b</h3>

Also:

### foo ### ###
### foo ### ##
### foo ## ###
### foo ## ### ##
.
<h3>foo</h3>
<h3>foo</h3>
<h3>foo ##</h3>
<h3>foo ##</h3>

And:

# foo `#`
# foo ` # `
.
<h3>foo <code>#</code></h3>
<h3>foo `</h3>

... where I'm not completely sure about the last one.

Common use cases

# foo # #bar .baz "quuz"
# foo # {id=bar class=baz title=quuz}
.
<h1 id="bar" class="baz" title="quuz">foo</h1>
<h1 id="bar" class="baz" title="quuz">foo</h1>

The string either inside quotation marks "" or parentheses () would be used in the HTML title attribute, but also in a table of contents, i.e. LaTeX (book) equivalence would be like this:

# foo # "bar"
# foo # (bar)
.
\chapter[bar]{foo}
\chapter[bar]{foo}

There could also be an extension that made headings not have an auto-generated number or not being included in the ToC, or both, e.g.:

# foo # -
.
\chapter*{foo}

Impact

I do not have a corpus available to test this proposal with, but I expect there to be very little existing contents that would be affected by the change, because the hash or number sign # is very unlikely to occur within a heading (or prose in general) with spaces on both sides of it. A string of # characters is even less likely. Authors who are talking of the character itself will very likely mark it up with directly adjacent backticks or quotation marks.

Consequences

People would probably also like to have info strings for setext headings if they were available for ATX headings. Their = and - underlines do not allow any contents in the same line either. A possible, but hackish, solution would be to only consider trailing characters for an info string if the underline length matches the characters in the (last line of the) heading.

I am not proposing this behavior right now.

foo
=== #bar .baz "quuz"
foo
--- #bar .baz "quuz"
.
<h1 id="bar" class="baz" title="quuz">foo</h1>
<h2 id="bar" class="baz" title="quuz">foo</h2>

foo
==  ==  #bar .baz "quuz"
foo
- #bar .baz "quuz"
.
<p>foo ==  ==  #bar .baz "quuz" foo</p>
<ul><li>#bar .baz "quuz"</li></ul>

[vyp]

Also try proposing at https://talk.commonmark.org/.

[Crissov]

Related topics have been discussed there, e.g.:

• Consistent attribute syntax
• Feature request: automatically generated ids for headers
• Anchors in markdown
• Enumerated lists without explicit number, ATX headings with explicit number
• MultiMarkdown Cross References

I'm not sure it's worth raising this topic over there. I'm not proposing the #id .class "title" @key=value syntax (nor any other) for the info string, just that there be an optional info string in ATX headings.

[vyp]

Oh right then, good point. I wanted to point you to the discourse in the case that you didn't know about or see it.

[Crissov]

I have started to edit spec.txt to make this change, but since I got almost no feedback, I’m actually not sure whether I should proceed with that. I also don’t feel competent enough to make the respective changes to the reference implementations.

[Crissov]

commonmark.js

var reATXHeadingMarker = /^#{1,6}(?:[ \t]+|$)/;

    // ATX heading
    function(parser) {
        var match;
        if (!parser.indented &&
            (match = parser.currentLine.slice(parser.nextNonspace).match(reATXHeadingMarker))) {
            parser.advanceNextNonspace();
            parser.advanceOffset(match[0].length, false);
            parser.closeUnmatchedBlocks();
            var container = parser.addChild('heading', parser.nextNonspace);
            container.level = match[0].trim().length; // number of #s
            // remove trailing ###s:
            container._string_content =
                parser.currentLine.slice(parser.offset).replace(/^[ \t]*#+[ \t]*$/, '').replace(/[ \t]+#+[ \t]*$/, '');
            parser.advanceOffset(parser.currentLine.length - parser.offset);
            return 2;
        } else {
            return 0;
        }
    },

[jgm]

I think this kind of discussion belongs in talk.commonmark.org, so we can keep this tracker more focused.

[Crissov]

Discussion continues there: https://talk.commonmark.org/t/info-strings-for-suffixed-headings/2902