Heading Number and Table of Content Extension

Extensions
1

Hi,

I like to propose two items to add to the spec

  • Add the ability to number headers.
  • Add the ability to add table of contents.

Perhaps, for auto-numbering headers, in the first few lines of a markdown text, we can add something like this: {auto-number-headers}.

Then, every time the header syntax appears (i.e #, ##, etc…), the render will auto number the sections like this: 1, 1.1, 1.2.4, 2.1.2 as it parses each level or header.

Here’s an example:

# My big topic
## My sub topic blah
### my sub sub topic foo foo
# My next big topic 
## something

would render to this (other visual text effect typically rendered are not done here to convey the intent of this post.):

1. My big topic
1.1. My sub topic blah
1.1.1 my sub sub topic foo foo
2.  My next big topic 
2.1 something

For the table of content request, the raw markdown text would add {toc} and the render would know that this is where the table of content would be placed.

The render would first have to parse all headers (i.e. #, ##, etc…) then create a table of content that if a user clicks on it, it would bring the user to that part of the rendered markdown. Also, if both {auto-number-headers} and {toc}, the table of content would also include the number headers too.

This would be a nice addition to allow technical specs to be written easier. Additionally, it would make it a bit clearer in rendered markdown to know that something is at a different level header because size of text and other visual text effects do not always clearly convey the hierarchy of the document.

2 Likes
2

Could we use Jekyll-style front matter to toggle on and off automatic table of contents and automatic numbering of headings?

I believe Kramdown uses the {toc} syntax, but Markdown generally avoids adding English language to the document markup itself. With front matter, we also make the placement of the table of contents configurable, e.g. insert table of contents at the top of the document, insert table of contents before the first heading, etc.

3

absolutely! I was just giving an example of the syntax to explain or illustrate my ask. if the folks at commonmark want to use the Jekyll-style front matter, especially if this is something widely used by renderers that adopt Commonmark and its variant, I am good with that. I do not care so much about the syntax but more about the feature.

As for {toc}, yes, I am okay with your proposal as well. Thanks for considering it!

2 Likes
4

I don’t think these should be additions to the spec, but rather rendering options that any CommonMark compatible renderer can expose.

The spec is about the form and semantics of CommonMark plain text markup. What you describe requires no change to the markup or even its semantics (That the headings are numbered in the case of your example is purely rendering choice).

Where it would have to be part of the CommonMark spec is if the content author specified the heading numbers in the plain text, e.g. as we can with lists to control the starting number or to have both numbered and non-numbered lists in the same doc.

1 Like
5

Ok. Putting it in spec allows you to drive commonality and consistency between the various CommonMark renderers. You get inter-operability. I understand that may be technically it doesn’t belong in the common mark spec since you want it to be of the form and semantics of the raw unrendered text but it should be in some kind of spec. Otherwise, one implementation of CommonMark renderer could behave differently than another implementation of CommonMark renderer.

6

Intuitively: Numbers for headings with number sign prefixes #, no numbers for underlined headings. That means, the AST needs to distinguish ATX and Setext styles.

1 Like