Skip to content

feat: add "root" section type for flat sidebar grouping without parent title #93

@zrosenbauer

Description

@zrosenbauer

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:

  1. Isolates the scope — same as standalone, the section gets its own sidebar context
    (scopes.json, resolveScopedSidebar())
  2. Promotes children — child sections are rendered as top-level sidebar items (no wrapping
    parent group in the _meta.json output)
  3. 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?

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or improvement

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions