fix: add support for unlisted pages (#106)

Author: tylerdave

docs/Configuration.md

@@ -206,6 +206,7 @@ Per-page options set in YAML frontmatter:
 | `author`      | `str`           | Page author (used in Atom feed, overrides site-level feed author)         |
 | `subtitle`    | `str`           | Subtitle shown below the page title, in folder indexes, and tag indexes   |
 | `show_index`  | `bool`          | For `index.md` files: render page content + auto-generated folder listing |
+| `unlisted`    | `bool`          | Hide page from sidebar navigation and folder indexes (still accessible by URL) |
 
 ## CLI Overrides
 

src/rockgarden/nav/folder_index.py

@@ -88,6 +88,9 @@ def generate_folder_indexes(
     for folder_path in sorted(folders):
         if _should_hide(folder_path, config.hide):
             continue
+        index_page = existing_indexes.get(folder_path)
+        if index_page and index_page.frontmatter.get("unlisted", False):
+            continue
 
         children = _get_folder_children(
             folder_path, pages, config, clean_urls, base_path
@@ -204,7 +207,9 @@ def _get_folder_children(
         if len(parts) == 1:
             if parts[0] == "index":
                 continue
-            if _should_hide(page.slug, config.hide):
+            if _should_hide(page.slug, config.hide) or page.frontmatter.get(
+                "unlisted", False
+            ):
                 continue
 
             modified = None
@@ -229,6 +234,11 @@ def _get_folder_children(
             if subfolder_path not in seen_subfolders:
                 if _should_hide(subfolder_path, config.hide):
                     continue
+                subfolder_index = folder_index_pages.get(subfolder_path)
+                if subfolder_index and subfolder_index.frontmatter.get(
+                    "unlisted", False
+                ):
+                    continue
 
                 seen_subfolders.add(subfolder_path)
                 label = resolve_label(subfolder_path, subfolder, config.labels)

src/rockgarden/nav/tree.py

@@ -124,7 +124,9 @@ def build_nav_tree(
     tree: dict[str, dict] = {}
 
     for page in pages:
-        if _should_hide(page.slug, config.hide):
+        if _should_hide(page.slug, config.hide) or page.frontmatter.get(
+            "unlisted", False
+        ):
             continue
 
         parts = page.slug.split("/")
@@ -136,7 +138,10 @@ def build_nav_tree(
             current_path_parts.append(part)
             folder_path = "/".join(current_path_parts)
 
-            if _should_hide(folder_path, config.hide):
+            folder_page = folder_pages.get(folder_path)
+            if _should_hide(folder_path, config.hide) or (
+                folder_page and folder_page.frontmatter.get("unlisted", False)
+            ):
                 break
 
             if part not in current:
@@ -148,8 +153,7 @@ def build_nav_tree(
                     "_original_name": original_name,
                 }
             current = current[part]["_children"]
-
-        if not _should_hide(page.slug, config.hide):
+        else:
             page_name = parts[-1]
             if page_name != "index":
                 current[page_name] = {

tests/test_folder_index.py

@@ -269,3 +269,52 @@ def test_folder_note_not_in_children(self):
         assert "City of Fairshore" not in child_titles
         assert "The Salty Dog" in child_titles
         assert "Market Square" in child_titles
+
+
+class TestUnlistedFolderIndex:
+    """Test that unlisted pages are excluded from folder index children."""
+
+    def test_unlisted_page_hidden_from_folder_children(self):
+        pages = [
+            make_page("docs/visible", "Visible"),
+            make_page("docs/secret", "Secret", unlisted=True),
+        ]
+        indexes = generate_folder_indexes(pages)
+        docs = next(fi for fi in indexes if fi.slug == "docs/index")
+        child_titles = [c.title for c in docs.children]
+        assert "Visible" in child_titles
+        assert "Secret" not in child_titles
+
+    def test_unlisted_folder_hidden_from_parent_index(self):
+        """Folder with unlisted index page not shown in parent's children."""
+        pages = [
+            make_page("docs/public", "Public"),
+            Page(
+                source_path=Path("/vault/docs/secret/index.md"),
+                slug="docs/secret/index",
+                frontmatter={"title": "Secret Folder", "unlisted": True},
+                content="",
+            ),
+            make_page("docs/secret/inner", "Inner Page"),
+        ]
+        indexes = generate_folder_indexes(pages)
+        docs = next(fi for fi in indexes if fi.slug == "docs/index")
+        child_titles = [c.title for c in docs.children]
+        assert "Public" in child_titles
+        assert "Secret Folder" not in child_titles
+        assert "secret" not in [c.title.lower() for c in docs.children]
+
+    def test_unlisted_folder_not_in_generated_indexes(self):
+        """Folder with unlisted index should not get a generated folder index."""
+        pages = [
+            Page(
+                source_path=Path("/vault/secret/index.md"),
+                slug="secret/index",
+                frontmatter={"title": "Secret", "unlisted": True},
+                content="",
+            ),
+            make_page("secret/inner", "Inner"),
+        ]
+        indexes = generate_folder_indexes(pages)
+        index_slugs = [fi.slug for fi in indexes]
+        assert "secret/index" not in index_slugs

tests/test_nav_tree.py

@@ -523,3 +523,75 @@ def test_folder_note_not_duplicate_child(self):
         assert "Fairshore" not in child_labels
         assert "The Salty Dog" in child_labels
         assert "Market Square" in child_labels
+
+
+class TestUnlistedPages:
+    """Test that unlisted frontmatter hides pages from nav."""
+
+    def test_unlisted_page_hidden_from_nav(self):
+        pages = [
+            make_page("about", "About"),
+            Page(
+                source_path=Path("/vault/secret.md"),
+                slug="secret",
+                frontmatter={"title": "Secret", "unlisted": True},
+                content="",
+            ),
+        ]
+        tree = build_nav_tree(pages)
+        labels = [c.label for c in tree.children]
+        assert "About" in labels
+        assert "Secret" not in labels
+
+    def test_unlisted_page_folder_still_shown(self):
+        pages = [
+            Page(
+                source_path=Path("/vault/docs/hidden.md"),
+                slug="docs/hidden",
+                frontmatter={"title": "Hidden", "unlisted": True},
+                content="",
+            ),
+            make_page("docs/visible", "Visible"),
+        ]
+        tree = build_nav_tree(pages)
+        docs = tree.children[0]
+        assert docs.is_folder
+        child_labels = [c.label for c in docs.children]
+        assert "Visible" in child_labels
+        assert "Hidden" not in child_labels
+
+    def test_unlisted_false_still_shown(self):
+        pages = [
+            Page(
+                source_path=Path("/vault/page.md"),
+                slug="page",
+                frontmatter={"title": "Page", "unlisted": False},
+                content="",
+            ),
+        ]
+        tree = build_nav_tree(pages)
+        labels = [c.label for c in tree.children]
+        assert "Page" in labels
+
+    def test_unlisted_folder_hidden_from_nav(self):
+        """Folder with unlisted index page should not appear in nav."""
+        pages = [
+            Page(
+                source_path=Path("/vault/secret/index.md"),
+                slug="secret/index",
+                frontmatter={"title": "Secret", "unlisted": True},
+                content="",
+            ),
+            Page(
+                source_path=Path("/vault/secret/details.md"),
+                slug="secret/details",
+                frontmatter={"title": "Details"},
+                content="",
+            ),
+            make_page("public", "Public"),
+        ]
+        tree = build_nav_tree(pages)
+        labels = [c.label for c in tree.children]
+        assert "Public" in labels
+        assert "secret" not in [c.label.lower() for c in tree.children]
+        assert "Details" not in labels