Summary
Add a new section property (e.g. root: true or a new top-level pages config) that creates
an isolated sidebar scope where the parent section title is excluded from the sidebar hierarchy
and its child sections are promoted to top-level sidebar items.
Current state
Today, standalone: true isolates a section into its own sidebar scope
(packages/core/src/sync/index.ts:380–408, runtime filtering in
packages/ui/src/theme/components/sidebar/sidebar-filter.ts:31–83), but the section title
still appears as the top-level group in both the sidebar and nav dropdown.
For example, a "Reference" section with standalone: true and children "API" and "CLI" renders as:
Reference ← nav dropdown
└─ API ← sidebar
└─ CLI
There's no way to make "API" and "CLI" appear as top-level sidebar items within the scope,
hiding "Reference" from the sidebar tree entirely.
Proposed scope
Introduce a root (or similar) property on Section that:
- Isolates the scope — same as
standalone, the section gets its own sidebar context
(scopes.json, resolveScopedSidebar())
- Promotes children — child sections are rendered as top-level sidebar items (no wrapping
parent group in the _meta.json output)
- Hides the parent title from sidebar — the section title is used only for nav/routing,
not as a sidebar heading
Affected areas
| Area |
File |
Change |
| Config type |
packages/config/src/types.ts:244–267 |
Add root?: boolean to Section |
| Config schema |
packages/config/src/schema.ts:99–121 |
Add root to Zod schema |
| Resolved type |
packages/core/src/sync/types.ts:115–150 |
Propagate root on ResolvedEntry |
| Meta generation |
packages/core/src/sync/sidebar/meta.ts:80–339 |
Promote children when root is set |
| Scope collection |
packages/core/src/sync/index.ts:380–408 |
Treat root sections as standalone scopes |
| Nav generation |
packages/core/src/sync/sidebar/index.ts:15–32 |
Decide nav behavior for root sections |
Example config
{
title: 'Reference',
path: '/references',
root: true, // children promoted to top-level sidebar items
items: [
{ title: 'API', path: '/references/api', include: 'docs/references/api/**' },
{ title: 'CLI', path: '/references/cli', include: 'docs/references/cli/**' },
],
}
Result: Navigating to /references/api shows a sidebar with "API" and "CLI" as top-level
headings — no "Reference" wrapper.
Open questions
- Naming:
root: true, flat: true, or a distinct top-level config key like pages?
- Should the nav item for a root section link to the first child, or show a dropdown?
- Should
root imply standalone automatically, or be independent?
Summary
Add a new section property (e.g.
root: trueor a new top-levelpagesconfig) that createsan isolated sidebar scope where the parent section title is excluded from the sidebar hierarchy
and its child sections are promoted to top-level sidebar items.
Current state
Today,
standalone: trueisolates a section into its own sidebar scope(
packages/core/src/sync/index.ts:380–408, runtime filtering inpackages/ui/src/theme/components/sidebar/sidebar-filter.ts:31–83), but the section titlestill appears as the top-level group in both the sidebar and nav dropdown.
For example, a "Reference" section with
standalone: trueand children "API" and "CLI" renders as:There's no way to make "API" and "CLI" appear as top-level sidebar items within the scope,
hiding "Reference" from the sidebar tree entirely.
Proposed scope
Introduce a
root(or similar) property onSectionthat:standalone, the section gets its own sidebar context(
scopes.json,resolveScopedSidebar())parent group in the
_meta.jsonoutput)not as a sidebar heading
Affected areas
packages/config/src/types.ts:244–267root?: booleantoSectionpackages/config/src/schema.ts:99–121rootto Zod schemapackages/core/src/sync/types.ts:115–150rootonResolvedEntrypackages/core/src/sync/sidebar/meta.ts:80–339rootis setpackages/core/src/sync/index.ts:380–408rootsections as standalone scopespackages/core/src/sync/sidebar/index.ts:15–32Example config
Result: Navigating to
/references/apishows a sidebar with "API" and "CLI" as top-levelheadings — no "Reference" wrapper.
Open questions
root: true,flat: true, or a distinct top-level config key likepages?rootimplystandaloneautomatically, or be independent?