104 lines
3.2 KiB
Markdown
104 lines
3.2 KiB
Markdown
# 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.
|