Table of contents generator

[macfarmw]

I recommend adding a table of contents generator feature. A placeholder like pandoc's --toc or MultiMarkdown's {{toc}} will be expanded into list of links nested by heading level.

Given the markdown:

# Markdown
--toc
# History
John Grubner created the Markdown language in 2004.
## Standardization
There is no clearly defined Markdown standard, apart from the original writeup and implementation by John Gruber, which some consider abandonware.
## CommonMark
From 2012, a group of people including Jeff Atwood launched what Atwood characterized as a standardization effort.
# Implementations
Implementations of Markdown are available for over a dozen programming languages.

The generated html will be

<h1 id="markdown">Markdown</h1>
<ul>
    <li>
        <a href="#history">History</a>
        <ul>
            <li><a href="#standardization">Standardization</a></li>
            <li><a href="#commonmark">CommonMark</a></li>
        </ul>
    </li>
    <li><a href="#implementations">Implementation</a></li>
</ul>
<h1 id="history">History</h1>
<p>John Grubner created the Markdown language in 2004.</p>
<h2 id="standardization">Standardization</h2>
<p>There is no clearly defined Markdown standard, apart from the original writeup and implementation by John Gruber, which some consider abandonware.</p>
<h2 id="commonmark">CommonMark</h2>
<p>From 2012, a group of people including Jeff Atwood launched what Atwood characterized as a standardization effort.</p>
<h1 id="implementations">Implementations</h1>
<p>Implementations of Markdown are available for over a dozen programming languages.</p>

Which looks like this:

Markdown

• History
  • Standardization
  • CommonMark
• Implementation

History

John Grubner created the Markdown language in 2004.

Standardization

There is no clearly defined Markdown standard, apart from the original writeup and implementation by John Gruber, which some consider abandonware.

CommonMark

From 2012, a group of people including Jeff Atwood launched what Atwood characterized as a standardization effort.

Implementations

Implementations of Markdown are available for over a dozen programming languages.

[xoofx]

Thanks for the suggestion. I don't have time to implement this feature, but a PR is welcome.

In the past, I previously thought about adding such extension, but when prototyping a static website generator (lunet) that had to support also HMTL content, I realized that TOC content generation is often done outside of the document itself (in the layout part, which is often already in HTML), and has to support TOC from different input (HTML, Markdown... etc.), so I decided that it was better to plug TOC generation from the HTML output directly... hence, the lack of motivation to work on this. 😅

[johnsimons]

@xoofx if you were to do it as part of the md rendering, any tips where to start or what code to look at for inspiration?

[RickStrahl]

+1 @johnsimons The docs for extending seem a bit sparse at the moment and looking at some of the existing extensions is dense reading :-)

Re: TOC generation: I've done this in the past with just a bit of JavaScript on the client that looks for all headers and the builds up the TOC structure to embed on the page. The advantage of this is that you don't have to pre-gen and you can have more control over when and where you generate the TOC.

[clarkd]

I'm just circling back to this as we have a similar requirement. I think @xoofx is right insofar as it would be best to generate it from the frontend but what I'm wondering is how to trigger it.

I figured that there could be a simple Markdig extension that looks for --TOC anywhere in the markdown and renders that as <div class="markdig-toc"></div>. From there a JS extension could look for that class and build/generate a TOC within it. That way, the author has control where the ToC appears.

Thoughts? @xoofx? @macfarmw

[xoofx]

I figured that there could be a simple Markdig extension that looks for --TOC anywhere in the markdown and renders that as <div class="markdig-toc"></div>. From there a JS extension could look for that class and build/generate a TOC within it. That way, the author has control where the ToC appears.

sure, that's one option.

One thing to keep in mind is that usually a TOC can require parameters, things like "starting level" (to exclude for example the first # top level heading) or "depth level" (to specify how deep to display), you could also want to add numbering (and different kind of numbering)... and maybe include this numbering as part of your headings...etc.

When you see how difficult specifications for the basic CommonMark set is already quite a challenge, you could imagine that many could come with different requirements/features requests for such an extension!

If I remember for lunet, I thought about using HTML comments for this kind of extensions that actually don't require any changes to markdig:

without parameters:

<!-- toc -->

or with parameters:

<!-- toc level=1 depth=3 -->

so that you could process them with any HTML parser, but you could also process them directly with mardkig as a post extensions working on HTML blocks. This can be a placeholder for a lot of different extensions but avoids having to develop a new extension parser for every new extension "tag". And it makes it compatible with pure HTML docs...

but you can go with a dedicated syntax as well...

[Atrejoe]

It appears that this pipeline addresses TOC creation:

https://github.com/leisn/MarkdigToc