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

marius95
Hello everyone, I try to use an Javascript Event Handler in my root.html.leex file. Therefore I created a function in the app.js file: ...
New
9mm
I am constructing a JSON object (map) and I need to conditionally set a field. I’m trying to write proper elixir-way code… and I’m at a l...
New
myronmarston
The Elixir Typespec docs show the following syntax for keyword lists in typespecs: # ... | [key: type] # keyword lists...
New
electic
Hi, I am new to Elixir. I am trying to use the DateTime component to insert a date into MySQL however the there seems to be no way to fo...
New
Lily
In templates/appointment/index.html.eex: &lt;%= for appointment &lt;- @appointments do %&gt; &lt;tr&gt; &lt;td&gt;&lt;%= appoi...
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
pmjoe
I have a relationship of love and hate with Elixir. Lots of things are just absolutely right, but there are some things that are kind of ...
New
freewebwithme
Using vs code and installed ElixirLS: support and debugger. And I got an error popped up on start up says Failed to run ‘elixir’ comma...
New
script
If I have a string “1000 cfu/ml” . I want to remove the characters and / and space . So the string is like this "1000" What is the ...
New
WestKeys
Currently suffering from paralysis by [HTTP client] analysis. This is rather unusual in Elixirland as there tends to be consensus on the ...
New

Other popular topics Top

senggen
Erlang/OTP 25 [erts-13.2.2] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] 15:22:35.803 [error] gen_event {lager_file_backend...
New
electic
Hi, I am new to Elixir. I am trying to use the DateTime component to insert a date into MySQL however the there seems to be no way to fo...
New
chrismccord
Phoenix 1.4.0 released Phoenix 1.4 is out! This release ships with exciting new features, most notably with HTTP2 support, improved deve...
688 30877 112
New
minhajuddin
I have seen a lot of code which picks the first element from a list using Enum.at(0) instead of List.first. Is there a reason why people ...
New
Lily
In templates/appointment/index.html.eex: &lt;%= for appointment &lt;- @appointments do %&gt; &lt;tr&gt; &lt;td&gt;&lt;%= appoi...
New
jay1
Why is it that the mnesia database isn’t the most preferred database for use in Elixir/Phoenix?
New
pmjoe
I have a relationship of love and hate with Elixir. Lots of things are just absolutely right, but there are some things that are kind of ...
New
vrod
I am using the Starship cross-shell prompt – it seems pretty nice, but I get some errors: [WARN] - (starship::utils): Executing command ...
New
WestKeys
Currently suffering from paralysis by [HTTP client] analysis. This is rather unusual in Elixirland as there tends to be consensus on the ...
New
sergio
Kind of like when jquery came out, it was super necessary. Existing drag and drop libraries have a bunch of baggage to support old browse...
New

We're in Beta

About us Mission Statement