[Feature Request]: Support for Footnotes or Fancy Callouts in Tables

[reakaleek]

Additional Context

This feature would be beneficial for providing additional context or caveats directly in documentation tables, rather than forcing authors or readers to jump elsewhere on the page. This approach is already adopted in some other documentation ecosystems.

Alternative Solutions

The workaround is to use inline numbering in tables and describe them in a numbered list afterwards, but this is not user-friendly and can become unwieldy in complex documentation tables.

Examples and Research

• Example featuring callout annotation in a table: https://www.elastic.co/docs/deploy-manage/tools/snapshot-and-restore#index-compatibility
• Markup pattern from our docs: https://github.com/elastic/docs-content/blob/main/deploy-manage/tools/snapshot-and-restore.md?plain=1#L161-L174
• Callouts in tables are supported in some external tools/documentation sites.

How important is this feature to you?

"Important"

What problem are you trying to solve?

Currently, there is no support for including footnotes or special callouts within tables in our documentation, unlike the support for footnotes/code callouts elsewhere. As discussed in internal conversations, the current workaround is to use plain numbers like (1), (2) in the table body, and then explain them later as a numbered list below the table—this is not very elegant or scalable for complex docs.

Proposed Solution

Add first-class support in docs-builder for table cell footnotes, or the ability to reference callouts/notes directly within table cells (possibly rendered as superscript-style links or tooltip-style annotations). Ideally this would work similarly to how we handle code callouts or like the callout pattern used here: https://www.elastic.co/docs/deploy-manage/tools/snapshot-and-restore#index-compatibility.

Prerequisites

false,false

View original Slack conversation

[cotti]

AI triage

Automated investigation against the current codebase. A human still needs to confirm before any code change.

Original concern

Authors want footnotes and/or richer "callout" annotations inside table cells (rendered as superscript links or tooltip-style notes), instead of the current workaround of (1)/(2) markers in the cell plus a numbered list below the table.

Findings

• src/Elastic.Markdown/Myst/MarkdownParser.cs:173 — footnotes are enabled in the main pipeline (.UseFootnotes(); also :151 in the minimal pipeline), so footnote references [^x] are a supported inline construct. Added in PR #2275.
• src/Elastic.Markdown/IO/MarkdownFile.cs:454-470 — footnote definitions are always collected into a single page-level <div class="footnotes"> block at the bottom of the page (the Footnotes heading is injected there), not inline near the reference. docs/syntax/footnotes.md:137 documents this: definitions live at the document level and "always render at the bottom of the page." Tests confirm references work inside containers while definitions stay document-level (tests/Elastic.Markdown.Tests/Inline/FootnotesTests.cs:329-378).
• src/Elastic.Markdown/Myst/MarkdownParser.cs:185,192 — tables come from .UsePipeTables() with no grid-table extension, and .DisableHtml() strips raw HTML. Pipe-table cells are therefore inline-only: block content (admonitions / "fancy callouts", lists, multi-paragraph notes) cannot be placed in a cell. This is the same inline-only-cell limitation behind the tables cluster below.
• src/Elastic.Markdown/Myst/Directives/Table/TableDirectiveBlock.cs:12-18,57-66 — the {table} directive (PR #2852) only wraps a pipe table to control column widths; it requires exactly one pipe table and does not change the cell content model.

Verdict

Needs stakeholder input

Footnote references are inline and the superscript styling already exists (.footnote-ref sup in Assets/markdown/footnotes.css), so a [^x] placed in a cell may already render a superscript link — but the note text always collects at the page bottom rather than appearing as an in-table or tooltip annotation, which is the UX this request describes. The "fancy callouts" half (block-level admonitions in a cell) is blocked outright by the inline-only pipe-table cell model. Delivering this means choosing an author-facing syntax and a reader-facing rendering/interaction, plus working around the cell content-model blocker — a design-and-architecture feature, not a quick fix.

Proposal

Open questions grouped by audience:

• Writer (authoring syntax): Should authors reuse footnote refs ([^x]) inside cells (definitions still at page bottom)? A new per-table "annotations/notes" block? Or code-callout-style (1) markers with a structured companion list that the builder pairs automatically? What's the migration story for the existing (1)+list workaround?
• UX (reader rendering): How should an in-cell annotation appear — a superscript link to page-bottom footnotes (today's footnote behavior), an inline tooltip/popover anchored near the cell, or a notes block rendered directly beneath the table? Plus accessibility of superscript/tooltip annotations.
• Engineering constraint (known, not an open ask): Block content in cells would require grid-table support or a custom cell content model and an AOT-safe renderer; .DisableHtml() removes the raw-HTML escape hatch. This is the shared cluster blocker, so any solution here should be designed alongside the cluster.

Related issues

Part of a broader tables cluster, all open and all rooted in inline-only pipe-table cells / table rendering limits:

• List support in table cells #508 — list support in table cells
• [Feature Request]: Improved ES|QL examples output table formatting #718 — improved ES|QL examples output table formatting
• [Feature Request]: Render lists like tables #2734 — render lists like tables
• [Discuss] Tables #112 — [Discuss] Tables (umbrella)
• Changelog table column width causes horizontal scrolling with no visual cue #3376 — table column-width horizontal scrolling

Maintainers may want to plan a coherent fix across these and consider a cluster:tables label (label creation is out of scope for this triage).

Notes

• Worth verifying directly whether [^x] already renders inside a pipe-table cell — no test or doc covers footnotes-in-tables today; document the outcome either way.
• The referenced example (snapshot-and-restore) is the manual (1)+list workaround in action, i.e. the pattern this request wants to make first-class.