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

Fl4m3Ph03n1x
Background Let’s assume I have a typical GenServer that receives messages as requests, does some operation in a DB and returns responses....
New
Harrisonl
We have an ECS cluster with 4 services, where each task joins a single cluster, via discovery ECS discovery service. Currently when I de...
New
shahryarjb
Hello, I get Persian date from my client and convert it to normal calendar like this: def jalali_string_to_miladi_english_number(persi...
New
jononomo
I am trying to figure out how Mix knows whether the environment is test, dev, or prod -- where is this set? Thanks.
New
dotdotdotPaul
Okay, I'm having a heck of a time trying to figure out how to best handle the validation of belongs_to associations in Ecto. I'm sure I'...
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
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
myronmarston
The Elixir Typespec docs show the following syntax for keyword lists in typespecs: # ... | [key: type] # keyword lis...
New
chewm
Hi guys, nice to meet you to the whole forum, I’m new here, I’m trying to configure visual studio code for elixir, right now the intellis...
New
skosch
To my knowledge, put_in, Map.update etc. all have the one limitation of not automatically creating intermediate keys when needed (for exa...
New

Other popular topics Top

Qqwy
Update: How to use the Blogs &amp; Podcasts section You can post links to your blog posts or podcasts either in one of the Official Blog...
3268 119930 1237
New
vonH
In asking this question I am more interested about the expressiveness of the language itself and less concerned about the availability of...
New
romenigld
I am trying to run a deploy with docker and I successfully runned with this command: docker build -t romenigld/blog-prod . but when I t...
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
lk-geimfari
What is most correct way to open, read and parse JSON file with poison? For example if we have example.json file in root of some projec...
New
danschultzer
None of the current solutions worked well for me, so I went ahead and built a user management system from scratch. This project took far...
548 27727 240
New
ashish173
I am using Ecto timestamps with postgres, I can see the timestamps() use the :naive_dateime but for my use case I wanted to store the ti...
New
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
lucidguppy
I have a super simple question about elixir - how would I take a file like this foo bar baz and output a new file that enumerates th...
New
magnetic
Hey :wave:t3: Elixir community, I’ve been learning Elixir, and working on some side projects. My editor of choice is VSCode, and althoug...
New

We're in Beta

About us Mission Statement