Skip to content

Add three-level documentation navigation tree#5769

Draft
evnchn wants to merge 2 commits intozauberzeug:mainfrom
evnchn:docs/three-level-navigation-tree
Draft

Add three-level documentation navigation tree#5769
evnchn wants to merge 2 commits intozauberzeug:mainfrom
evnchn:docs/three-level-navigation-tree

Conversation

@evnchn
Copy link
Copy Markdown
Collaborator

@evnchn evnchn commented Feb 12, 2026

Motivation

Addresses feedback from discussion #5744 proposing a categorized three-level menu structure for the documentation sidebar. The current 2-level tree (Section > Element) becomes hard to scan as the number of elements grows. A 3-level tree (Section > Subsection > Element) groups related elements together, improving discoverability while preserving the curated semantic ordering.

Implementation

  • doc.intro_group() — new API similar to doc.intro(), but creates a group header with all of the target page's parts as children. The tree builder uses these children for the third nesting level.
  • DocumentationPart.children — new field enabling grouped parts for tree nesting without changing page rendering.
  • subsection_*.py modules (35 new files) — each defines a subsection title and uses doc.intro() to reference existing *_documentation.py modules. Section files now use doc.intro_group() to reference these subsection modules.
  • tree.py — updated to build 3-level hierarchy from grouped parts. Group nodes are always expanded via on_expand handler and CSS hiding of expand arrows.
  • rendering.py — renders grouped parts inline (group header + children) on section pages.
  • Clicking a group node navigates to its anchor on the parent section page (e.g., /documentation/section_controls#buttons).

Before (2-level):

Controls
├── Button
├── Button Group
├── Checkbox
├── Switch
└── ...

After (3-level):

Controls
├── Buttons
│   ├── Button
│   ├── Button Group
│   └── ...
├── Choices
│   ├── Checkbox
│   ├── Switch
│   └── ...
└── ...

Important

The specific grouping of elements into subsections and the UI/UX are to be finalized. This PR establishes the technical mechanism and proposes an initial grouping based on the community discussion. Feedback is welcome on:

  • Which elements belong together — Are the current subsection groupings intuitive?
  • Subsection naming — Are names like "Value & Interaction", "Editors & Structured Data" clear enough?
  • Group ordering — Alphabetical vs. curated semantic order within sections?
  • Sections with inline demos (Binding, Styling, Events) — grouped as-is but may benefit from restructuring
  • Tree UX — Group nodes are always expanded and non-collapsible. Should this change?

Progress

  • I chose a meaningful title that completes the sentence: "If applied, this PR will..."
  • The implementation is complete.
  • If this PR addresses a security issue, it has been coordinated via the security advisory process.
  • Pytests have been added (or are not necessary).
  • Documentation has been added (or is not necessary).

🤖 Generated with Claude Code

Introduces `doc.intro_group()` for 3-level tree nesting in the sidebar.
Each section now uses subsection modules to group related elements
(e.g., Controls > Buttons > Button, Button Group, etc.), improving
discoverability while preserving the curated semantic ordering.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@evnchn
Copy link
Copy Markdown
Collaborator Author

evnchn commented Feb 12, 2026

I am responsible for the UI decisions in this PR, and Claude Code is forced to implement it in a loop until the screenshots look right.

@evnchn evnchn added documentation Type/scope: Documentation, examples and website in progress Status: Someone is working on it labels Feb 12, 2026
@falkoschindler falkoschindler added this to the 3.9 milestone Feb 12, 2026
@falkoschindler
Copy link
Copy Markdown
Contributor

Maybe it's a good opportunity to also organize documentation *.py files in subfolders, mimicking the tree structure.

(Similarly we might want introduce subfolders for our tests/, mirroring the nicegui/ directory that is being tested. But that's for a separate PR.)

The flat content/ directory (~150 files) is now organized into subfolders
that mirror the documentation tree structure, improving navigability.
The doc framework module is renamed to _doc/ to distinguish it from
content sections.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@evnchn evnchn added help wanted Status: Author is inactive, others are welcome to jump in and removed in progress Status: Someone is working on it labels Mar 8, 2026
@falkoschindler falkoschindler removed this from the 3.9 milestone Mar 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Type/scope: Documentation, examples and website help wanted Status: Author is inactive, others are welcome to jump in

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants