TODO Board

The TODO board renders a markdown file as an interactive checklist with TODO and DONE sections. Each item is a checkbox entry that can be toggled, edited inline, and reordered — all backed by plain markdown.

Overview

The TODO board is an alternative view for managing task lists within the app. Instead of editing markdown directly, you interact with a structured checklist UI. Every operation writes back to the same markdown file, keeping it compatible with version control and external tools like Claude Code.

Getting Started

Enable TODO View

1. Keyboard shortcut — Press Mod+Shift+T to toggle between the standard editor view and the TODO board.

2. Command palette — Open the command palette with Mod+K and select "Toggle TODO View".

Markdown Format

A TODO file is a standard markdown file with YAML frontmatter, followed by ## TODO and ## DONE sections of checkbox items.

Frontmatter

The frontmatter identifies the file as a TODO list. type: todo should be the first field — it tells the app to render this file as a TODO board instead of the standard editor view. The parser accepts it anywhere in the frontmatter, but the serializer always writes it first:

---
type: todo
title: Sprint Tasks
---

Legacy todo: true Frontmatter

Earlier versions of zudo-text identified TODO files with todo: true instead of type: todo. The parser still accepts this legacy form, so existing lists continue to open without changes. New lists should use type: todo.

See Migration below for details on how legacy files upgrade.

Sections

Items live under two ## headings: ## TODO holds unchecked items, and ## DONE holds checked items. Either section may be empty or omitted.

## TODO

- [ ] Write unit tests
- [ ] Update documentation

## DONE

- [x] Set up CI pipeline

Structural rules:

• Unchecked items use - [ ] (hyphen, space, open bracket, space, close bracket).

• Checked items use - [x] (or - [X]).

• Items in ## TODO are treated as unchecked; items in ## DONE are treated as checked. When an item is toggled, it moves to the matching section on the next save.

Task Body

Each item can carry an optional body — free-form notes, context, or subtasks. The body lives on the line immediately after the task line, indented by exactly 2 spaces. There must be no blank line between the task line and its body:

- [ ] Write unit tests
  Cover the parser and serializer.
  Include edge cases for empty sections.
- [ ] Update documentation

Structural rules:

• The body begins on the very next line after the task line. A blank line between them terminates the item with no body.

• Every body line is indented by 2 spaces. Lines with other indentation are ignored.

• Multiple body lines are preserved in order and joined as a multi-line body.

• Unindented, non-checkbox lines inside a section are ignored by the parser.

Item IDs

Item IDs are generated by slugifying the item title. Duplicate titles receive a numeric suffix to stay unique within the file.

Operations

Toggle Item

Click the checkbox to toggle an item between TODO and DONE. The item moves to the appropriate section on the next save.

Add Item

Click the "+ Add" button at the bottom of the TODO section. Type the item title and press Enter to create it.

Edit Item

Double-click an item title to edit it inline. Press Enter to confirm or Escape to cancel.

Remove Item

Click the delete button on an item to remove it from the list.

AI-Friendly Format

The TODO markdown format is designed to work well with AI tools like Claude Code:

• Single-file state — The entire checklist is one markdown file.

• Standard checkbox syntax — - [ ] and - [x] are universally understood.

• Flat structure — Every item is a single bullet under ## TODO or ## DONE, with an optional indented body. Edits map to simple line-level changes.

• Human-readable — The format works as plain markdown even without the TODO board UI.

Migration

If you have existing TODO files that use the legacy todo: true frontmatter, you don't need to do anything — the parser continues to accept them.

When the app next saves a legacy file (for example, after you toggle an item, add a task, or edit a title), the frontmatter is automatically rewritten from:

---
todo: true
title: Sprint Tasks
---

to the canonical form:

---
type: todo
title: Sprint Tasks
---

This is a one-time upgrade per file. The rest of the file — sections, items, bodies — is preserved exactly. If you'd rather migrate immediately without waiting for a save, open the file and make any small change (toggle a task and toggle it back, or edit and revert); the next write normalizes the frontmatter.

Example List

A complete TODO file:

---
type: todo
title: Sprint 12
---

## TODO

- [ ] Write unit tests
  Cover the parser and serializer.
  Include edge cases for empty sections.
- [ ] Update documentation

## DONE

- [x] Set up CI pipeline
  Configured GitHub Actions for test + build.
- [x] Draft sprint plan

Empty-state guidance

An unconfigured TODO frame explains the feature with an illustration and Manual link while retaining the existing file/create controls. An invalid TODO file shows the Markdown skeleton and offers Choose another file when the host provides a file picker.