feat: Add index-topmatter config option for custom YAML frontmatter (#412)

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

* tests: remove full topmatter test

* refactor: Generalize dash-to-underscore conversion for all config keys

* Update quartodoc/autosummary.py

* Update quartodoc/autosummary.py

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:
+        # handle index topmatter
+        if self.index_topmatter is not None:
+            # index_topmatter overrides title
+            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,15 @@ def from_quarto_config(cls, quarto_cfg: "str | dict") -> Builder:
 
         _fast_inventory = quarto_cfg.get("interlinks", {}).get("fast", False)
 
+        # Convert dash to underscore for all config keys (YAML uses dashes, Python uses underscores)
+        config_args = {}
+        for k, v in cfg.items():
+            if k != "style":
+                # Replace dashes with underscores for Python parameter names
+                config_args[k.replace("-", "_")] = 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,79 @@ 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