marick

marick

What is syntax for ExDoc markdown?

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:

Screenshot 2024-06-07 at 10.34.49

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

Most Liked

garazdawi

garazdawi

Erlang Core Team

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

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

Screenshot 2024-06-08 at 08.36.54

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

Screenshot 2024-06-08 at 08.38.43

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.

Where Next?

Popular in Questions Top

baxterw3b
Hi guys, i’m new in the Elixir world, and i have to say, that i love it! i’m having some problem to understand anonymous functions with ...
New
hariharasudhan94
I would like to know what is the best IDE for elixir development?
New
nsuchy
Hi. I’ve noticed that Windows Powershell has it’s own IEX command and you cannot access Elixir’s IEX due to the conflict. This isn’t a cr...
New
joeerl
Hello again - after a longish gap I’ve decided I really must dig into Elixir and see what’s been happening here - so I have a few questio...
New
gshaw
What is the idiomatic way of matching for not nil in Elixir? E.g., First way: defp halt_if_not_signed_in(conn, signed_in_account) when...
New
bsollish-terakeet
Credo is smart enough to check for (something like) this: assert length(the_list) == 0 with this response: Checking if an enum is empt...
New
albydarned
Hello all! I am typing this post from my new MacBook Pro with the M1 chip. I’m loving it so far, and will probably use it as my daily dr...
New

Other popular topics Top

rms.mrcs
Hi, I need to transform a list of numbers into a map where the keys are the indexes and the values are the original values of the list. ...
New
vonH
When I run the Plug and I recompile I wind up having to use Ctrl C to quit iex and start again. Witht the help of rlwrap I can use the cu...
New
hariharasudhan94
Lets say I have map like this fetching from my database %{"_id" =&gt; #BSON.ObjectId&lt;58eb1a7a9ad169198c3dXXXX&gt;, "email" =&gt; ...
New
Brian
What is the proper way to load a module from a file in to IEX? In the python world, doing something like this pretty standard: from ....
New
axelson
This post is a wiki (feel free to hit the edit button near the bottom right of this post to add your own changes!) This post collects co...
239 49266 226
New
Patoshizzle
After calling mix ecto.create I get this error: 17:00:32.162 [error] GenServer #PID&lt;0.412.0&gt; terminating ** (Postgrex.Error) FATAL...
New

We're in Beta

About us Mission Statement