Settings & Theme

The settings page centrally manages Backlog.md configuration items, Definition of Done defaults, and Web interface theme preferences. The task editor also provides rich editing capabilities in the settings-related area.

Entering the Settings Page

After starting the Web interface, click the "Settings" tab in the top navigation bar to enter the settings page. The page is divided into multiple configuration blocks arranged from top to bottom.

Viewing and Modifying Configuration Items

In the "Configuration" block, you can view and edit currently effective parameters, including:

  • Default assignee (defaultAssignee): a list-type setting automatically applied when a task/draft is created without an explicit assignee.
  • Labels (labels): editor for the project's predefined label list.
  • Default editor (defaultEditor): clearing this field disables the default editor (the service default code --wait can hang unattended agent processes).
  • Web server port: defaultPort and the automatic-port toggle (automatically use the next available port when the default is occupied).
  • Hide empty status columns (hideEmptyColumns): when enabled, the board hides status columns with no tasks, reducing visual clutter; all status columns remain visible while dragging a task so it can be dropped.
  • Auto-open browser (autoOpenBrowser).
  • Task resolution strategy (taskResolutionStrategy): conflict-resolution strategy when tasks with the same name exist in multiple branches—most_recent (take the most recently modified version) or most_progressed (take the version whose status has advanced the furthest, falling back to modification time when progress is equal); new projects default to most_recent.
  • Advanced Settings cross-branch toggles: below Task Resolution Strategy are Cross-Branch Tasks (includeCrossBranch, default off—whether scanned tasks from other branches appear in board/task list/search), Check Active Branches (checkActiveBranches, default on—whether to scan other local branches, also determines the candidate branch set for task ID allocation), and Active Branch Days (activeBranchDays, default 30 days, shown only when the scan toggle is on).
  • Diagram engine (diagramEngine): which engine renders Mermaid diagrams—pele (default, open-sourced by the Obsidian team, zero-dependency, renders Mermaid 12.1.0 syntax to SVG) or mermaid (11.16.1 fallback); the choice is persisted to the diagram_engine key in config.yml and remains effective after restarting the browser. It affects only Mermaid diagrams, not ECharts data charts.
  • Git-related options (see Configuration Management).

Click the item you want to modify, enter the new value, and click the "Save" button. Configuration changes are written back to the project configuration file immediately; some settings (such as port) take effect after restarting backlog browser.

List-type settings (default assignee, labels) are presented as a list editor: you can add or remove items one by one, and they are written back to the YAML list in the configuration file on save. These settings are the same configuration modified by backlog config set; both entry points see each other's changes.

Default assignee takes effect when creating a task: if no assignee is specified, the default is applied; an explicit assignee completely replaces the default (no merge). Clearing the assignee chips in the creation form saves an empty value and does not fall back to the default.

State Machine Editor

The settings page provides a state machine editor for visually maintaining the object-form statuses configuration in backlog/config.yml—previously only editable by hand. The editor uses a left-right layout:

  • Left state card list: add, delete, and edit states (name, category, exit action, display flag), and maintain each state's next transitions (target to, condition when, AI autonomy level ai, prerequisite if, required evidence requires / evidence); supports multi-select terminal statuses.
  • Right Mermaid live preview: a migration tree recursively expanded from the initial state along next, with back edges and cycles degraded to dashed back-references so they do not expand infinitely.
  • Layout toggle: switch between card layout and tab layout.

The two restore buttons have strictly distinct semantics:

  • Reset: appears only when there are unsaved changes; discards edits and reloads the current content from config.yml (never overwrites the file).
  • Default: replaces the current configuration with the built-in seven-state default state machine (equivalent to a factory reset).

The state machine is declarative, not enforced: the editor can show lint warnings but will not block saving; after saving, the server broadcasts config-updated, and board columns and terminal-status determination refresh immediately. The three AI-facing overviews (CLI backlog instructions overview, MCP resources, and instruction tools) automatically render the same state machine, and agents work according to the declared machine. See Task Lifecycle for state machine semantics.

The terminal-status set is derived from the state machine and is the only place to change it: the settings page previously had a "terminal status" multi-select, but it did not store a list; instead it silently rewrote each state's category—conflicting with the state machine editor writing the same field. Now the settings page only shows the derived terminal-status set (such as Done, Dropped) as read-only with a source note; backlog config list also prints terminalStatuses: [Done, Dropped] (derived from statuses). To add or remove terminal statuses, modify the corresponding state's category in the state machine editor above.

Editing Definition of Done Defaults

In the "Definition of Done" block, you can view and edit the default completion criteria checklist automatically attached to new tasks.

Click the text editing area and enter or modify DoD items, one per line. After saving, new tasks created through the Web interface or CLI will carry the updated default DoD list.

Customizing the Web UI Theme

In the "Theme" block, you can switch the interface appearance:

  • Follow system — automatically match the operating system's light or dark mode setting.
  • Light mode — force a light background theme.
  • Dark mode — force a dark background theme.

After switching, the entire Web interface color scheme takes effect immediately without refreshing the page. The preference is saved locally in the browser and restored automatically on the next visit.

Language Switching

In the "Language" dropdown in the "Project Settings" block, you can choose the Web interface display language:

  • English
  • 日本語 (Japanese)
  • 简体中文 (Simplified Chinese)
  • 繁體中文 (Traditional Chinese)

After selecting a language, interface text switches immediately without refreshing the page. The language preference is saved together with the project configuration to the locale field in backlog/config.yml (or the project root configuration) and restored automatically the next time the Web interface starts.

The language setting is persisted only after clicking the "Save changes" button to write it to the configuration file. Switching language before saving previews the new language immediately, but refreshing the page reverts to the last saved setting.

Using the Task Editor

Click any task in the Web interface to enter the task editor page. The editor provides rich forms and Markdown editing capabilities.

Rich-Text Markdown Editor

The task description area uses the MDEditor rich-text editor. You can type Markdown syntax directly; the editor provides real-time preview and common formatting shortcut buttons:

  • Heading levels
  • Bold, italic, strikethrough
  • Unordered and ordered lists
  • Code blocks and blockquotes
  • Links and tables

Interactive Acceptance Criteria Checklist

Find the "Acceptance criteria" area in the task editor. Each acceptance criterion has a checkbox on the left; click to mark it complete or incomplete. The checked state is automatically synced and saved to the corresponding section of the Markdown file.

When checking multiple acceptance criteria or DoD items in the Web popup preview mode, the system batches saves: it waits about one second of inactivity before sending a single request (carrying the complete checked array), rather than sending a request on every click. Any unsaved checks are flushed immediately before the popup closes; if it fails, they roll back to the server's known state. This prevents a request storm when working through a long checklist and makes board and task-list refreshes smoother.

If you manually modify the acceptance criteria format in the Markdown source file, the editor automatically repairs and syncs the list structure when loading, ensuring checkboxes display correctly.

Task Content Outline

For tasks with longer content, the editor shows a "Contents" (TOC) panel on the right. The outline automatically extracts headings at all levels from the task body; click any heading to quickly scroll to the corresponding position. As you scroll, the outline highlights the current section.

Rich Form Fields

A set of structured form fields is provided at the top of the editor; click to modify:

  • Status — dropdown selection of Todo, In Progress, Done, etc.
  • Priority — choose High, Medium, Low.
  • Labels — enter label names, supports multiple labels.
  • Milestone — dropdown to select an existing milestone or leave blank.
  • Assignee — enter assignee name.
  • Dependencies — add IDs of other tasks this task depends on.
  • References — add referenced tasks or external links.

After modifying any field, click the "Save" button at the bottom of the page; the changes are written back to the Markdown file.

Automatic Mermaid Diagram Rendering

If the task body contains Mermaid syntax code blocks, the Web interface automatically renders them as visual diagrams, including flowcharts, sequence diagrams, Gantt charts, etc. No extra action is needed; the diagram appears immediately after saving the task. The Pele engine is used by default; you can switch to the Mermaid 11.16.1 fallback in the Diagram Engine dropdown on the settings page (see the "Diagram engine" configuration item above).

Images and Attachment Viewing

Images referenced in tasks (such as ![description](assets/xxx.png)) are displayed directly as previews in the editor. Click a preview to view the original image in a new tab.

Files under the project's backlog/assets/ directory are automatically served by the Web server, ensuring all attachments and screenshots load normally in the Web interface.

results matching ""

    No results matching ""