Table of contents extracted from Markdown documents

[mnapoli]

A new step extracts a table of contents from Markdown documents (list of headers) and makes it available as metadata. Uses the latest commonmark (we end up with 2 Markdown parser because this one doesn't support Markdown Extra).

With this new step, we now have this metadata available in Twig layouts:

<h1>{{ tableOfContents.title }}</h1>
<p>
    Table of contents:
</p>
{{ tableOfContents.toHtmlList() }}

API of tableOfContents:

• title: the title of the current document (i.e. first header of level 1)
• toHtmlList(): generates the summary as a HTML list (<ul>)

TODO:

• Require a stable dependency in composer.json (i.e. wait for a new release of commonmark)
• Should the metadata key be document instead of tableOfContents? (no)
• Update to the latest CommonMark version
• Merge master
• The list should contain links to headers. Related to Auto-generate HTML IDs for headers #39
• Documentation

[wysow]

@mnapoli seems your wish is coming true: https://github.com/thephpleague/commonmark/releases/tag/0.5.0 ;-)

[mnapoli]

Good!

I just noticed that the library requires mbstring, which I'm afraid will lead to conflicts later on. I've opened thephpleague/commonmark#38 to fix this.

[mnapoli]

thephpleague/commonmark#38 was fixed, waiting for a new stable release to be able to use it ;)

[wysow]

@mnapoli seems the release of commonmark has been done right?

[mnapoli]

Yep cool!

I'm wondering if it's worth the effort to try and make the CommonMark parser support Markdown Extra. The thing is that it is needed to be able to link to headers, without that a table of content is kind of useless. But since CommonMark doesn't support it, it means people could end up defining IDs with Markdown Extra:

# A rapid example {#example}

But CommonMark will not parse it… The if we auto-generate title IDs from the text content (#39), here we would have a table of content linking to a-rapid-example but Parsedown would have generated an ID named example instead…

By making CommonMark support Markdown Extra, we could remove Parsedown and have a consistent behavior… It would be perfect. Still need to think about it, extending CommonMark doesn't look that easy…

[mnapoli]

I'm convinced now that we need Markdown Extra support in CommonMark to replace Parsedown and finish this PR.

I've opened thephpleague/commonmark#60 and hopefully I'll find some time to look into it.

[wysow]

@mnapoli So should we start our own extension for this?

[mnapoli]

@wysow yep I've tried a few times already but this is quite a challenge honestly.

Also, I had a look at https://github.com/dshafik/markua and about Markua itself and it looks quite cool! The good thing is that Markua seems to include all Markdown Extra, + a few features like the "asides" that are the just perfect for writing documentation (which makes a lot of sense since Markua has been invented for Leanpub for writing books…).

So my POV is let's use Markua instead, which would cover both Markdown and Markdown Extra. That means contributing to https://github.com/dshafik/markua to implement missing features (actually the main things we need are tables and headers IDs). If that project is not maintain anymore, we can also fork it to our organization…

What do you think? If you want to have a look into that you are most welcome, honestly I was a bit lost with the API of CommonMark…

[mnapoli]

I updated this PR. What's lacking now is linking the table of contents items to the headers (so that we can go to a header by clicking on it in the summary).

[ncarboni]

Any update of the documentation? I would love to generate a TOC based on the header in the markdown and having it appear in the default theme/readsthedoc

[mnapoli]

Unfortunately this PR is 2 years old and has huge changes, I might as well close it for now to avoid giving false hopes.