toc: hide and skip option (#1498)

Author: MykolaGolubyev

znai-core/src/main/java/org/testingisdocumenting/znai/structure/TableOfContents.java

@@ -75,14 +75,14 @@ public void addIndex() {
 
     public TocItem firstNonIndexPage() {
         return tocItems.stream()
-                .filter(tocItem -> !tocItem.isIndex())
+                .filter(tocItem -> !tocItem.isIndex() && !tocItem.isHidden())
                 .findFirst()
                 .orElse(null);
     }
 
     public Optional<TocItem> firstPageInChapter(String dirName) {
         return tocItems.stream()
-                .filter(tocItem -> tocItem.getDirName().equals(dirName))
+                .filter(tocItem -> tocItem.getDirName().equals(dirName) && !tocItem.isHidden())
                 .findFirst();
     }
 

znai-core/src/main/java/org/testingisdocumenting/znai/structure/TocBehavior.java

@@ -0,0 +1,33 @@
+/*
+ * 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.structure;
+
+public enum TocBehavior {
+    DEFAULT,
+    HIDE,
+    SKIP;
+
+    public static TocBehavior fromString(String value) {
+        return switch (value.toLowerCase()) {
+            case "hide" -> HIDE;
+            case "skip" -> SKIP;
+            case "default" -> DEFAULT;
+            default -> throw new IllegalArgumentException(
+                    "unsupported toc value: \"" + value + "\", supported values: \"default\", \"hide\", \"skip\"");
+        };
+    }
+}

znai-core/src/main/java/org/testingisdocumenting/znai/structure/TocItem.java

@@ -33,6 +33,7 @@ public class TocItem {
     private final TocNameAndOpts page;
     private final String fileNameWithoutExtension;
     private final String fileExtension;
+    private final TocBehavior tocBehavior;
     private String pageTitle;
     private PageMeta pageMeta;
 
@@ -55,6 +56,7 @@ public TocItem(TocNameAndOpts chapter, TocNameAndOpts page, String defaultExtens
 
         this.fileNameWithoutExtension = extractName(page.getGivenName());
         this.fileExtension = extractExtension(page.getGivenName(), defaultExtension);
+        this.tocBehavior = page.getTocBehavior();
         validateFileName(chapter.getGivenName());
         validateFileName(this.fileNameWithoutExtension);
 
@@ -130,6 +132,18 @@ public void setPageTitleIfNoTocOverridePresent(String pageTitle) {
         }
     }
 
+    public TocBehavior getTocBehavior() {
+        return tocBehavior;
+    }
+
+    public boolean isHidden() {
+        return tocBehavior == TocBehavior.HIDE;
+    }
+
+    public boolean isSkip() {
+        return tocBehavior == TocBehavior.SKIP;
+    }
+
     public boolean isIndex() {
         return chapter.getGivenName().isEmpty() && fileNameWithoutExtension.equals(INDEX);
     }
@@ -150,6 +164,10 @@ public boolean match(String dirName, String fileNameWithoutExtension) {
         result.put("pageSectionIdTitles",
                 getPageSectionIdTitles().stream().map(PageSectionIdTitle::toMap).collect(toList()));
 
+        if (tocBehavior != TocBehavior.DEFAULT) {
+            result.put("toc", tocBehavior.name().toLowerCase());
+        }
+
         return result;
     }
 

znai-core/src/main/java/org/testingisdocumenting/znai/structure/TocNameAndOpts.java

@@ -29,11 +29,13 @@
 public class TocNameAndOpts {
     private final String TITLE_KEY = "title";
     private final String PATH_KEY = "path";
+    private final String TOC_BEHAVIOR_KEY = "toc";
 
     private final String givenName;
     private final Map<String, ?> opts;
     private final boolean hasTitleOverride;
     private final boolean hasPath;
+    private final TocBehavior tocBehavior;
 
     private String humanReadableName;
 
@@ -45,6 +47,7 @@ public TocNameAndOpts(String trimmed) {
         this.opts = hasOpenBracket ? extractOpts(trimmed, openBracketIdx) : Collections.emptyMap();
         this.hasTitleOverride = opts.containsKey(TITLE_KEY);
         this.hasPath = opts.containsKey(PATH_KEY);
+        this.tocBehavior = buildTocBehavior();
 
         this.humanReadableName = buildHumanReadableName();
     }
@@ -77,6 +80,10 @@ public String getPath() {
         return opts.get(PATH_KEY).toString();
     }
 
+    public TocBehavior getTocBehavior() {
+        return tocBehavior;
+    }
+
     private Map<String, ?> extractOpts(String trimmed, int openBracketIdx) {
         int closeBracketIdx = trimmed.indexOf('}');
         if (closeBracketIdx == -1) {
@@ -86,6 +93,15 @@ public String getPath() {
         return JsonUtils.deserializeAsMap(trimmed.substring(openBracketIdx, closeBracketIdx + 1));
     }
 
+    private TocBehavior buildTocBehavior() {
+        Object behavior = opts.get(TOC_BEHAVIOR_KEY);
+        if (behavior == null) {
+            return TocBehavior.DEFAULT;
+        }
+
+        return TocBehavior.fromString(behavior.toString());
+    }
+
     private String buildHumanReadableName() {
         Object title = opts.get(TITLE_KEY);
         if (title != null) {

znai-core/src/test/groovy/org/testingisdocumenting/znai/structure/PlainTextTocGeneratorTest.groovy

@@ -189,13 +189,44 @@ api-reference.md {title: "API Docs"}""")
         api.getPageTitle().should == "API Docs"
     }
 
+    @Test
+    void "should support hide and skip toc property"() {
+        def toc = new PlainTextTocGenerator("md").generate("""
+chapter1
+    page-a
+    page-b {toc: "hide"}
+    page-c {toc: "skip"}""")
+
+        def pageA = toc.findTocItem("chapter1", "page-a")
+        pageA.isHidden().should == false
+        pageA.getTocBehavior().should == TocBehavior.DEFAULT
+
+        def pageB = toc.findTocItem("chapter1", "page-b")
+        pageB.isHidden().should == true
+        pageB.getTocBehavior().should == TocBehavior.HIDE
+
+        def pageC = toc.findTocItem("chapter1", "page-c")
+        pageC.isSkip().should == true
+        pageC.getTocBehavior().should == TocBehavior.SKIP
+    }
+
+    @Test
+    void "should throw error for unsupported toc value"() {
+        code {
+            new PlainTextTocGenerator("md").generate("""
+chapter1
+    page-a {toc: "unknown"}""")
+        } should throwException(IllegalArgumentException,
+                ~/unsupported toc value: "unknown"/)
+    }
+
     @Test
     void "should throw error for indented page without chapter"() {
         code {
             new PlainTextTocGenerator("md").generate("""
     page-without-chapter
 """)
-        } should throwException(IllegalArgumentException, 
+        } should throwException(IllegalArgumentException,
                 "chapter is not specified, use a line without indentation to specify a chapter")
     }
 }

znai-core/src/test/groovy/org/testingisdocumenting/znai/structure/TableOfContentsTest.groovy

@@ -156,4 +156,24 @@ class TableOfContentsTest {
         toc.findTocItem(pathC).should == [dirName: "chapter2", fileNameWithoutExtension: "page-c"]
         toc.findTocItem(pathD).should == null
     }
+
+    @Test
+    void "firstNonIndexPage should skip hidden pages"() {
+        def toc = new TableOfContents("md")
+        toc.addIndex()
+        toc.addTocItem(new TocNameAndOpts("chapter1"), new TocNameAndOpts('page-a {toc: "hide"}'))
+        toc.addTocItem("chapter1", "page-b")
+        toc.addTocItem("chapter1", "page-c")
+
+        toc.firstNonIndexPage().fileNameWithoutExtension.should == "page-b"
+    }
+
+    @Test
+    void "firstPageInChapter should skip hidden pages"() {
+        def toc = new TableOfContents("md")
+        toc.addTocItem(new TocNameAndOpts("chapter1"), new TocNameAndOpts('page-a {toc: "hide"}'))
+        toc.addTocItem("chapter1", "page-b")
+
+        toc.firstPageInChapter("chapter1").get().fileNameWithoutExtension.should == "page-b"
+    }
 }

znai-docs/znai/flow/structure.md

@@ -47,6 +47,30 @@ optional-chapter
    page-four.md
 ```
 
+# Hide & Skip
+
+You can control how individual pages participate in the documentation by setting `toc` property in the `toc` file.
+
+A hidden page can be navigated to with a direct link, but it won't appear in the TOC panel
+and won't participate in next/prev page navigation.
+
+```
+chapter-name
+    page-one
+    page-two {toc: "hide"}
+    page-three
+```
+
+A skipped page is accessible via direct URL, but it won't participate in next/prev page navigation.
+Users navigating sequentially will skip over it.
+
+```
+chapter-name
+    page-one
+    page-two {toc: "skip"}
+    page-three
+```
+
 # Sub Headings
 
 Only a first level heading is treated as a first class citizen:

znai-docs/znai/release-notes/1.88/add-2026-04-14-toc-item-behavior.md

@@ -0,0 +1,2 @@
+* Add: `toc` file items support new `toc` property with `skip` and `hide` to control what is displayed in TOC navigation
+and what pages are skipped with next/prev page buttons

znai-reactjs/src/layout/TocMenu.jsx

@@ -97,7 +97,7 @@ class Item extends PureComponent {
 const Section = ({ section, selected, onTocItemClick, onTocItemPageSectionClick }) => {
   const className = "toc-section" + (section.dirName === selected.dirName ? " selected" : "");
 
-  const items = section.items.filter((item) => !isTocItemIndex(item));
+  const items = section.items.filter((item) => !isTocItemIndex(item) && item.toc !== "hide");
   if (items.length === 0) {
     return null;
   }

znai-reactjs/src/structure/TocItem.ts

@@ -15,12 +15,15 @@
  * limitations under the License.
  */
 
+export type TocBehavior = "default" | "hide" | "skip";
+
 export interface TocItem {
   dirName: string;
   fileName: string;
   chapterTitle?: string;
   pageTitle?: string;
   pageMeta?: object;
+  toc?: TocBehavior;
   anchorId?: string;
   fileExtension?: string;
   items?: TocItem[];