footnote: list at the end of a page (#1497)

\

Author: MykolaGolubyev

znai-docs/znai/flow/footnotes.md

@@ -18,9 +18,24 @@ To add a reference to the footnote use `[^my-id]` which will result in [^my-id]
     Constructor()
     ```
 
-Note: numeric footnotes are treated as text footnotes, and they will be assigned the auto incremented 
+Note: numeric footnotes are treated as text footnotes, and they will be assigned the auto incremented
 number in order of appearance.
 
 # Preview
 
 Hover mouse over a footnote reference see its content in a tooltip.
+
+# Footnotes List
+
+A footnotes list is automatically appended at the end of the page when footnotes are present.
+Clicking the number in the list navigates back to the reference [^another-note].
+
+[^another-note]: This is another footnote to demonstrate the list with multiple entries.
+
+To hide the footnotes list, set `hideFootnoteList` to `true` in `meta.json`:
+
+```json {title: "meta.json"}
+{
+  "hideFootnoteList": true
+}
+```

znai-docs/znai/meta.json

@@ -4,6 +4,7 @@
   "category": "Documentation",
   "description": "Build functional, maintainable, beautiful User Guides with markdown and Znai plugins. Instant pages navigation. Local search. Multiple integrations to work with Python, Java, C++, OpenAPI, etc. Transform \"getting started\" sections into slideshow for your workshops. Manage multiple documentations with self-deployed znai hub.",
   "hidePresentationTrigger": false,
+  "hideFootnoteList": false,
   "viewOn": {
     "link": "https://github.com/testingisdocumenting/znai/blob/master/znai-docs/znai",
     "title": "View Markdown"

znai-docs/znai/release-notes/1.88/add-2026-04-13-footnote-list.md

@@ -0,0 +1 @@
+* Add: Footnote list at the end of the page in addition to footnote on hover

znai-reactjs/src/App.css

@@ -131,6 +131,7 @@
     --znai-footnote-preview-background-color: hsl(212, 95%, 94%);
     --znai-footnote-preview-label-background-color: hsl(212, 95%, 90%);
     --znai-footnote-preview-border-color: hsl(212, 95%, 77%);
+    --znai-footnotes-list-border-color: hsl(0, 0%, 92%);
 
     --znai-search-box-text-color: #777;
     --znai-search-box-background-color: #eee;

znai-reactjs/src/doc-elements/DefaultElementsLibrary.jsx

@@ -88,6 +88,7 @@ import { ApiLinkedTextBlock } from "./api/ApiLinkedTextBlock";
 import { OpenApiMethodAndUrl } from "./open-api/OpenApiMethodAndUrl";
 import { Card } from "./card/Card";
 import { FootnoteReference } from "./footnote/FootnoteReference";
+import { FootnoteBackLinks } from "./footnote/FootnotesList";
 import { EmbeddedHtml } from "./html/EmbeddedHtml";
 import { Asciinema } from "./asciinema/Asciinema";
 import { ReadMore } from "./read-more/ReadMore.js";
@@ -180,6 +181,7 @@ library.AnnotatedImageWithOrderedList = AnnotatedImageWithOrderedList
 library.Card = Card;
 
 library.FootnoteReference = FootnoteReference;
+library.FootnoteBackLinks = FootnoteBackLinks;
 
 library.Tabs = Tabs
 presentationElementHandlers.Tabs = presentationTabsHandler

znai-reactjs/src/doc-elements/Documentation.jsx

@@ -35,9 +35,10 @@ import PresentationRegistry from "./presentation/PresentationRegistry";
 
 import AllPagesAtOnce from "./AllPagesAtOnce";
 
-import { mergeDocMeta } from "../structure/docMeta";
+import { mergeDocMeta, isFootnoteListHidden } from "../structure/docMeta";
 
 import { pageContentProcessor } from "./pageContentProcessor.js";
+import { FootnotesList } from "./footnote/FootnotesList";
 
 import { DocumentationModes } from "./DocumentationModes";
 import { pageTypesRegistry } from "./page/PageTypesRegistry";
@@ -203,6 +204,11 @@ export class Documentation extends React.Component {
       />
     );
 
+    const footnotes = isFootnoteListHidden() ? [] : pageContentProcessor.extractFootnotes(page.content);
+    const renderedFootnotesList = footnotes.length > 0 ? (
+      <FootnotesList footnotes={footnotes} elementsLibrary={elementsLibrary} />
+    ) : null;
+
     const NextPrevNavigation = pageTypesRegistry.nextPrevNavigationComponent(page.tocItem);
     const renderedNextPrevNavigation = (
       <NextPrevNavigation
@@ -255,6 +261,7 @@ export class Documentation extends React.Component {
             nextPageTocItem={this.nextPageTocItem}
             searchPopup={searchPopup}
             renderedPage={renderedPage}
+            renderedFootnotesList={renderedFootnotesList}
             renderedNextPrevNavigation={renderedNextPrevNavigation}
             renderedFooter={renderedFooter}
             onHeaderClick={this.onHeaderClick}

znai-reactjs/src/doc-elements/footnote/Footnote.demo.tsx

@@ -18,6 +18,7 @@ import React from "react";
 
 import { elementsLibrary } from "../DefaultElementsLibrary";
 import { FootnoteReference } from "./FootnoteReference";
+import { FootnotesList } from "./FootnotesList";
 import { Registry } from "react-component-viewer";
 import { TooltipRenderer } from "../../components/Tooltip";
 import { FootnotePreview } from "./FootnotePreview";
@@ -54,6 +55,16 @@ export function footnoteDemo(registry: Registry) {
       </div>
     );
   });
+
+  registry.add("footnotes list", () => (
+    <FootnotesList
+      elementsLibrary={elementsLibrary}
+      footnotes={[
+        { label: "1", content: footnoteContent(), refCount: 1 },
+        { label: "2", content: longerFootnoteContent(), refCount: 3 },
+      ]}
+    />
+  ));
 }
 
 function footnoteContent() {

znai-reactjs/src/doc-elements/footnote/FootnoteReference.css

@@ -27,3 +27,8 @@
    padding-left: 2px;
    padding-right: 2px;
 }
+
+a:has(> .znai-footnote-reference) {
+   text-decoration: none;
+   color: inherit;
+}

znai-reactjs/src/doc-elements/footnote/FootnoteReference.tsx

@@ -18,28 +18,40 @@ import React from "react";
 import { DocElementContent, ElementsLibraryMap } from "../default-elements/DocElement";
 import { Tooltip } from "../../components/Tooltip";
 import { FootnotePreview } from "./FootnotePreview";
+import { isFootnoteListHidden } from "../../structure/docMeta";
+import { footnoteRefAnchorId, footnoteEntryAnchorId } from "./footnoteAnchors";
 
 import "./FootnoteReference.css";
 
 interface Props {
   label: string;
   content: DocElementContent;
+  occurrence: number;
   elementsLibrary: ElementsLibraryMap;
 }
 
-export function FootnoteReference({ label, content, elementsLibrary }: Props) {
+export function FootnoteReference({ label, content, occurrence, elementsLibrary }: Props) {
   const tooltipContent = <FootnotePreview label={label} content={content} elementsLibrary={elementsLibrary} />;
 
   const referenceClassName =
     "znai-footnote-reference " + (label.length === 1 ? "single-char-label" : "multi-char-label");
 
+  const hasFootnoteList = !isFootnoteListHidden();
+  const anchorId = hasFootnoteList ? footnoteRefAnchorId(label, occurrence) : undefined;
+
+  const sup = (
+    <sup id={anchorId} className={referenceClassName}>
+      {label}
+    </sup>
+  );
+
   return (
     <Tooltip
       content={tooltipContent}
       placement="parent-content-block"
       contentClassName="znai-footnote-preview-container"
     >
-      <sup className={referenceClassName}>{label}</sup>
+      {hasFootnoteList ? <a href={"#" + footnoteEntryAnchorId(label)}>{sup}</a> : sup}
     </Tooltip>
   );
 }

znai-reactjs/src/doc-elements/footnote/FootnotesList.css

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2025 znai maintainers
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+.znai-footnotes-list {
+    --znai-regular-text-size: var(--znai-smaller-text-size);
+    --znai-code-text-size: var(--znai-small-meta-text-size);
+
+    border-top: 1px solid var(--znai-footnotes-list-border-color);
+    font-size: var(--znai-regular-text-size);
+
+    margin: 56px calc(-1 * var(--znai-single-side-horizontal-min-spacing)) -56px;
+}
+
+.znai-footnotes-list-content {
+    padding: 64px 0 32px 32px;
+}
+
+.znai-footnotes-list-entry {
+    display: flex;
+    align-items: first baseline;
+    gap: 12px;
+    margin-bottom: 4px;
+}
+
+.znai-footnotes-list-entry:last-child {
+    margin-bottom: 0;
+}
+
+.znai-footnotes-list-entry-label {
+    flex-shrink: 0;
+    min-width: 20px;
+    text-align: right;
+    color: var(--znai-snippets-title-color);
+}
+
+.znai-footnotes-list-entry-content {
+    flex: 1;
+    min-width: 0;
+}
+
+.znai-footnote-back-links {
+    margin-left: 4px;
+    white-space: nowrap;
+}
+
+.znai-footnote-back-link {
+    text-decoration: none;
+    color: var(--znai-snippets-title-color);
+    margin-left: 2px;
+}
+
+.znai-footnote-back-link:hover {
+    color: var(--znai-brand-primary-color);
+}