Footnotes and Definitions

GFM Footnotes

Footnotes are a GitHub site feature, also supported by Pandoc, Markdown Extra, MultiMarkdown, GitLab, and Obsidian. They are not in CommonMark and not in the GFM spec.

A reference in the text, a definition anywhere in the document.

Here is a claim that needs a citation.[^1]

And another one.[^note]

[^1]: The definition. It can appear anywhere in the file.
[^note]: Labels can be words, which is easier to maintain than numbers.

Behavior:

• The rendered marker is renumbered in document order, so [^1], [^note], [^99] become 1, 2, 3 in the output.
• Definitions are collected and printed at the bottom of the document with a back link, regardless of where they sit in the source.
• Labels are case insensitive and may not contain spaces or brackets.
• A reference with no matching definition renders as literal [^1] text.
• A definition never referenced is silently dropped.

Multi-paragraph and multi-block footnotes work by indenting the continuation four spaces.

Some claim.[^long]

[^long]: The first paragraph of the note.

    A second paragraph, indented four spaces.

    - a list inside the footnote
    - another item

Inline Footnotes

Pandoc and a few other renderers allow the note text at the point of use, with no separate definition. GitHub does not support this.

Here is a claim.^[This is an inline footnote, Pandoc only.]

On GitHub that renders literally, caret and brackets included. Avoid it in anything hosted on a Git forge.

Footnotes Where They Are Unsupported

In a renderer without footnote support, the reference and the definition both render as visible bracketed text, which reads badly. The portable substitutes:

Here is a claim.[1]

...

**References**

1. Source of the claim, https://example.com

Here is a claim ([source](https://example.com)).

For a README, a parenthetical link is almost always better than a footnote. Footnotes earn their place in long-form documents rendered by a pipeline you control.

Definition Lists

Definition lists are not CommonMark, not GFM, and not supported on GitHub. They exist in Pandoc, Markdown Extra, MultiMarkdown, kramdown, and Obsidian.

The common syntax: the term on one line, then a line starting with : and a space.

Term
: The definition of the term.

Another term
: Its definition.
: A second definition for the same term.

Pandoc also accepts a tilde in place of the colon, and allows a blank line between the term and the definition to produce a loose list.

Term
~ The definition, Pandoc's alternative marker.

Term

: A definition after a blank line, which renders loose.

Multi-block definitions indent the continuation.

Term
: The first paragraph of the definition.

  A second paragraph, indented two spaces.

  ```bash
  a code block inside a definition
  ```

Definition Lists on GitHub

Since the syntax is unsupported, the choices are a raw HTML dl (which GitHub's sanitizer permits) or a substitute structure.

<dl>
  <dt>Term</dt>
  <dd>The definition of the term.</dd>
  <dt>Another term</dt>
  <dd>Its definition.</dd>
</dl>

- **Term**: the definition of the term.
- **Another term**: its definition.

| Term | Definition |
|------|------------|
| `--verbose` | Print more output. |
| `--quiet` | Print nothing but errors. |

For API and flag documentation, the table form is the most common in practice, because it renders everywhere and sorts and diffs cleanly. The bold-label bullet form is better when definitions run longer than a line.

Abbreviations

Another Markdown Extra and MultiMarkdown extension, not supported by CommonMark, GFM, or GitHub. It defines an abbreviation once and adds a tooltip at every occurrence.

The HTML spec and the W3C both say so.

*[HTML]: HyperText Markup Language
*[W3C]:  World Wide Web Consortium

On GitHub the definition lines render as literal text with a stray asterisk, which looks like a mistake. Where you need this and cannot rely on the extension, spell the term out on first use and use the acronym after, which is better writing anyway.

Support at a Glance

The practical rule: if a feature is not in the CommonMark spec, check the exact renderer before relying on it, and prefer a construct that degrades to readable text rather than to visible punctuation.