fix(docs): Command reference hides the sidebar on leaf pages

cmd/docgen/main.go

@@ -64,7 +64,7 @@ func write(cmd *cobra.Command, dir string) error {
 	if err := doc.GenMarkdownCustom(cmd, &body, linker(cmd)); err != nil {
 		return err
 	}
-	page.Write(dropHeading(body.Bytes()))
+	page.Write(retitleSeeAlso(dropHeading(body.Bytes())))
 
 	// A command with subcommands owns a directory, so its page is that
 	// directory's index; a leaf is a plain page beside its siblings.
@@ -112,6 +112,12 @@ func linker(from *cobra.Command) func(string) string {
 	}
 }
 
+// retitleSeeAlso rewrites cobra's shouty "SEE ALSO" heading to match the
+// sentence case of the headings around it.
+func retitleSeeAlso(md []byte) []byte {
+	return bytes.ReplaceAll(md, []byte("### SEE ALSO"), []byte("### See also"))
+}
+
 // dropHeading removes the "## <command path>" line cobra opens with, and the
 // blank line after it.
 func dropHeading(md []byte) []byte {

cmd/docgen/main_test.go

@@ -76,7 +76,29 @@ func TestWritePage(t *testing.T) {
 	assert.NotContains(t, got, "## flagsmith flag update")
 	// no generation date is stamped into the page
 	assert.NotContains(t, got, "Auto generated")
+	// cobra's shouty heading is sentence case, like the headings around it
+	assert.Contains(t, got, "### See also")
+	assert.NotContains(t, got, "SEE ALSO")
 
 	// Guard against the assertions above passing on an empty file.
 	require.NotEmpty(t, strings.TrimSpace(got))
 }
+
+func TestWriteCollapsesSidebarGroups(t *testing.T) {
+	// Given
+	dir := t.TempDir()
+	require.NoError(t, write(cmd.Root(), dir))
+
+	// When / Then
+	// the root of the tree is always expanded, so the top-level commands show
+	root, err := os.ReadFile(filepath.Join(dir, "_index.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(root), "sidebar:\n  open: true")
+
+	// everything below it is collapsed until the reader expands it
+	for _, page := range []string{"flag/_index.md", "environment/key/_index.md", "flag/update.md"} {
+		body, err := os.ReadFile(filepath.Join(dir, page))
+		require.NoError(t, err)
+		assert.NotContains(t, string(body), "sidebar:", page)
+	}
+}

website/hugo.yaml

@@ -11,9 +11,11 @@ module:
   imports:
     - path: github.com/imfing/hextra
 
+cascade:
+  - target: {}
+    type: docs
+
 enableRobotsTXT: true
-# Generated pages have no git history of their own, so there is no
-# "last modified" worth showing.
 enableGitInfo: false
 
 markup:
@@ -26,8 +28,6 @@ markup:
 
 menu:
   main:
-    # Installing is documented in the README and on docs.flagsmith.com. Link to
-    # one of them rather than keeping a third copy in step.
     - name: Install
       url: https://github.com/Flagsmith/flagsmith-cli#install
       weight: 1
@@ -53,13 +53,9 @@ params:
   footer:
     displayCopyright: false
     displayPoweredBy: false
-  # The reference is generated, so "edit this page" would point at a file that
-  # does not exist in the repository.
   editURL:
     enable: false
   page:
     width: normal
-  # Every page is a command, so the sidebar is the command tree and should be
-  # visible from the home page down.
   sidebar:
     displayTitle: false