Footnote support?

[matildepark]

Currently there's no way to inject markdown-it plugins down to the tokenizer, so we can't just pass markdown-it-footnotes here, but I can't see any facility for supporting Footnote syntax (which are common in GFM). Any current workarounds?

[mfix-stripe]

Hey @matildepark, check out this thread on why we aren't support footnotes, for now: #40

[zeel01]

While I see the desire to avoid additional dependencies, the markdown-it-footnotes syntax is greatly preferable to using a custom tag for this purpose. Not only is this syntax much less verbose, but I've seen it in use on a number of popular platforms, so using this syntax is much more familiar to users.
To that end, it seems like the best choice would be to either make it readily and easily possible to load makdown-it plugins within Markdoc, or preferably for Markdoc to add its own custom solution for footnotes using the same syntax.

[zeel01]

Aside: I don't think this should be marked as duplicate if #74 is being pointed here and the previous discussion regarding it was a Pull Request.

[jtbayly]

Just going to add that I am mostly interested in MarkDoc as a way to write books. Footnotes are essential for that some way or another.

[ntgussoni]

I think footnotes is a pretty regular thing for writers, specially those writing books. I can see most of us (i already have it in a todo list) implementing our own version of this. It's true that it can also be implemented with a regular link, but I believe the regular [^1] usage is widely spread

[OFranke]

So with my UnescapedHtml component in #10 (comment) I am able to create footnotes like this:

---
title: Example document showing documentation features
description: Explanation on how to use links, citations, ...
---

Explanation on how to use links, html, citations, ...

---

## Citations & Footnotes

Some important reference text linking to a footnote {% html htmlWrapperTag="span" %} <a href="#ref1">[1]</a> {% /html %}.

Some other important reference text linking to a footnote {% html htmlWrapperTag="span" %} <a href="#ref2">[2]</a> {% /html %}.

## Footnotes

{% html htmlWrapperTag="div" %}

<div>
    <span id="ref1">[1]:</span> <a href="/link-to-paper-1">Paper description 1</a>
</div>
<div>
    <span id="ref2">[2]:</span> <a href="/link-to-paper-2">Paper description 2</a>
</div>
{% /html %}

@mfix-stripe @rpaul-stripe So I could create another tag that would enforce styling consistency across the footnote but I wonder, is there any better/more framework-native approach on how I could create footnotes?

The trouble I am facing with this solution is that I manually need to count up the references in the text. For the actual footnotes I could create a special tag that selects the references by a specific ID and then display those references. But all that does not feel very elegant.

I'd be happy if you can point me in a better direction here.

@matildepark Here's your workaround :)

[matildepark]

Once you're manually doing the work of injecting the footnotes and their corresponding citation in HTML in the Markdown you might as well just write your article in HTML and not Markdown.

@OFranke here is what we do as per discussion in #40.

[OFranke]

Once you're manually doing the work of injecting the footnotes and their corresponding citation in HTML in the Markdown you might as well just write your article in HTML and not Markdown.

Yes youre absolutely right. For me this is just a simple workaround to get it done.

Thanks for the link to the urbit repo, I see there's a custom fork of markdoc. I'll have a look into that, thank you! I am using markdoc with nextjs integration so I am not quite sure if there's a way to hook into the AST parsing for customizing.

[matildepark]

I see there's a custom fork of markdoc.

All that's in the fork is merging the html-support branch and also adding markdown-it-sup to the parser for superscript.

[nkohari-stripe]

IMO, this is something best left to users to customize. There are lots of different ways a note can be displayed (section footnote, endnote, asides, etc.) so I think it'd be challenging to provide a one-size-fits-all solution.

I've solved this problem using a pretty simple implementation of a {% note %} tag, which serves two roles depending on whether it has children. I then display the content as endnotes. The syntax looks like this:

Lorum ipsum dolor sit amet. {% note #1 /%}

...

{% note #1 %}Here is the footnote.{% /note %}

Personally, I think this is easier to understand than a custom syntax, and much more versatile!

If you're interested, you can see the implementation here:

• Markdoc tag: https://github.com/nkohari/nate.io/blob/master/src/tags/note.ts
• React component: https://github.com/nkohari/nate.io/blob/master/src/components/Note.tsx

Another approach would be to write the {% note %} content inline, and walk the Markdoc AST before transformation, extracting the content and rendering it in the "shell" of your application. I don't do this with footnotes, but I do something similar with images to support preloading.

[mfix-stripe]

For the time being, we are encouraging folks to follow the pattern @nkohari-stripe described above (#70 (comment)), so I am going to close this issue. We can revisit this further down the road if we see other needs.

[lschierer]

Do you have any idea where I would drop those files in an Astro project to get them to be picked up?

[nick-kang]

@nkohari-stripe - Thanks for the example! How are you getting the tag to recognize #1 as an id without doing {% note id=#1 %}?

Also curious why did you put this block in here? If the footnote was a link, it would just render as plain text. https://github.com/nkohari/nate.io/blob/6b0044f08237449c302bfbc2d7036c67ffa81aac/src/tags/note.ts#L14-L16

edit: Is it to prevent rendering a <p>?