{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "footnote-docs",
"title": "Footnote",
"description": "Documentation for Footnote",
"files": [
{
"path": "../../content/docs/(plugins)/(elements)/footnote.mdx",
"content": "---\ntitle: Footnote\ndocs:\n - route: /docs/markdown\n title: Markdown\n - route: /docs/navigation-feedback\n title: Navigation Feedback\n---\n\n\n\nFootnote 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 ``; 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.\n\n\n\n## Features\n\n- GFM-compatible footnote references and definitions as dedicated Plate nodes.\n- One-transform insertion with automatic numeric identifier allocation.\n- `[^` inline combobox for insertion from the default UI kit.\n- Recreate a missing definition from an unresolved reference without duplicating.\n- Keep the first duplicate definition canonical; renumber later duplicates on demand.\n- Navigation helpers that jump between reference and definition with a landed-target flash.\n\n\n\n## Kit Usage\n\n\n\n### Installation\n\nThe 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](/docs/installation/plate-ui).\n\n\n\n### Add Kit\n\n```tsx\nimport { createPlateEditor } from 'platejs/react';\nimport { MarkdownKit } from '@/components/editor/plugins/markdown-kit';\n\nconst editor = createPlateEditor({\n plugins: [\n // ...otherPlugins,\n ...MarkdownKit,\n ],\n});\n```\n\n\n\n## Manual Usage\n\n\n\n### Installation\n\n```bash\nnpm install @platejs/footnote @platejs/markdown remark-gfm\n```\n\n### Add Plugins\n\nThree 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.\n\n```tsx\nimport {\n FootnoteDefinitionPlugin,\n FootnoteReferencePlugin,\n} from '@platejs/footnote/react';\nimport { MarkdownPlugin } from '@platejs/markdown';\nimport { createPlateEditor } from 'platejs/react';\nimport remarkGfm from 'remark-gfm';\n\nconst editor = createPlateEditor({\n plugins: [\n // ...otherPlugins,\n FootnoteReferencePlugin,\n FootnoteDefinitionPlugin,\n MarkdownPlugin.configure({\n options: {\n remarkPlugins: [remarkGfm],\n },\n }),\n ],\n});\n```\n\n`FootnoteReferencePlugin` pulls in `FootnoteInputPlugin` automatically — that's the inline void rendered while the reader is typing inside the `[^` combobox.\n\n### Insert a Footnote\n\nCall `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:\n\n```tsx\neditor.tf.insert.footnote();\n```\n\nWhen the selection is expanded, the expanded fragment seeds the definition body so you can select text and \"footnote-ify\" it in one shot.\n\nPass `focusDefinition: false` when the reference should stay inline (for example, inside a larger template):\n\n```tsx\neditor.tf.insert.footnote({ focusDefinition: false });\n```\n\nPass `identifier` to reuse an existing identifier; the transform skips creating a duplicate definition when one already exists.\n\n### Repair an Unresolved Reference\n\nWhen 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:\n\n```tsx\neditor.tf.footnote.createDefinition({ identifier: '3' });\n```\n\nPass `focus: false` when you want to leave the caret where it was:\n\n```tsx\neditor.tf.footnote.createDefinition({ focus: false, identifier: '3' });\n```\n\n### Navigate Between Reference and Definition\n\n`tf.footnote.focusDefinition` and `tf.footnote.focusReference` jump the selection, scroll the target into view, and flash it through [Navigation Feedback](/docs/navigation-feedback). No extra wiring needed:\n\n```tsx\neditor.tf.footnote.focusDefinition({ identifier: '3' });\neditor.tf.footnote.focusReference({ identifier: '3' });\n```\n\nWhen a single definition is pointed at by multiple references, pass `index` to pick which one to land on:\n\n```tsx\neditor.tf.footnote.focusReference({ identifier: '3', index: 1 });\n```\n\nBoth transforms return `false` when the identifier doesn't resolve, so you can branch on stale links without throwing.\n\n### Handle Duplicate Definitions\n\nTwo 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:\n\n```tsx\nconst nextIdentifier = editor.tf.footnote.normalizeDuplicateDefinition({\n path: duplicatePath,\n});\n```\n\nThe 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.\n\n### Customize Rendering\n\nSwap in your own React components with `withComponent`:\n\n```tsx\nimport {\n FootnoteDefinitionPlugin,\n FootnoteReferencePlugin,\n} from '@platejs/footnote/react';\nimport { createPlateEditor } from 'platejs/react';\n\nconst editor = createPlateEditor({\n plugins: [\n FootnoteReferencePlugin.withComponent(MyFootnoteReference),\n FootnoteDefinitionPlugin.withComponent(MyFootnoteDefinition),\n ],\n});\n```\n\nThe 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.\n\n\n\n## Plugins\n\n### `FootnoteReferencePlugin`\n\nInline void node rendered as ``. Owns the `[^` combobox trigger, identifier registry, navigation transforms, and query API. Automatically includes `FootnoteInputPlugin`.\n\n\n\n \n Character that opens the footnote combobox.\n - **Default:** `'^'`\n \n \n Only trigger when the previous character matches. The default requires `[` so bare `^` in prose doesn't open the combobox.\n - **Default:** `/^\\[$/`\n \n TElement\" optional>\n Factory for the node inserted when the combobox opens. Defaults to a `footnoteInput` element.\n \n boolean\" optional>\n Extra predicate gating the combobox. Return `false` to suppress triggering at the current selection.\n \n\n\n\n### `FootnoteDefinitionPlugin`\n\nBlock node for footnote definitions. Lives at the bottom of the document and carries the identifier + body content.\n\n\n\n### `FootnoteInputPlugin`\n\nInline 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.\n\n\n\n## API\n\nAll 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.\n\n### `api.footnote.definition`\n\nGet the canonical (first-in-document-order) definition entry for an identifier.\n\n\n\n \n Footnote identifier.\n \n\n\n | undefined\">\n Canonical definition entry, or `undefined` when nothing matches.\n \n\n\n\n### `api.footnote.definitions`\n\nGet every definition entry that shares an identifier, in document order. When duplicates exist, the first entry is canonical; later entries are duplicates.\n\n\n\n \n Footnote identifier.\n \n\n\n []\">\n Definition entries in document order.\n \n\n\n\n### `api.footnote.definitionText`\n\nGet the plain-text content of the canonical definition. Ideal for hover previews — reads straight from live definition nodes, no copied state.\n\n\n\n \n Footnote identifier.\n \n\n\n \n Definition text, or `undefined` when no definition exists.\n \n\n\n\n### `api.footnote.references`\n\nGet every reference entry that points at an identifier, in document order.\n\n\n\n \n Footnote identifier.\n \n\n\n []\">\n Reference entries in document order.\n \n\n\n\n### `api.footnote.identifiers`\n\nList every identifier that has at least one definition, in document order.\n\n\n\n \n Defined identifiers.\n \n\n\n\n### `api.footnote.nextId`\n\nCompute the next free numeric identifier. Used by `tf.insert.footnote` when the caller doesn't supply one.\n\n\n\n \n Next free identifier (e.g. `'1'`, `'2'`).\n \n\n\n\n### `api.footnote.isResolved`\n\nCheck whether an identifier has at least one definition.\n\n\n\n \n Footnote identifier.\n \n\n\n \n `true` when at least one definition exists for the identifier.\n \n\n\n\n### `api.footnote.duplicateDefinitions`\n\nGet every non-canonical definition entry for an identifier — that is, every definition after the first in document order.\n\n\n\n \n Footnote identifier.\n \n\n\n []\">\n Definition entries past the canonical one.\n \n\n\n\n### `api.footnote.duplicateIdentifiers`\n\nList every identifier that has more than one definition.\n\n\n\n \n Identifiers with duplicate definitions.\n \n\n\n\n### `api.footnote.hasDuplicateDefinitions`\n\nCheck whether an identifier has more than one definition.\n\n\n\n \n Footnote identifier.\n \n\n\n \n `true` when two or more definitions share the identifier.\n \n\n\n\n### `api.footnote.isDuplicateDefinition`\n\nCheck whether a given definition path is a later duplicate (not the canonical one).\n\n\n\n \n Path of the definition to check.\n \n\n\n \n `true` when the node at `path` is a footnote definition past the canonical one.\n \n\n\n\n## Transforms\n\n### `tf.insert.footnote`\n\nInsert a footnote reference at the current selection, create a matching definition if one doesn't already exist, and focus the definition body.\n\nWhen the selection is expanded, the expanded fragment seeds the new definition body so you can convert selected prose into a footnote in one call.\n\n\n\n \n Reuse an existing identifier. Defaults to `api.footnote.nextId()`.\n \n \n Focus the definition body after insertion. Pass `false` to keep the caret inline after the reference.\n - **Default:** `true`\n \n \n Standard insert-nodes options (`at`, `select`, etc.) forwarded to the reference insert.\n \n\n\n\n### `tf.footnote.createDefinition`\n\nCreate 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.\n\n\n\n \n Identifier to create a definition for.\n \n \n Focus the definition body after creation.\n - **Default:** `true`\n \n\n\n \n Path of the resolved definition.\n \n\n\n\n### `tf.footnote.focusDefinition`\n\nJump the selection into the canonical definition body, scroll it into view, and flash it through Navigation Feedback.\n\n\n\n \n Footnote identifier.\n \n\n\n \n `false` when no definition resolves, `true` otherwise.\n \n\n\n\n### `tf.footnote.focusReference`\n\nJump the selection to the matching reference, scroll it into view, and flash it through Navigation Feedback.\n\n\n\n \n Footnote identifier.\n \n \n Pick a specific reference when the definition is pointed at by several. Indexed by document order.\n - **Default:** `0`\n \n\n\n \n `false` when the reference doesn't resolve, `true` otherwise.\n \n\n\n\n### `tf.footnote.normalizeDuplicateDefinition`\n\nRenumber 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()`.\n\n\n\n \n Path of the duplicate definition to renumber.\n \n \n Target identifier. Must be free. Defaults to `api.footnote.nextId()`.\n \n\n\n \n The assigned identifier on success, or `false` when the path isn't a duplicate definition or the target identifier is already taken.\n \n\n\n\n## Related Docs\n\n- [Markdown](/docs/markdown)\n- [Navigation Feedback](/docs/navigation-feedback)\n- [Editor Methods](/docs/editor-methods)\n",
"type": "registry:file",
"target": "content/docs/plate/(plugins)/(elements)/footnote.mdx"
}
],
"type": "registry:file"
}