Components / Footnote

Footnote

Inline footnote primitive for blog MDX articles. Hover/focus shows a tooltip preview; an auto-injected list appears at the end of the article.

Section: Components

Use <Footnote/> inside MDX articles to attach citations to inline text. The marker is a real link to the entry at the bottom of the article. Hovering or focusing the marker reveals the full text in a Tooltip popover so readers don't have to leave the paragraph to read a citation.

Two modes

Definition (default): <Footnote id="1">...</Footnote> declares the footnote text. Reference: <Footnote ref="1" /> points back at a previously-declared id, useful when the same source is cited multiple times. The end-of-article list gets one entry per id, with a back-link for every marker that referenced it.

Live example

The EU AI Act applies to all high-risk AI systems 1 Footnote 1See Article 6 of Regulation (EU) 2024/1689, OJ L 2024/1689, 12 July 2024. , not just those that use deep-learning models. Article 10 elaborates on the training-data requirements 2 Footnote 2Article 10, paragraph 3, requires datasets to be "relevant, sufficiently representative, and to the best extent possible, free of errors." , and the same article is referenced again here1 to show the reference mode.

Hover any superscript marker to see the citation. The footnote list at the bottom of this card is auto-injected by the client script.

live-example.mdx | astro 
The EU AI Act applies to all high-risk AI systems<Footnote id="1">
  See <em>Article 6</em> of Regulation (EU) 2024/1689, OJ L 2024/1689, 12 July 2024.
</Footnote>, not just those that use deep-learning models. Article 10 elaborates
on the training-data requirements<Footnote id="2">
  Article 10, paragraph 3, requires datasets to be "relevant, sufficiently
  representative, and to the best extent possible, free of errors."
</Footnote>, and the same article is referenced again here<Footnote ref="1" />
to show the reference mode.

Usage in MDX

article.mdx | astro 
import Footnote from '@/components/blog/mdx/Footnote.astro';

The EU AI Act applies to all high-risk AI systems<Footnote id="1">
  See Article 6 of Regulation (EU) 2024/1689, OJ L 2024/1689.
</Footnote>.

...later in the same article, the same source again:

The same article<Footnote ref="1" /> defines high-risk categories in Annex III.

Auto-injected footnote list

You do not need to add a <FootnoteList /> component. A client-side enhancer (loaded by every BlogPostLayout) scans the article on astro:page-load and appends an <aside class="ypai-footnotes" role="doc-endnotes"> at the end of the .reading-surface. Each entry has a back-link (↩) per source marker so screen-reader users can return to the citation context.

Anatomy

Property Behavior
Marker Superscript `<a href="#fn-N">` — kebab-case id, hub-tinted color.
Tooltip Popover preview rendering the slot body (reuses the Tooltip primitive).
Entry Auto-injected list item at the end of `.reading-surface`. Includes a back-link (↩) per marker.
Backref Per-marker `<a>` inside the entry; clicking moves focus to the original marker.

Do / Don't

Property Do Don't
Citation length Quote the relevant sentence; link to the source for the full doc. Paste full PDF abstracts — the popover will dwarf the paragraph.
Reference reuse Use `ref` mode for the second-and-later citation of the same source. Duplicate the body via `id` — the back-link list becomes confusing.
Marker placement Place the marker immediately after the cited phrase, before punctuation. Drop the marker mid-word or in a place SR users cannot reach by Tab.
In-text emphasis Use `<em>` / `<strong>` inside the citation body for source titles. Apply heavy styling inside Footnote — it inherits article surface tokens.
Footnote list Trust the auto-injected list at the end of `.reading-surface`. Hand-roll a `<FootnoteList />` — the enhancer dedupes and back-links automatically.

Props

PropTypeDefaultNotes
idstring | number—Definition mode. Slot content is the citation body.
refstring | number—Reference mode. Must match an earlier id.

Tokens & styling

  • --hub-accent — superscript colour (per-article hub tint, falls back to #A855F7)
  • --ds-z-overlay — popover stacking (shared with Tooltip)
  • Respects prefers-reduced-motion: reduce (no fade)

Accessibility

  • Markers are real <a href="#fn-N"> anchors — screen readers announce "link, footnote N".
  • Each marker is wired via aria-describedby to the popover so SR users hear the citation body inline.
  • The aside has role="doc-endnotes" + aria-label="Footnotes".
  • Tooltip preview opens immediately on keyboard :focus (no 300 ms delay).
  • Esc dismisses the tooltip and blurs the marker.

Source

src/components/blog/mdx/Footnote.astro