Footnote

Footnote turns GFM footnote markup ([^1] references and [^1]: text definitions) into dedicated Plate nodes you can insert, repair, and jump between. The reference is an inline void <sup>; the definition is a block at the end of the document. Paired with MarkdownPlugin and remark-gfm, references and definitions round-trip as real footnote markdown instead of fallback text.

Features

• GFM-compatible footnote references and definitions as dedicated Plate nodes.
• One-transform insertion with automatic numeric identifier allocation.
• [^ inline combobox for insertion from the default UI kit.
• Recreate a missing definition from an unresolved reference without duplicating.
• Keep the first duplicate definition canonical; renumber later duplicates on demand.
• Navigation helpers that jump between reference and definition with a landed-target flash.

Kit Usage

Installation

The fastest way to add footnote-aware markdown is with the MarkdownKit, which includes MarkdownPlugin, the footnote plugins wired for the default markdown profile, and works with Plate UI.

Add Kit

import { createPlateEditor } from 'platejs/react';
import { MarkdownKit } from '@/components/editor/plugins/markdown-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...MarkdownKit,
  ],
});

Manual Usage

Installation

npm install @platejs/footnote @platejs/markdown remark-gfm

Add Plugins

Three plugins ship together: the inline reference, the block definition, and the combobox input. Pair them with MarkdownPlugin and remark-gfm so [^1] round-trips correctly.

import {
  FootnoteDefinitionPlugin,
  FootnoteReferencePlugin,
} from '@platejs/footnote/react';
import { MarkdownPlugin } from '@platejs/markdown';
import { createPlateEditor } from 'platejs/react';
import remarkGfm from 'remark-gfm';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    FootnoteReferencePlugin,
    FootnoteDefinitionPlugin,
    MarkdownPlugin.configure({
      options: {
        remarkPlugins: [remarkGfm],
      },
    }),
  ],
});

FootnoteReferencePlugin pulls in FootnoteInputPlugin automatically — that's the inline void rendered while the reader is typing inside the [^ combobox.

Insert a Footnote

Call tf.insert.footnote at the current selection. It inserts the reference, creates a matching definition at the end of the document, and moves the caret into the definition body so the reader can start writing:

editor.tf.insert.footnote();

When the selection is expanded, the expanded fragment seeds the definition body so you can select text and "footnote-ify" it in one shot.

Pass focusDefinition: false when the reference should stay inline (for example, inside a larger template):

editor.tf.insert.footnote({ focusDefinition: false });

Pass identifier to reuse an existing identifier; the transform skips creating a duplicate definition when one already exists.

Repair an Unresolved Reference

When a reference points at an identifier with no definition (e.g. pasted from elsewhere), use tf.footnote.createDefinition to create just the definition — without inserting another reference:

editor.tf.footnote.createDefinition({ identifier: '3' });

Pass focus: false when you want to leave the caret where it was:

editor.tf.footnote.createDefinition({ focus: false, identifier: '3' });

Navigate Between Reference and Definition

tf.footnote.focusDefinition and tf.footnote.focusReference jump the selection, scroll the target into view, and flash it through Navigation Feedback. No extra wiring needed:

editor.tf.footnote.focusDefinition({ identifier: '3' });
editor.tf.footnote.focusReference({ identifier: '3' });

When a single definition is pointed at by multiple references, pass index to pick which one to land on:

editor.tf.footnote.focusReference({ identifier: '3', index: 1 });

Both transforms return false when the identifier doesn't resolve, so you can branch on stale links without throwing.

Handle Duplicate Definitions

Two definitions with the same identifier is a resolvable edit state, not an error. The first definition in document order stays canonical; later ones are flagged as duplicates. Renumber a later duplicate with:

const nextIdentifier = editor.tf.footnote.normalizeDuplicateDefinition({
  path: duplicatePath,
});

The transform returns the newly assigned identifier string on success, or false when the path isn't a duplicate definition or the requested identifier is already taken. Pass identifier to target a specific free identifier instead of the next available one.

Customize Rendering

Swap in your own React components with withComponent:

import {
  FootnoteDefinitionPlugin,
  FootnoteReferencePlugin,
} from '@platejs/footnote/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    FootnoteReferencePlugin.withComponent(MyFootnoteReference),
    FootnoteDefinitionPlugin.withComponent(MyFootnoteDefinition),
  ],
});

The package owns node semantics, identifier allocation, and navigation helpers. App-level surfaces — hover previews, the [^ combobox, slash-command entries, toolbar buttons — are built on top of the transforms and API methods below.

Plugins

FootnoteReferencePlugin

Inline void node rendered as <sup>. Owns the [^ combobox trigger, identifier registry, navigation transforms, and query API. Automatically includes FootnoteInputPlugin.

FootnoteDefinitionPlugin

Block node for footnote definitions. Lives at the bottom of the document and carries the identifier + body content.

FootnoteInputPlugin

Inline void used as the live combobox input while the reader is typing [^…. Pulled in automatically by FootnoteReferencePlugin; add it directly only if you render the combobox yourself.

API

All API methods hang off editor.api.footnote. Reads go through a lazy per-editor registry that rebuilds only when a footnote operation invalidates it, so hover previews and navigation stay cheap even when a single definition has many references.

api.footnote.definition

Get the canonical (first-in-document-order) definition entry for an identifier.

api.footnote.definitions

Get every definition entry that shares an identifier, in document order. When duplicates exist, the first entry is canonical; later entries are duplicates.

api.footnote.definitionText

Get the plain-text content of the canonical definition. Ideal for hover previews — reads straight from live definition nodes, no copied state.

api.footnote.references

Get every reference entry that points at an identifier, in document order.

api.footnote.identifiers

List every identifier that has at least one definition, in document order.

api.footnote.nextId

Compute the next free numeric identifier. Used by tf.insert.footnote when the caller doesn't supply one.

api.footnote.isResolved

Check whether an identifier has at least one definition.

api.footnote.duplicateDefinitions

Get every non-canonical definition entry for an identifier — that is, every definition after the first in document order.

api.footnote.duplicateIdentifiers

List every identifier that has more than one definition.

api.footnote.hasDuplicateDefinitions

Check whether an identifier has more than one definition.

api.footnote.isDuplicateDefinition

Check whether a given definition path is a later duplicate (not the canonical one).

Transforms

tf.insert.footnote

Insert a footnote reference at the current selection, create a matching definition if one doesn't already exist, and focus the definition body.

When the selection is expanded, the expanded fragment seeds the new definition body so you can convert selected prose into a footnote in one call.

tf.footnote.createDefinition

Create the missing definition for an existing identifier without inserting another reference. Returns the path of the definition — the newly created one, or the existing one when the identifier already resolves.

tf.footnote.focusDefinition

Jump the selection into the canonical definition body, scroll it into view, and flash it through Navigation Feedback.

tf.footnote.focusReference

Jump the selection to the matching reference, scroll it into view, and flash it through Navigation Feedback.

tf.footnote.normalizeDuplicateDefinition

Renumber a later duplicate definition so the canonical definition stays intact. Pass the path of the duplicate; optionally pass a specific identifier to target, otherwise the transform picks api.footnote.nextId().

Related Docs

• Markdown
• Navigation Feedback
• Editor Methods