Heading id:s anchors

[jmn]

Would it be possible to have Earmark.as_html("##Foo") generate <h2 id="foo">Foo</h2> so you can navigate the document to section headings (e.g. /document.html#foo"). Pandex (Pandoc) currently does this.

[RobertDober]

I like the idea. But I need to give it some thoughts, because I am very vulnerable to feature creep.
Another point is that we risk creating conflicting id's what would you think about the alternative of being GFM compliant https://babelmark.github.io/?text=%23%23+hello and therefore generating

  <a id="user-content-hello" class="anchor" href="#hello" aria-hidden><span aria-hidden class="octicon octicon-link"></span></a>hello

That would also be better because as far as I understand @josevalim is rather pro GFM compliance and ex_doc is just our main customer 😊

I guess I would lose the <span> though, and, of course keep the <h2>.

[josevalim]

We already do it for ExDoc, so if it is added, we would need to make it opt-in or opt-out to not break our references. We pretty much have to namespace all of our ids by the module or function name, because the chance of conflicts is high.

[RobertDober]

Thx for the update @josevalim. So there could be an option for that, but there are a great many already.... hmm I still see the value of the feature and it is easy to implement, but code is
always a liability.

Would using the evolving API with as_ast |> your_filter |> transform be an option @jmn ?

I'd love to see people develop that kind of filter for all to use and to take some burden off Earmark.

Therefore I guess my time is better spent making this API stable ASAP and releasing a 1.5 than to add yet another feature myself...

[RobertDober]

Just an idea. After 1.5 is released it would be nice to create a hex package EarmarkFilters which would test their filters against Earmark.Transform.transform. I could own such a package but would surely prefer to be a humble contributor if needed.

[jdmarshall]

Markdown cheat sheet says that the syntax 'should' be

### My Great Heading {#custom-id}

Which of course does not work with Earmark.

[RobertDober]

This would be nice 😊

again these are reasonabe ideas, for which I do not have reasonable time alas.

Actually adding this would not need an option as it would be done in Earmark only not in the parser.
concerning the syntax mentioned by @jdmarshall would this be something possible in Earmark Parser ? Should it be protected with an option as it might break some ex_doc, although would be nice to be standard by default, thoughts @josevalim ?

Deprecation warnings of course before making it default

[josevalim]

I think it should be guided by an option and the option may want to specify an optional prefix. For example, in Elixir, we prefix all module ones with "module-" and all function ones by the function name.