earmark

earmark copied to clipboard

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.

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 :blush:

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

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.

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...

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.

Markdown cheat sheet says that the syntax 'should' be

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

Which of course does not work with Earmark.

This would be nice :blush:

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

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.