Documents & Decisions

The Web interface provides browsing for document lists and decision records, grouped by subfolder, making it convenient to read project knowledge-base content in the browser.

Entering the Documents Page

After starting the Web interface, click the "Documents" tab in the top navigation bar to enter the document list page. The page displays all Markdown documents under backlog/docs/ in groups.

Browsing the Document List

The document list is automatically grouped by subfolder. For example:

• guides — guide documents
• api — API documents
• (root) — documents placed directly under docs/

Click a group title to expand or collapse the document entries under that folder. Each entry shows the title, a last-updated summary, and labels if any.

Sidebar Sort Toggles

The document area header in the sidebar provides Name / ID sort toggles. Click to switch the sort column and direction (↑ / ↓ shown next to the column name):

• Name: sort by document title (falls back to filename when there is no title), numeric-aware (doc-4 sorts before doc-10).
• ID: sort by document ID, with name as tie-breaker.
• Each folder level is sorted independently; folders are always listed before files.

The decisions area also provides Title / ID sort toggles; decisions are a flat list without folders. The three sidebar sections (Documents, Wiki, Decisions) share the same control style.

Viewing Document Content

Click a document title in the list to navigate to the document detail page. The document content is shown as rendered Markdown, including:

• Title and body
• Code blocks and syntax highlighting
• Tables and lists
• Images and links

Click the "Back" button at the top of the page or the browser back button to return to the document list.

In-Document Anchor Jumping

Title links inside the document body ([link](#section-name) form) smooth-scroll to the target within the current document context and update the address bar anchor, without jumping to the app root. Heading IDs are generated by a unified slug algorithm; human-readable TOC anchors (such as #A1, #A1: Section Title) are still parsed and located correctly. For documents linked by local short links, :line or :start-end line-range suffixes are also supported; clicking shows the specified line range in the preview box.

Links with anchors (such as /documentation/5#A2) also automatically scroll to the target heading on first load: after content is rendered asynchronously, an observer locates the heading, and the anchor in the address bar is preserved during URL normalization (bare IDs are completed with the title slug).

Documents also support direct positioning by ID: whether in the root directory or a subfolder, entering a bare ID (such as doc-20) or a plain number (20) opens the corresponding document accurately. When the ID is ambiguous, a fail-closed conflict hint is shown with a candidate list.

Table of Contents (TOC)

Document, decision, and Wiki detail pages provide a TOC button in the header: clicking expands the heading outline of the current page. The hierarchy comes from actually rendered headings (including duplicate headings and CJK headings):

• Click an entry to smooth-scroll to the corresponding section; as you scroll, the current section is highlighted in the TOC (scrollspy).
• Entries with subtrees can be collapsed; when there are many entries, deep levels are collapsed by default and the current branch is expanded automatically.
• The panel header provides "Collapse all / Expand all" master switches.
• The TOC button does not appear when the page has no headings or is in edit mode.

Task details, Wiki previews, and file preview modals have the same outline as a bookmark-style drawer protruding from the left edge of the modal (without changing modal width). See the "Outline Drawer" section in Task List.

Silent Reload on Content Changes

When a document is modified externally on disk, an already-open document page reloads silently based on a content fingerprint comparison: the body is updated only when the content actually changes, and scroll position and anchor are preserved. In edit mode the page does not reload, so unsaved input is not affected.

Mermaid Diagrams

```mermaid code blocks in document, decision, and Wiki bodies are rendered as diagrams: the fence language identifier is case-insensitive; diagram themes switch automatically with the interface light/dark mode; the Markdown editor preview pane also renders Mermaid.

Entering the Decision Records Page

Click the "Decisions" tab in the top navigation bar to enter the decision record (ADR) list page. The page shows all decision files under backlog/decisions/.

Each decision record displays:

• Decision title
• Current status (Proposed, Accepted, Rejected, Deprecated, Superseded)
• Creation date

Viewing Decision Details

Click any entry in the decision list to enter the decision detail page. The page renders the full ADR content, including sections such as background, considerations, final decision, and impact.

Decision status tags are distinguished by color, and status names are localized with the interface language (for example "已接受" in Chinese); non-standard statuses are shown as-is. Each status also has its own icon, so color is not the only distinguishing signal.

Creating a New Decision

The "+" button in the sidebar decisions area opens the new decision page: enter the title and body (images can be pasted and are automatically promoted to assets/paste/ on save); after saving, it navigates to the new decision page. If the body is left empty, the default "Context / Decision / Consequences" template is used.

Editing a Decision

The decision detail page has an Edit button in the upper-right corner: click to enter edit mode, where Cancel / Save button pairs appear; list refreshes during editing do not interrupt or overwrite your input; the ?edit=true deep link opens directly in edit mode.

In edit mode, you can directly modify the status in the header: the dropdown lists standard statuses such as proposed / accepted / rejected / superseded (displayed localized, stored values remain in the original English), or keeps the free-text status already in the data. Changing only the status does not rewrite the body.