webook/docs/superpowers/specs/2026-05-29-toolbar-breadcrumb-design.md

Toolbar Breadcrumb Design

Goal

Replace the static toolbar title with a breadcrumb that reflects the current document location.

Target format:

Docs / 目录1 / 目录2 / 文件标题

The final segment uses the current file title instead of the raw file name.

Scope

In scope:

• Update the toolbar breadcrumb display in the reading view.
• Derive breadcrumb segments from the current markdown file path.
• Use the resolved markdown title for the last segment.
• Keep the breadcrumb display-only for now.

Out of scope:

• Clicking breadcrumb segments to navigate.
• Renaming directory segments with custom labels.
• Changing sidebar navigation behavior.

Data Source

The client already has the data needed for breadcrumb rendering:

• currentFile tracks the selected markdown file path.
• navTree contains file metadata, including titles extracted from markdown.
• initialContent and defaultFile cover first-load rendering.

No server-side schema changes are required for this feature.

Behavior

First load

• If the page loads with an initial document, render the breadcrumb immediately.
• If the page loads at / and auto-selects a homepage, render the breadcrumb for that file.

On file change

• When a new markdown file finishes loading, refresh the toolbar breadcrumb.
• Keep the final segment synced with the rendered file title.

Segment rules

• Always start with Docs.
• For files in the root directory, show Docs / 文件标题.
• For nested files, show each directory name in order, followed by the file title.
• If a file has no H1 title, fall back to the file name without extension.

Failure behavior

• If a hash points to a file that fails to load, do not replace the breadcrumb with a broken path.
• Keep the most recent valid breadcrumb until a valid file is rendered.

Implementation Plan

Template

Replace the single static toolbar title node with a breadcrumb container that the client can fully control.

Client logic

Add two small helpers in public/app.js:

• A title index builder that maps file paths to their resolved display titles from navTree.
• A breadcrumb renderer that splits currentFile into directory segments and appends the resolved file title as the last segment.

Call the breadcrumb renderer in both places that establish visible content:

• Initial content hydration
• Successful loadFile() completion

Styling

Keep the existing toolbar visual style, but allow breadcrumb segments to wrap the available width more gracefully:

• Directory segments may truncate first.
• The final file-title segment should remain most visible.
• Mobile layout should continue to fit within the existing toolbar structure.

Testing

Verify these cases:

• Root path auto-loads a homepage and shows Docs / 文件标题
• Root-level markdown file selection
• Nested markdown file selection
• Direct refresh on a deep hash URL
• Markdown file without an H1 title
• Narrow viewport layout does not break the toolbar

Review Notes

• Breadcrumb remains display-only by design.
• Directory labels come from real folder names, not markdown metadata.
• This change is intentionally client-side only to keep the diff narrow.