footnote: fix idx reset (#1496)

Author: MykolaGolubyev

znai-core/src/main/java/org/testingisdocumenting/znai/extensions/footnote/ParsedFootnote.java

@@ -18,6 +18,7 @@
 
 import org.commonmark.ext.footnotes.FootnoteDefinition;
 import org.testingisdocumenting.znai.core.ComponentsRegistry;
+import org.testingisdocumenting.znai.parser.MarkdownParsingContext;
 import org.testingisdocumenting.znai.parser.ParserHandlersList;
 import org.testingisdocumenting.znai.parser.commonmark.MarkdownVisitor;
 import org.testingisdocumenting.znai.parser.docelement.DocElement;
@@ -29,22 +30,22 @@
 import java.util.List;
 import java.util.stream.Collectors;
 
-public record ParsedFootnote(FootnoteId id, DocElement docElement, List<PageSearchEntry> searchEntries) {
-    public static ParsedFootnote parse(ComponentsRegistry componentsRegistry, Path markdownPath, FootnoteDefinition footnote) {
+public record ParsedFootnote(FootnoteId id, int idx, DocElement docElement, List<PageSearchEntry> searchEntries) {
+    public static ParsedFootnote parse(ComponentsRegistry componentsRegistry, Path markdownPath, FootnoteDefinition footnote, int idx) {
         var searchHandler = new SearchCrawlerParserHandler();
         DocElementCreationParserHandler docElementsHandler = new DocElementCreationParserHandler(componentsRegistry, markdownPath);
         var parserHandler = new ParserHandlersList(
                 docElementsHandler,
                 searchHandler
         );
 
-        var visitor = new MarkdownVisitor(componentsRegistry, markdownPath, parserHandler);
+        var visitor = new MarkdownVisitor(componentsRegistry, markdownPath, new MarkdownParsingContext(), parserHandler);
         visit(visitor, footnote);
 
         List<PageSearchEntry> searchEntries = searchHandler.getSearchEntries();
         DocElement docElement = docElementsHandler.getDocElement();
 
-        return new ParsedFootnote(new FootnoteId(footnote.getLabel()), docElement, searchEntries);
+        return new ParsedFootnote(new FootnoteId(footnote.getLabel()), idx, docElement, searchEntries);
     }
 
     private static void visit(MarkdownVisitor visitor, FootnoteDefinition footnote) {

znai-core/src/main/java/org/testingisdocumenting/znai/parser/MarkdownParsingContext.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2026 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.
+ */
+
+package org.testingisdocumenting.znai.parser;
+
+public class MarkdownParsingContext {
+    private int footnoteIdx;
+
+    public int nextFootnoteIdx() {
+        return ++footnoteIdx;
+    }
+}

znai-core/src/main/java/org/testingisdocumenting/znai/parser/commonmark/MarkdownParser.java

@@ -29,6 +29,7 @@
 import org.testingisdocumenting.znai.core.Log;
 import org.testingisdocumenting.znai.extensions.PluginParamWarning;
 import org.testingisdocumenting.znai.extensions.PluginParamsFactory;
+import org.testingisdocumenting.znai.parser.MarkdownParsingContext;
 import org.testingisdocumenting.znai.parser.MarkupParser;
 import org.testingisdocumenting.znai.parser.MarkupParserResult;
 import org.testingisdocumenting.znai.parser.ParserHandler;
@@ -45,6 +46,8 @@
 import org.commonmark.parser.Parser;
 
 public class MarkdownParser implements MarkupParser {
+    private static final ThreadLocal<MarkdownParsingContext> currentParsingContext = new ThreadLocal<>();
+
     private final Parser fullParser;
     private final Parser metaOnlyParser;
     private final ComponentsRegistry componentsRegistry;
@@ -58,6 +61,24 @@ public MarkdownParser(ComponentsRegistry componentsRegistry) {
     }
 
     public MarkupParserResult parse(Path path, String markdown) {
+        MarkdownParsingContext existing = currentParsingContext.get();
+        boolean isTopLevel = existing == null;
+        MarkdownParsingContext parsingContext = isTopLevel ? new MarkdownParsingContext() : existing;
+
+        if (isTopLevel) {
+            currentParsingContext.set(parsingContext);
+        }
+
+        try {
+            return doParse(path, parsingContext, markdown);
+        } finally {
+            if (isTopLevel) {
+                currentParsingContext.remove();
+            }
+        }
+    }
+
+    private MarkupParserResult doParse(Path path, MarkdownParsingContext parsingContext, String markdown) {
         SearchCrawlerParserHandler searchCrawler = new SearchCrawlerParserHandler();
         DocElementCreationParserHandler elementCreationHandler =
                 new DocElementCreationParserHandler(componentsRegistry, path);
@@ -66,7 +87,7 @@ public MarkupParserResult parse(Path path, String markdown) {
         ParserHandlersList parserHandler = new ParserHandlersList(elementCreationHandler, searchCrawler, markdownGenerator);
 
         Node node = fullParser.parse(markdown);
-        MarkdownVisitor visitor = parsePartial(node, path, parserHandler);
+        MarkdownVisitor visitor = parsePartial(node, path, parsingContext, parserHandler);
 
         if (!visitor.getUnresolvedFootnoteRefs().isEmpty()) {
             throw new IllegalArgumentException("undefined footnote reference(s): " +
@@ -99,11 +120,11 @@ public PageMeta parsePageMetaOnly(String markdown) {
 
     public void parse(Path path, ParserHandler handler, String markdown) {
         Node node = fullParser.parse(markdown);
-        parsePartial(node, path, handler);
+        parsePartial(node, path, new MarkdownParsingContext(), handler);
     }
 
-    private MarkdownVisitor parsePartial(Node node, Path path, ParserHandler handler) {
-        MarkdownVisitor visitor = new MarkdownVisitor(componentsRegistry, path, handler);
+    private MarkdownVisitor parsePartial(Node node, Path path, MarkdownParsingContext parsingContext, ParserHandler handler) {
+        MarkdownVisitor visitor = new MarkdownVisitor(componentsRegistry, path, parsingContext, handler);
         node.accept(visitor);
 
         return visitor;

znai-core/src/main/java/org/testingisdocumenting/znai/parser/commonmark/MarkdownVisitor.java

@@ -24,6 +24,7 @@
 import org.testingisdocumenting.znai.extensions.fence.FencePlugin;
 import org.testingisdocumenting.znai.extensions.footnote.FootnoteId;
 import org.testingisdocumenting.znai.extensions.footnote.ParsedFootnote;
+import org.testingisdocumenting.znai.parser.MarkdownParsingContext;
 import org.testingisdocumenting.znai.extensions.include.IncludePlugin;
 import org.testingisdocumenting.znai.extensions.inlinedcode.InlinedCodePlugin;
 import org.testingisdocumenting.znai.extensions.latex.LatexDollarBlock;
@@ -52,15 +53,17 @@ public class MarkdownVisitor extends AbstractVisitor {
 
     private final ComponentsRegistry componentsRegistry;
     private final Path path;
+    private final MarkdownParsingContext parsingContext;
     private final ParserHandler parserHandler;
     private boolean sectionStarted;
 
     private final Set<PluginParamWarning> parameterWarnings;
     private final Set<String> unresolvedFootnoteRefs;
 
-    public MarkdownVisitor(ComponentsRegistry componentsRegistry, Path path, ParserHandler parserHandler) {
+    public MarkdownVisitor(ComponentsRegistry componentsRegistry, Path path, MarkdownParsingContext parsingContext, ParserHandler parserHandler) {
         this.componentsRegistry = componentsRegistry;
         this.path = path;
+        this.parsingContext = parsingContext;
         this.parserHandler = parserHandler;
         this.parameterWarnings = new LinkedHashSet<>();
         this.unresolvedFootnoteRefs = new LinkedHashSet<>();
@@ -181,7 +184,7 @@ public void visit(CustomBlock customBlock) {
             GfmTableToTableConverter gfmTableToTableConverter = new GfmTableToTableConverter(componentsRegistry, path, (TableBlock) customBlock);
             parserHandler.onTable(gfmTableToTableConverter.convert());
         } else if (customBlock instanceof FootnoteDefinition footnote) {
-            ParsedFootnote parsed = ParsedFootnote.parse(componentsRegistry, path, footnote);
+            ParsedFootnote parsed = ParsedFootnote.parse(componentsRegistry, path, footnote, parsingContext.nextFootnoteIdx());
             parserHandler.onFootnoteDefinition(parsed);
         } else {
             throw new UnsupportedOperationException("unsupported custom block: " + customBlock);

znai-core/src/main/java/org/testingisdocumenting/znai/parser/docelement/DocElementCreationParserHandler.java

@@ -61,8 +61,6 @@ public class DocElementCreationParserHandler implements ParserHandler {
     private final Deque<DocElement> elementsStack;
 
     private final Map<FootnoteId, ParsedFootnote> parsedFootnotes;
-    private final Map<FootnoteId, Integer> footnoteIdxById;
-    private int footnoteAutoIdx;
     private String currentSectionTitle;
 
     private boolean isSectionStarted;
@@ -76,8 +74,6 @@ public DocElementCreationParserHandler(ComponentsRegistry componentsRegistry, Pa
         this.globalAnchorIds = new ArrayList<>();
 
         this.parsedFootnotes = new HashMap<>();
-        this.footnoteAutoIdx = 0;
-        this.footnoteIdxById = new HashMap<>();
 
         this.docElement = new DocElement(DocElementType.PAGE);
         this.elementsStack = new ArrayDeque<>();
@@ -224,15 +220,12 @@ public void onTable(MarkupTableData tableData) {
     @Override
     public void onFootnoteDefinition(ParsedFootnote footnote) {
         parsedFootnotes.put(footnote.id(), footnote);
-
-        int indexToUse = ++footnoteAutoIdx;
-        footnoteIdxById.put(footnote.id(), indexToUse);
     }
 
     @Override
     public void onFootnoteReference(FootnoteId footnoteId) {
         append(new DocElement( "FootnoteReference",
-                "label", (Supplier<?>) (() -> Integer.toString(footnoteIdxById.getOrDefault(footnoteId, 1))),
+                "label", (Supplier<?>) (() -> footnoteLabel(footnoteId)),
                 "content", (Supplier<?>) (() -> footnoteContent(footnoteId))));
     }
 
@@ -577,13 +570,18 @@ private void addAnchorIdsToProps(Map<String, Object> props, AnchorIds ids) {
         props.put("additionalIds", ids.additional());
     }
 
+    private String footnoteLabel(FootnoteId footnoteId) {
+        ParsedFootnote footnote = parsedFootnotes.get(footnoteId);
+        return footnote != null ? Integer.toString(footnote.idx()) : "undefined";
+    }
+
     private List<Map<String, Object>> footnoteContent(FootnoteId footnoteId) {
-        ParsedFootnote parsedFootnote = parsedFootnotes.get(footnoteId);
-        if (parsedFootnote == null) {
+        ParsedFootnote footnote = parsedFootnotes.get(footnoteId);
+        if (footnote == null) {
             throw new IllegalArgumentException("can't find footnote with id <" + footnoteId + ">");
         }
 
-        return parsedFootnote.docElement().contentToListOfMaps();
+        return footnote.docElement().contentToListOfMaps();
     }
 
     private void addHeadingContentWhenNotSimple(Map<String, Object> props, Heading heading) {
@@ -633,4 +631,5 @@ public void visit(StrongEmphasis strongEmphasis) {
 
         props.put("headingContent", content);
     }
+
 }

znai-core/src/main/java/org/testingisdocumenting/znai/parser/table/GfmTableToTableConverter.java

@@ -18,6 +18,7 @@
 package org.testingisdocumenting.znai.parser.table;
 
 import org.testingisdocumenting.znai.core.ComponentsRegistry;
+import org.testingisdocumenting.znai.parser.MarkdownParsingContext;
 import org.testingisdocumenting.znai.parser.docelement.DocElementCreationParserHandler;
 import org.testingisdocumenting.znai.parser.commonmark.MarkdownVisitor;
 import org.commonmark.ext.gfm.tables.*;
@@ -102,7 +103,7 @@ private void handleBodyCell(TableCell bodyCell) {
     @SuppressWarnings("unchecked")
     private List<Map<String, Object>> contentFromCell(TableCell bodyCell) {
         DocElementCreationParserHandler handler = new DocElementCreationParserHandler(componentsRegistry, markdownPath);
-        MarkdownVisitor markdownVisitor = new MarkdownVisitor(componentsRegistry, markdownPath, handler);
+        MarkdownVisitor markdownVisitor = new MarkdownVisitor(componentsRegistry, markdownPath, new MarkdownParsingContext(), handler);
 
         bodyCell.accept(markdownVisitor);
 

znai-core/src/test/groovy/org/testingisdocumenting/znai/parser/MarkdownParserTest.groovy

@@ -637,6 +637,38 @@ after footnote
         ]
     }
 
+    @Test
+    void "footnotes inside fence plugin should continue numbering"() {
+        def previousDefaultParser = componentsRegistry.defaultParser()
+        componentsRegistry.setDefaultParser(parser)
+
+        try {
+            parse("""
+text before [^first]
+
+[^first]: first footnote
+
+~~~attention-note
+inner text [^second]
+
+[^second]: second footnote
+~~~
+""")
+
+            def content = PropsUtils.exerciseSuppliers(content)
+
+            def firstRef = content[0].content.find { it.type == "FootnoteReference" }
+            firstRef.label.should == "1"
+
+            def attentionBlock = content.find { it.type == "AttentionBlock" }
+            def innerParagraph = attentionBlock.content[0]
+            def secondRef = innerParagraph.content.find { it.type == "FootnoteReference" }
+            secondRef.label.should == "2"
+        } finally {
+            componentsRegistry.setDefaultParser(previousDefaultParser)
+        }
+    }
+
     @Test
     void "undefined footnote reference"() {
         code {

znai-docs/znai/release-notes/1.88/fix-2026-04-12-footnote-continuous-idx.md

@@ -0,0 +1 @@
+* Fix: footnote idx is no longer reset when footnotes are defined inside plugins like `readmore`