feat: Add index-topmatter config option for custom YAML frontmatter

Author: machow

quartodoc/autosummary.py

@@ -480,6 +480,11 @@ class Builder:
     parser:
         Docstring parser to use. This correspond to different docstring styles,
         and can be one of "google", "sphinx", and "numpy". Defaults to "numpy".
+    index_topmatter : dict, optional
+        Custom YAML frontmatter for the API index page. When provided, this
+        completely overrides the `title` configuration. Set to an empty dict
+        to generate an empty frontmatter block. Default is None, which falls
+        back to using the `title` parameter.
 
     """
 
@@ -530,6 +535,7 @@ def __init__(
         dynamic: bool | None = None,
         parser="numpy",
         render_interlinks: bool = False,
+        index_topmatter: "dict[str, Any] | None" = None,
         _fast_inventory=False,
     ):
         self.layout = self.load_layout(
@@ -559,6 +565,8 @@ def __init__(
         if out_index is not None:
             self.out_index = out_index
 
+        self.index_topmatter = index_topmatter
+
         self.rewrite_all_pages = rewrite_all_pages
         self.source_dir = str(Path(source_dir).absolute()) if source_dir else None
         self.dynamic = dynamic
@@ -646,9 +654,15 @@ def write_index(self, blueprint: layout.Layout):
         content = self.renderer.summarize(blueprint)
         _log.info(f"Writing index to directory: {self.dir}")
 
-        if self.title is not None:
+        # New logic for handling topmatter
+        if self.index_topmatter is not None:
+            # index_topmatter overrides title completely
+            meta = [Meta(self.index_topmatter)]
+        elif self.title is not None:
+            # Fall back to title-only frontmatter
             meta = [Meta({"title": self.title})]
         else:
+            # No frontmatter at all
             meta = []
 
         final = str(Blocks([*meta, content]))
@@ -806,8 +820,18 @@ def from_quarto_config(cls, quarto_cfg: "str | dict") -> Builder:
 
         _fast_inventory = quarto_cfg.get("interlinks", {}).get("fast", False)
 
+        # Convert dash to underscore for index-topmatter
+        config_args = {}
+        for k, v in cfg.items():
+            if k != "style":
+                # Convert index-topmatter to index_topmatter
+                if k == "index-topmatter":
+                    config_args["index_topmatter"] = v
+                else:
+                    config_args[k] = v
+
         return cls_builder(
-            **{k: v for k, v in cfg.items() if k != "style"},
+            **config_args,
             _fast_inventory=_fast_inventory,
         )
 

quartodoc/tests/test_builder.py

@@ -149,3 +149,128 @@ def test_builder_no_title_no_topmatter(tmp_path):
 
     index = (Path(tmp_path) / "index.qmd").read_text()
     assert not index.startswith("---")
+
+
+def test_builder_index_topmatter_custom(tmp_path):
+    """Test that index_topmatter allows custom frontmatter."""
+    cfg = yaml.safe_load(
+        """
+    quartodoc:
+      package: quartodoc.tests.example
+      title: "This will be ignored"
+      index-topmatter:
+        title: "Custom API Reference"
+        description: "API documentation for my package"
+        author: "Test Author"
+        date: "2024-01-01"
+      sections:
+        - title: first section
+          contents: [a_func]
+    """
+    )
+
+    builder = Builder.from_quarto_config(cfg)
+    builder.dir = str(tmp_path)
+    bp = blueprint(builder.layout)
+    builder.write_index(bp)
+
+    index = (Path(tmp_path) / "index.qmd").read_text()
+    assert index.startswith("---")
+    assert "title: Custom API Reference" in index
+    assert "description: API documentation for my package" in index
+    assert "author: Test Author" in index
+    assert "This will be ignored" not in index  # Original title not used
+
+
+def test_builder_index_topmatter_empty(tmp_path):
+    """Test that empty index_topmatter generates empty frontmatter."""
+    cfg = yaml.safe_load(
+        """
+    quartodoc:
+      package: quartodoc.tests.example
+      title: "Will be ignored"
+      index-topmatter: {}
+      sections:
+        - title: first section
+          contents: [a_func]
+    """
+    )
+
+    builder = Builder.from_quarto_config(cfg)
+    builder.dir = str(tmp_path)
+    bp = blueprint(builder.layout)
+    builder.write_index(bp)
+
+    index = (Path(tmp_path) / "index.qmd").read_text()
+    assert index.startswith("---\n{}\n\n---")  # Empty dict rendered as {} in YAML
+
+
+def test_builder_index_topmatter_fallback(tmp_path):
+    """Test that title is used when index_topmatter is not provided."""
+    cfg = yaml.safe_load(
+        """
+    quartodoc:
+      package: quartodoc.tests.example
+      title: "Function Reference"
+      sections:
+        - title: first section
+          contents: [a_func]
+    """
+    )
+
+    builder = Builder.from_quarto_config(cfg)
+    builder.dir = str(tmp_path)
+    bp = blueprint(builder.layout)
+    builder.write_index(bp)
+
+    index = (Path(tmp_path) / "index.qmd").read_text()
+    assert "title: Function Reference" in index
+
+
+def test_builder_index_topmatter_full_build(tmp_path):
+    """Test full build with index-topmatter configuration."""
+    cfg = yaml.safe_load(
+        """
+    quartodoc:
+      package: quartodoc.tests.example
+      index-topmatter:
+        title: "Complete API Reference"
+        description: "Full documentation with custom frontmatter"
+        author: "Test Suite"
+        date-modified: "2024-12-04"
+        toc: true
+        toc-depth: 2
+      sections:
+        - title: Test Functions
+          desc: "Testing the new index-topmatter feature"
+          contents:
+            - a_func
+            - AClass
+    """
+    )
+
+    builder = Builder.from_quarto_config(cfg)
+    builder.dir = str(tmp_path / "api")
+
+    # Run the full build
+    builder.build()
+
+    # Check that the index file was created with correct frontmatter
+    index_path = Path(tmp_path) / "api" / "index.qmd"
+    assert index_path.exists()
+
+    index_content = index_path.read_text()
+    assert "title: Complete API Reference" in index_content
+    assert "description: Full documentation with custom frontmatter" in index_content
+    assert "author: Test Suite" in index_content
+    assert "date-modified: '2024-12-04'" in index_content or "date-modified: 2024-12-04" in index_content
+    assert "toc: true" in index_content
+    assert "toc-depth: 2" in index_content
+
+    # Check that the section title is still rendered correctly
+    assert "## Test Functions" in index_content
+    assert "Testing the new index-topmatter feature" in index_content
+
+    # Check that individual pages were created
+    assert (Path(tmp_path) / "api" / "a_func.qmd").exists()
+    assert (Path(tmp_path) / "api" / "AClass.qmd").exists()