Earmark GFM Footnote Return to Article Link Text Rendered Incorrectly

[jwilger]

When parsing a markdown document that contains footnotes with the option footnotes: true passed to Earmark, the link that is inserted at the end of the footnote by Earmark has the link text set to ["↩"] (https://github.com/RobertDober/earmark_parser/blob/5797a53a1d60003e5d0038c326bfd1e8b129c85f/lib/earmark_parser/ast/renderer/footnote_renderer.ex#L31).

When rendering the documentation as HTML via ex_doc, this link text is escaped, replacing the & with &, so that the literal ↩ is displayed in the text rather than the HTML entity that was intended.

It looks like ex_doc can take a verbatim: true option when rendering a tag (

ex_doc/lib/ex_doc/doc_ast.ex

Line 49 in 7dbc937

def to_string({tag, attrs, inner, %{verbatim: true}} = ast, fun) do

) which seems like it would address this issue, but I'm not entirely sure how to get ex_doc to use that option in this case. Part of me wonders if that option shouldn't just be used for all text that is coming from the markdown processor, thus making any escaping of HTML entities the job of the markdown processor itself rather than the templating modules of ex_doc, but I'm not familiar enough with the ins and outs of the project to know if that would be a good idea or not.

[josevalim]

@jwilger looking at the earmark code you linked, it is not set verbatim: true to that particular node, so maybe that's what we should do? Can you please send a PR to earmark_parser and see if it works?

[jwilger]

In addition to looking into @josevalim's comment above, there's a somewhat kludgy workaround using CSS for anyone else who runs into this; just add the following to your mix.exs:

def project do
  [
    # ...
    docs: [
      # ...
      before_closing_head_tag: &before_closing_head_tag/1
    ]
  ]
end

defp before_closing_head_tag(:html) do
  """
  <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;
    }
  </style>
  """
end

defp before_closing_head_tag(_), do: ""

[josevalim]

Closing this, as I believe it is not an ExDoc issue!

[marick]

If you, like me, find your way to this issue because footnotes render like this:

... despite using markdown_processor: {ExDoc.Markdown.Earmark, footnotes: true} in mix.exs, two notes:

1. @jwilger's workaround above continues to work in current ExDoc (0.34.0). You get the desired ↩️.
2. However, the source of the footnote ([^1]) isn't styled to look like a footnote. The following works for me:

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

... but beware: I know barely any CSS.

[josevalim]

We probably need to add the CSS to ExDoc? Would you like to send a PR?

[bradhanks]

I submitted a PR to earmark_parser that I believe fixes this issue: RobertDober/earmark_parser#163