Related topics
- Info strings elsewhere
- 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
@jgm closed issue #500 on Github, suggesting we discuss it here, so Iʼm quoting most of it below:
Status quo (0.28)
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.
[Emphasis mine.]
Valid heading suffixes from spec examples
## foo ##
### bar ###
# foo ##################################
##### foo ##
### foo ###
Invalid heading suffixes
### foo ### b
# foo#
### foo \###
## foo #\##
# foo \#
Proposal
I wish 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}
Iʼm not proposing the #id .class "title" @attribute key=value syntax (nor any other) for the info string, just that there be an optional info string in ATX headings.
Impact
I do not have a corpus available to test this proposal with, but I expect there to be very little existing content 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>
More ideas like this are discussed in Info strings elsewhere.
It’s really something that’s needed…