kanban-markdown

Kanban Markdown

Manage kanban board features stored as markdown files with YAML frontmatter. Each feature is a .md file; the VS Code kanban-markdown extension renders them as a board.

File Format

Every feature file follows this exact format:

---
id: "my-feature-2026-02-20"
status: "backlog"
priority: "medium"
assignee: null
dueDate: null
created: "2026-02-20T10:00:00.000Z"
modified: "2026-02-20T10:00:00.000Z"
completedAt: null
labels: []
order: "a0"
---

# My Feature

Description and details here.

Serialization rules (must match exactly for the extension to parse correctly):

• String fields: always "double-quoted"
• Nullable fields (assignee, dueDate, completedAt): bare null when unset
• Labels: inline array ["bug", "ui"] or []
• Order: "double-quoted" string — fractional index for lexicographic sorting (see below)
• Field order: id, status, priority, assignee, dueDate, created, modified, completedAt, labels, order

Valid values:

• status: backlog | todo | in-progress | review | done
• priority: critical | high | medium | low

For full field specs, see references/data-model.md.

Features Directory

Default: .devtool/features/ relative to workspace root. Configurable via VS Code setting kanban-markdown.featuresDirectory.

• Active features (backlog, todo, in-progress, review): {featuresDir}/{id}.md
• Completed features (done): {featuresDir}/done/{id}.md

Fractional Index Ordering

The order field uses fractional indexing — lexicographically sortable strings that allow inserting between any two items without reindexing. The extension uses the fractional-indexing npm package internally.

When creating features, determine the order by reading existing features in the target column (sorted by order):

• If the column is empty: use "a0"
• To append after the last item: increment the trailing character — "a0" → "a1", "a1" → "a2", ..., "a9" → "aA", etc.
• The full character sequence is 0-9, A-Z, a-z (base-62, ASCII order)