From 02364b7003f2c9f29b76dc0283f881b9b840e257 Mon Sep 17 00:00:00 2001 From: Kim Gustyr Date: Mon, 24 Aug 2026 09:55:05 +0100 Subject: [PATCH 1/3] fix(docs): Command reference hides the sidebar on leaf pages --- cmd/docgen/main.go | 8 +++++++- cmd/docgen/main_test.go | 22 ++++++++++++++++++++++ website/hugo.yaml | 9 +++++++++ 3 files changed, 38 insertions(+), 1 deletion(-) diff --git a/cmd/docgen/main.go b/cmd/docgen/main.go index 29f5fa5..ee4a8a7 100644 --- a/cmd/docgen/main.go +++ b/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 "## " line cobra opens with, and the // blank line after it. func dropHeading(md []byte) []byte { diff --git a/cmd/docgen/main_test.go b/cmd/docgen/main_test.go index fc1e386..131a285 100644 --- a/cmd/docgen/main_test.go +++ b/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) + } +} diff --git a/website/hugo.yaml b/website/hugo.yaml index 407c78c..d908b1f 100644 --- a/website/hugo.yaml +++ b/website/hugo.yaml @@ -11,6 +11,15 @@ module: imports: - path: github.com/imfing/hextra +# Every page in the site is part of the command reference, so give the whole of +# content/ the theme's "docs" type. Without it the generated leaf pages (e.g. +# organisation/delete) fall back to the theme's plain single-page layout, which +# hides the sidebar, and the sidebar tree is rooted at the current top-level +# section rather than at the whole command tree. +cascade: + - _target: {} + type: docs + enableRobotsTXT: true # Generated pages have no git history of their own, so there is no # "last modified" worth showing. From 81665c1ce086a899134017e5d345383f8eaf4de4 Mon Sep 17 00:00:00 2001 From: Kim Gustyr Date: Mon, 24 Aug 2026 09:58:37 +0100 Subject: [PATCH 2/3] trim, comments --- website/hugo.yaml | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/website/hugo.yaml b/website/hugo.yaml index d908b1f..b6bf4a2 100644 --- a/website/hugo.yaml +++ b/website/hugo.yaml @@ -11,18 +11,11 @@ module: imports: - path: github.com/imfing/hextra -# Every page in the site is part of the command reference, so give the whole of -# content/ the theme's "docs" type. Without it the generated leaf pages (e.g. -# organisation/delete) fall back to the theme's plain single-page layout, which -# hides the sidebar, and the sidebar tree is rooted at the current top-level -# section rather than at the whole command tree. 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: @@ -35,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 @@ -62,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 From 8322703d67daad65e9242a64fac1e2478ed888bf Mon Sep 17 00:00:00 2001 From: Kim Gustyr Date: Mon, 24 Aug 2026 10:54:19 +0100 Subject: [PATCH 3/3] Use cascade.target, not the deprecated cascade._target --- website/hugo.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/hugo.yaml b/website/hugo.yaml index b6bf4a2..255fddf 100644 --- a/website/hugo.yaml +++ b/website/hugo.yaml @@ -12,7 +12,7 @@ module: - path: github.com/imfing/hextra cascade: - - _target: {} + - target: {} type: docs enableRobotsTXT: true