Reference Footnotes

Annotated source

A footnote is a reference in the text and a definition anywhere in the document:

You write
A claim[^1], and a second one[^smith].

[^1]: The source, with a [link](https://example.com).
[^smith]: Smith, 2020.

You get
Compiles to
<p>
  A claim<sup
    ><a
      href="#fn-1"
      id="fnref-1"
      role="doc-noteref">1</a
    ></sup
  >, and a second one<sup
    ><a
      href="#fn-smith"
      id="fnref-2"
      role="doc-noteref">2</a
    ></sup
  >.
</p>
<section
  class="footnotes"
  role="doc-endnotes"
  aria-label="Footnotes"
>
  <ol>
    <li id="fn-1">
      <p>
        The source, with a <a
          href="https://example.com"
          >link</a
        >.
        <a
          href="#fnref-1"
          role="doc-backlink"
          aria-label="Back to reference 1"
          >↩︎</a
        >
      </p>
    </li>
    <li id="fn-smith">
      <p>
        Smith, 2020. <a
          href="#fnref-2"
          role="doc-backlink"
          aria-label="Back to reference 2"
          >↩︎</a
        >
      </p>
    </li>
  </ol>
</section>

The reference renders as a number that links to the note, and the notes are collected at the end of the document, in the order they are first referred to.

On the atlas: footnote.

A label is any run of characters without whitespace, brackets or ^. Labels match exactly, case included.

The number a reader sees comes from the order of the references, not from the label, so [^smith] is as good a label as [^2].

A definition is a line that starts with [^label]: and has text after it, or text on the lines below indented by four spaces, which is how Prettier writes a long one. It may hold links, emphasis, code and references to other notes.

It can be written anywhere: under the paragraph that cites it, at the end of the document, inside a block quote or a list item. Wherever it is, it renders in the section at the end.

A longer note continues as a list item does. After a blank line, a block indented by four spaces belongs to the note, and the first line that is not blank and not indented ends it:

[^1]: The source.

    A second paragraph, and a list:

    - one
    - two

Not part of the note.

Referring to a note twice gives both references the same number, and the note a link back to each.

The id of a note is fn- and its label, so a link to a note survives a renumbering. The id of a reference is fnref- and its number:

You write
## Fn 1

Text.[^1]

[^1]: A note.

You get
Compiles to
<h2>Fn 1</h2>
<p>
  Text.<sup
    ><a
      href="#fn-1"
      id="fnref-1"
      role="doc-noteref">1</a
    ></sup
  >
</p>
<section
  class="footnotes"
  role="doc-endnotes"
  aria-label="Footnotes"
>
  <ol>
    <li id="fn-1">
      <p>
        A note. <a
          href="#fnref-1"
          role="doc-backlink"
          aria-label="Back to reference 1"
          >↩︎</a
        >
      </p>
    </li>
  </ol>
</section>
mdsvex({ heading_ids: true });
You write
## Fn 1

Text.[^1]

[^1]: A note.

You get
Compiles to
<h2 id="fn-1">Fn 1</h2>
<p>
  Text.<sup
    ><a
      href="#fn-1-1"
      id="fnref-1"
      role="doc-noteref">1</a
    ></sup
  >
</p>
<section
  class="footnotes"
  role="doc-endnotes"
  aria-label="Footnotes"
>
  <ol>
    <li id="fn-1-1">
      <p>
        A note. <a
          href="#fnref-1"
          role="doc-backlink"
          aria-label="Back to reference 1"
          >↩︎</a
        >
      </p>
    </li>
  </ol>
</section>

With heading_ids, a heading keeps its id, and a note whose id a heading took moves aside instead: ## Fn 1 keeps fn-1 and the note [^1] becomes fn-1-1.

mdsvex adds no CSS and no heading. The section has the footnotes class and an accessible name.

The arrow of a back link is followed by a variation selector, so it is drawn as text and not as an emoji.

A reference is read by its syntax alone, before any definition is known. So a [^…] in prose that is not a footnote, such as the regular expression class [^abc], has to be escaped or put in code:

You write
The class \[^abc] matches, and so does `[^abc]`.

You get
Compiles to
<p>
  The class [^abc] matches, and so does <code
    >[^abc]</code
  >.
</p>

A reference with no definition, a label defined twice and a definition with no text fail the build with a FootnoteError. It has the code (footnote_undefined, footnote_duplicate or footnote_empty), the label, and the line and column of the reference or of the definition, and problems lists every one in the document:

You write src/routes/post.svx
A claim[^nope].

Its compile throws

Error the footnote reference [^nope] has no definition, add `[^nope]: text`, or escape the bracket as `\[^nope]` if it is not a footnote (/src/routes/post.svx:1)

You write
A claim[^a].

[^a]: The source.
[^a]: Another source.

Its compile throws

Error the footnote [^a] is defined twice, a label has one definition (/example.svx:4)

You write
A claim[^a].

[^a]:

Its compile throws

Error the footnote [^a] has no text, write it after `[^a]:` or on the lines below indented by four spaces (/example.svx:3)

A definition that nothing refers to is not rendered, and the compile warns with the code footnote_unused.

label names the section and back_label each link back, where {n} is the number of the reference.

mdsvex({
	footnotes: {
		label: 'Notes',
		back_label: 'Back to note {n}'
	}
});
You write
A claim[^1].

[^1]: The source.

You get
Compiles to
<p>
  A claim<sup
    ><a
      href="#fn-1"
      id="fnref-1"
      role="doc-noteref">1</a
    ></sup
  >.
</p>
<section
  class="footnotes"
  role="doc-endnotes"
  aria-label="Notes"
>
  <ol>
    <li id="fn-1">
      <p>
        The source. <a
          href="#fnref-1"
          role="doc-backlink"
          aria-label="Back to note 1"
          >↩︎</a
        >
      </p>
    </li>
  </ol>
</section>

strict: false turns the two errors into warnings: a reference with no definition is numbered and linked all the same, and the first definition of a label is the one that renders. That suits a preview of a document that is still being written.

mdsvex({ footnotes: { strict: false } });
You write
A claim[^1] and another[^2].

[^1]: The first.
[^1]: The second.

You get
Compiles to
<p>
  A claim<sup
    ><a
      href="#fn-1"
      id="fnref-1"
      role="doc-noteref">1</a
    ></sup
  >
  and another<sup
    ><a
      href="#fn-2"
      id="fnref-2"
      role="doc-noteref">2</a
    ></sup
  >.
</p>
<section
  class="footnotes"
  role="doc-endnotes"
  aria-label="Footnotes"
>
  <ol>
    <li id="fn-1">
      <p>
        The first. <a
          href="#fnref-1"
          role="doc-backlink"
          aria-label="Back to reference 1"
          >↩︎</a
        >
      </p>
    </li>
  </ol>
</section>

Two exports of a components module replace footnotes:

src/lib/markdown.js
export { default as footnote } from './markdown/Footnote.svelte';
export { default as footnotes } from './markdown/Footnotes.svelte';

footnote replaces a reference. It gets these props:

propvalue
childrenthe link it renders as without a replacement, the <sup>
notea snippet of what the definition holds
labelthe label, as written
numberits number
hrefthe link to the note, #fn- and the label
idthe id of the reference, fnref- and the number

note is what a side note or a hover card needs. A note holds blocks, and HTML allows no block inside the paragraph a reference is in, so draw it once the page is in the browser, as this card does on hover, or somewhere outside the paragraph:

src/lib/markdown/Footnote.svelte
<script>
	let { children, note } = $props();

	let open = $state(false);
</script>

<span
	class="footnote"
	role="group"
	onpointerenter={() => (open = true)}
	onpointerleave={() => (open = false)}
>
	{@render children()}{#if open}<span class="card">{@render note()}</span>{/if}
</span>

footnotes replaces the section and gets the <ol> of notes as its children:

src/lib/markdown/Footnotes.svelte
<script>
	let { children } = $props();
</script>

<aside class="notes" aria-label="Notes">
	<h2>Notes</h2>
	{@render children()}
</aside>
  • The links and the list that mdsvex writes for footnotes are not markdown, so a, sup, ol and li replacements never get them. What a note holds is markdown, so its paragraphs and links are replaced as anywhere else.
  • A reference inside a note snippet gets no snippet of its own.

See the footnotes playground example.

compile knows the whole document, so it can number the notes and move them. The streaming renderer does not: a reference shows its label as a superscript, and a definition renders where it is written, behind the same label.

Back to page index

mdsvex, markdown with Svelte in it. MIT licence.