Auto-generate HTML IDs for headers

[mnapoli]

It's pretty useful to be able to link to a sub-section of a page. To do this, we need to have HTML IDs on headers, like this:

<h2 id="introduction">Introduction</h2>

This is possible with Markdown Extra (supported by Couscous by default):

## Introduction {#introduction}

But that requires to use that notation everywhere. What would be good is to automatically add the IDs for headers.

For example: https://github.com/piwik/developer-documentation/blob/63348af258b258de5dd66d3978f5726d5717380c/app/helpers/Markdown/TitleIdPreprocessor.php

Note: I believe we can't copy-paste that code directly since its license is GPLv3 and Couscous is MIT (are they compatible?). We probably need to rewrite it.

We could probably implement that as a Step that is executed before Markdown is parsed.

This feature is super-useful to be able to specific sections in menus, or also to share the URL of a specific section of the documentation.

[henriquemoody]

I've sent erusev/parsedown#285 in order to do that. Perhaps do it on Couscous is better.

[mnapoli]

@henriquemoody cool! However we are looking at a more generic solution, because ideally we would like to be able to link to headers but also traverse the whole document structure (for example to generate a table of contents or a menu).

See that pull request: #69

So to do that we would have to move away from Parsedown in favor of https://github.com/thephpleague/commonmark which has the benefit of parsing a Markdown document into a PHP model that can be explored and manipulated (before being dumped to HTML).

What's blocking for now is that this new Markdown parser doesn't support Markdown Extra (see this comment).

[henriquemoody]

I got it.

If is there a way I can help I will be glad.

[mnapoli]

@henriquemoody the main blocker for #69 is to have support for tables and header IDs in https://github.com/dshafik/markua (Markua is a syntax on top of Markdown that includes Markdown Extra). So we want to contribute to this library to fill what's missing for Couscous, and then replace Parsedown with it.

If you manage to contribute to https://github.com/dshafik/markua that would be awesome!

[mnapoli]

And as I said in #69, if https://github.com/dshafik/markua turns out to be not maintained, we will fork it and move it to Couscous organization to be able to finish it.

[henriquemoody]

As I commented into the Parsedown project, If you take a look on all processed Markdown files rendered by GitHub you will he something like that right after <hN> tags:

<a name="this-is-an-anchor" class="anchor" href="#this-is-an-anchor">
    <span class="octicon octicon-link"></span>
</a>

We can do that on Couscous, but not on a Markdown library, IMO.

Any way, I will be nice if you fork Markua, I will be glad to contribute as well.

Ps.: You probably already read this but it's a good reading to attach to this issue: https://philsturgeon.uk/markdown/2014/11/30/state-of-markdown/