Add support for "self" sidebar roots (#2341)

Author: chalin

docsy.dev/content/en/docs/adding-content/_index.md

@@ -2,5 +2,5 @@
 title: Content and Customization
 weight: 3
 description: How to add content to and customize your Docsy site.
-sidebar_root_for: children
+sidebar_root_for: self
 ---

docsy.dev/content/en/docs/best-practices/_index.md

@@ -3,6 +3,7 @@ title: "Best Practices"
 weight: 9
 description: >
   Optional guidance and recommendations about organizing, authoring, and managing your technical documentation.
+sidebar_root_for: children
 ---
 
 Use this section to learn about some of the best practices around creating technical documentation with Docsy.

docsy.dev/content/en/docs/get-started/_index.md

@@ -7,6 +7,7 @@ date: 2018-07-30
 description:
   Learn how to get started with Docsy, including the available options for
   installing and using the Docsy theme.
+sidebar_root_for: self
 ---
 
 As you saw in our introduction, Docsy is a [Hugo](https://gohugo.io) theme, which means that if you want to use Docsy, you need to set up your website source so that the Hugo static site generator can find and use the Docsy theme files when building your site. The simplest way to do this is to copy and edit our example site, though we also provide instructions for adding the Docsy theme manually to new or existing sites.

docsy.dev/package.json

@@ -20,6 +20,7 @@
     "check:links": "npm run _check:links",
     "clean": "rm -Rf public",
     "fix:format": "npm run _check:format -- --write",
+    "fix": "npm run fix:format && npm run _refcache:prune",
     "make:public": "git init -b main public",
     "postbuild:preview": "npm run _check:links--warn",
     "postbuild:production": "npm run _check:links--warn",

layouts/_partials/sidebar-tree.html

@@ -110,6 +110,11 @@
         $s.Params.manualLinkTitle
         $s.Title
   -}}
+  {{ if and $treeRoot (eq $s.Params.sidebar_root_for "self") -}}
+    {{ with $s.Parent -}}
+      {{ $manualLink = .RelPermalink -}}
+    {{ end -}}
+  {{ end -}}
   <li class="td-sidebar-nav__section-title td-sidebar-nav__section
         {{- if $withChild }} with-child{{ else }} without-child{{ end -}}
         {{ if $activePath }} active-path{{ end -}}

layouts/_partials/sidebar.html

@@ -7,16 +7,30 @@
 {{ $sidebarRoot := .FirstSection -}}
 {{ $navRoot := cond (and (ne .Params.toc_root true) (eq .Site.Home.Type "docs")) .Site.Home .FirstSection -}}
 {{ if .Site.Params.ui.sidebar_root_enabled -}}
-  {{ range .Ancestors.Reverse -}}
-    {{ if not (and .IsSection (eq .Params.sidebar_root_for "children")) -}}
-      {{ continue -}}
-    {{ end -}}
+  {{ if and .IsSection (eq .Params.sidebar_root_for "self") -}}
     {{ $sidebarRoot = . -}}
-    {{/* Warn if sidebar_root_for is set on a top-level section */ -}}
-    {{ if or (eq . $.Site.Home) (eq . $navRoot) -}}
-      {{ warnf "sidebar_root_for is set on a top-level section (%s). This parameter is intended for nested sections only." .Path -}}
+  {{ else -}}
+    {{/* Check ancestors for sidebar_root_for (any value) */ -}}
+    {{ range .Ancestors.Reverse -}}
+      {{ if not .IsSection -}}
+        {{ continue -}}
+      {{ end -}}
+      {{ $rootFor := .Params.sidebar_root_for -}}
+      {{ if not $rootFor -}}
+        {{ continue -}}
+      {{ end -}}
+      {{ if not (or (eq $rootFor "self") (eq $rootFor "children")) -}}
+        {{ warnf "%s: sidebar_root_for should be 'self' or 'children'. Invalid value: '%s'." .Path $rootFor -}}
+        {{ continue -}}
+      {{ end -}}
+      {{ $sidebarRoot = . -}}
+      {{ break -}}
     {{ end -}}
   {{ end -}}
+  {{/* Warn if sidebar_root_for is set on a top-level section */ -}}
+  {{ if and $sidebarRoot.Params.sidebar_root_for (eq $sidebarRoot $navRoot) -}}
+    {{ warnf "%s: sidebar_root_for is set on a top-level section. This parameter is intended for nested sections only." $sidebarRoot.Path -}}
+  {{ end -}}
 {{ end -}}
 {{ $sidebarRootID := $sidebarRoot.RelPermalink -}}
 {{ $args := dict

package.json

@@ -23,7 +23,7 @@
     "ci:prepare": "npm run docsy.dev-install && npm run _prepare && npm run _diff:check",
     "docsy.dev-install": "npm run _cd:docsy.dev -- npm install",
     "fix:format": "npm run _check:format -- --write && npm run cd:docsy.dev fix:format",
-    "fix": "npm run fix:format",
+    "fix": "npm run fix:format && npm run cd:docsy.dev fix",
     "get:hugo-modules": "node scripts/getHugoModules/index.mjs",
     "postinstall": "npm run _mkdir:hugo-mod",
     "test:all": "npm run ci:prepare && npm run check && npm run cd:docsy.dev test && npm run ci:post",

tasks/sidebar-root-feature.plan.md

@@ -17,11 +17,11 @@ deeply nested documentation sections.
 
 ## Feature characteristics
 
-- New `sidebar_root_for` parameter set in section `_index.md`. Values:
-  `children` (current implementation) and `self` (planned).
-- When `sidebar_root_for: children`, descendant pages (but not the section
-  itself) show the rooted sidebar. When `sidebar_root_for: self`, both the
-  section and its descendants show the rooted sidebar.
+- New `sidebar_root_for` parameter set in section `_index.md` with two values:
+  - `children`: Rooted sidebar shown only for descendant pages
+  - `self`: Rooted sidebar shown for the section itself and all descendants
+- Nested sidebar_root_for sections are supported: descendant pages use the
+  closest ancestor with `sidebar_root_for` set
 - Include navigation out of a sidebar-root section.
 - Work alongside existing `toc_root` feature (not replace it)
 - Warn if `sidebar_root_for` is set on a top-level section (including site home
@@ -41,11 +41,23 @@ interaction handling is required.
 
 ### 1. Update `layouts/_partials/sidebar.html` - Find sidebar root and update cache key
 
-- Walk up page ancestors to find section with `sidebar_root_for: children`
+**Support both `children` and `self` values:**
+
+- If current page is a section with `sidebar_root_for: "self"`, use it as
+  sidebar root
+- Otherwise, walk up ancestors to find any section with `sidebar_root_for`
+  (either `"self"` or `"children"`)
+- Use the closest match as sidebar root
 - Use sidebar_root section's permalink as cache key
 - Warn if `sidebar_root_for` is set on a top-level section
 - Pass `sidebarRoot` to `sidebar-tree.html` as parameter
 
+**Logic:**
+
+1. Check if current page has `sidebar_root_for: "self"` → use it
+2. Else check ancestors for `sidebar_root_for` (any value) → use first match
+3. Result: `self` applies to section itself, `children` only to descendants
+
 ### 2. Add link back to sidebar-root section index page
 
 The current implementation of the sidebar tree, already has the sidebar tree
@@ -102,19 +114,22 @@ sidebar_root_for: children
 ---
 ```
 
-When viewing any page under `/docs/adding-content/` (such as
-`/docs/adding-content/content/`), the sidebar will show only the "Content and
-Customization" section and its children, instead of the full docs navigation
-tree. This makes the sidebar more focused for users working within this
-subsection.
+**With `sidebar_root_for: children`:**
+
+- Viewing `/docs/adding-content/` index → shows **full** docs navigation
+- Viewing `/docs/adding-content/content/` → shows **rooted** sidebar (only
+  "Content and Customization" and its children)
+
+**With `sidebar_root_for: self`:**
 
-Note that viewing the index page of `/docs/adding-content/` will still show the
-full docs navigation tree.
+- Viewing `/docs/adding-content/` index → shows **rooted** sidebar
+- Viewing `/docs/adding-content/content/` → shows **rooted** sidebar
+- Both the section itself and descendants get the focused navigation
 
 ### To-dos
 
-- [x] Step 1: Implement sidebar_root_for lookup and cache key logic in
-      sidebar.html
+- [ ] Step 1: Update sidebar_root_for lookup to support both "self" and
+      "children" values
 - [ ] Step 2: Add link back to site root section index page
 - [ ] Step 3: Add breadcrumb navigation UI (OPTIONAL/FUTURE)
 - [x] Step 4: Use sidebar_root_for for $navRoot calculation in sidebar-tree.html