From fd07609aefe346aa448b76e2dad4a340ea2a2a71 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 16 Oct 2025 13:22:02 -0400 Subject: [PATCH 1/2] Adds support for "self" sidebar roots --- .../content/en/docs/get-started/_index.md | 1 + docsy.dev/package.json | 1 + layouts/_partials/sidebar.html | 28 +++++++++---- package.json | 2 +- tasks/sidebar-root-feature.plan.md | 40 ++++++++++++------- 5 files changed, 49 insertions(+), 23 deletions(-) diff --git a/docsy.dev/content/en/docs/get-started/_index.md b/docsy.dev/content/en/docs/get-started/_index.md index afae0e03fe..738cc67a32 100644 --- a/docsy.dev/content/en/docs/get-started/_index.md +++ b/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. diff --git a/docsy.dev/package.json b/docsy.dev/package.json index 0e157f1db5..a3598bfd56 100644 --- a/docsy.dev/package.json +++ b/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", diff --git a/layouts/_partials/sidebar.html b/layouts/_partials/sidebar.html index 35f87c3d7c..c341f16507 100644 --- a/layouts/_partials/sidebar.html +++ b/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 diff --git a/package.json b/package.json index bb4cff611a..431665ae5c 100644 --- a/package.json +++ b/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", diff --git a/tasks/sidebar-root-feature.plan.md b/tasks/sidebar-root-feature.plan.md index c147373a62..e4fb5da9ae 100644 --- a/tasks/sidebar-root-feature.plan.md +++ b/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,21 @@ 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 +112,19 @@ 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) -Note that viewing the index page of `/docs/adding-content/` will still show the -full docs navigation tree. +**With `sidebar_root_for: self`:** +- 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 From 6d744da90aa9aa834ef7b0a15e4c92ddb9d50f51 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 16 Oct 2025 13:28:54 -0400 Subject: [PATCH 2/2] Adjust tree-root link for "self" roots: link to parent page --- docsy.dev/content/en/docs/adding-content/_index.md | 2 +- docsy.dev/content/en/docs/best-practices/_index.md | 1 + layouts/_partials/sidebar-tree.html | 5 +++++ tasks/sidebar-root-feature.plan.md | 9 +++++++-- 4 files changed, 14 insertions(+), 3 deletions(-) diff --git a/docsy.dev/content/en/docs/adding-content/_index.md b/docsy.dev/content/en/docs/adding-content/_index.md index 987330fd4b..ebc59cb78b 100644 --- a/docsy.dev/content/en/docs/adding-content/_index.md +++ b/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 --- diff --git a/docsy.dev/content/en/docs/best-practices/_index.md b/docsy.dev/content/en/docs/best-practices/_index.md index fb1ee788d6..cd8c0e6455 100644 --- a/docsy.dev/content/en/docs/best-practices/_index.md +++ b/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. diff --git a/layouts/_partials/sidebar-tree.html b/layouts/_partials/sidebar-tree.html index e309fd10cb..ddd6d8ba33 100644 --- a/layouts/_partials/sidebar-tree.html +++ b/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 -}}