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

lessless
I believe there are people here who are dealing with CSV files import on the daily basis, and since Excel is a really popular tool there ...
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
yawaramin
In the Dialyzer docs ( http://erlang.org/doc/man/dialyzer.html#requesting-or-suppressing-warnings-in-source-files ), there is a way to tu...
New
openscript
Hello! Sorry for this astonishing simple question, but I’m really stuck. I try to set up the intellij-elixir plugin, but I don’t know ho...
New
tduccuong
Hi, is there any work on GUI with Elixir, that is similar to Electron/Javascript? My idea is to bundle Phoenix and BEAM into a single se...
New
logicmason
Hi there, I'm working through my first release with elixir/phoenix. I've built a release with distillery and found that it crashes when I...
New
hariharasudhan94
I would like to know what is the best IDE for elixir development?
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
vrod
I am using the Starship cross-shell prompt – it seems pretty nice, but I get some errors: [WARN] - (starship::utils): Executing command ...
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

Other popular topics Top

yurko
Here are few pieces of (common) Linux knowledge that we use for reasonably small one server apps. We use Ubuntu but this should work for ...
New
ycv005
I have followed this StackOverflow post to install the specific version of Erlang. And When I am running mix ecto.setup then getting fol...
New
malloryerik
Hi, this is for people who, like me, have had some friction using .html.heex templates in VSCode. The solution seems to be, in a hyphena...
New
KronicDeth
Elixir plugin for JetBrain’s IntelliJ Platform (including Rubymine) This is a plugin that adds support for Elixir to JetBrains IntelliJ...
289 35421 110
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
lastday4you
I wanted to check elixir version in phoenix because i found that my elixir is 1.5 but when i use Enum.chunk_by it said the function is un...
New
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
fireproofsocks
Forgive me if this is obvious, but how does one delete a database record WITHOUT selecting it first? https://hexdocs.pm/ecto/Ecto.Repo.h...
New
ovidiubadita
Hey all, I discovered Elixir and I love it. I always wanted to learn a functional programming and I intended to go for Haskell, but afte...
New
aesmail
Hello guys, I have finally made it. I created an admin interface for a framework. It’s been on my todo list for years and with the curre...
New

We're in Beta

About us Mission Statement