Improve breadcrumb and code block controls

2026-05-29 15:08:44 +08:00
parent cf2d5fc77b
commit eb73d41d35
7 changed files with 465 additions and 54 deletions
@@ -0,0 +1,103 @@
+# 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.