What is syntax for ExDoc markdown?

[marick]

I am working on a package. The documentation will eventually make it to hexdocs.pm. The source is on GitHub, so it would be nice if the doc source (.md) would render there too.

This question taught me how to enable footnotes in mix.exs:

      markdown_processor: {ExDoc.Markdown.Earmark, footnotes: true},

Using that, I tried Github markdown syntax:

with smaller blobs within it[^1]
...
[^1]: The photo is via ...

It does work when viewing the file on github:

… but it only sorta works when I view the html in the docs folder:

Am I using the wrong syntax? I haven’t found a description of which variant of markdown Earmark supports. (If someone tells me where to find that, I’ll make a PR for the documents I looked in.)

I’m OK, I guess, with having the markdown files look wrong on github.

[garazdawi]

@marick

I haven’t found a description of which variant of markdown Earmark supports.

As far as I know, Earmark (or rather EarmarkParser) says that it supports Gruber Markdown though it tries its best to also support GFM, but there are edge cases where it does not and also it has its own set of extensions that are listed in its Readme.

So, as always with Markdown, ExDoc uses its own flavor that works differently than all other Markdown flavors If you want things to look nice on github and on hexpm, using as basic Markdown features as possible is the way to go in my oppinion.

[marick]

Thanks. Digging a bit deeper, it seems that the Markdown is parsed correctly, but that ExDoc isn’t using it correctly. There are two issues. The first is that the character is quoted, so appears as ↩ There is an ExDoc issue for that. It was closed without a fix, but the person who raised it did produce a hack by overriding class="reversefootnote":

  <style>
    a.reversefootnote {
      display: inline-block;
      text-indent: -9999px;
      line-height: 0;
    }

    a.reversefootnote:after {
      content: ' ↩'; /* or any other text you want */
      text-indent: 0;
      display: block;
      line-height: initial;
    }

That leaves the problem of the link to the footnote, which Github renders as a superscripted character in brackets:

Although the <a> has class="footnote", that class doesn’t style the text to make it look like a footnote:

That can be fixed with another style:

    a.footnote {
      font-size: 0.7em;
      vertical-align: super;
    }

… which seems to work, though that three lines is a non-negligible fraction of all the CSS I’ve ever written.