# Boardwalk

A lean, modern kanban board plugin for [Obsidian](https://obsidian.md) — drag-and-drop task boards in plain Markdown, with first-class per-card move history.

Boardwalk reads and writes the same Markdown board format as the [Kanban plugin](https://github.com/obsidian-community/obsidian-kanban) by mgmeyers, which it uses as its feature reference (with gratitude). Boards are plain Markdown files: `## headings` are lanes, `- [ ]` list items are cards. Your data is never locked in — every board opens in either plugin, or in any text editor.

## Why another kanban plugin

The original Kanban plugin is excellent but effectively unmaintained since mid-2024. Boardwalk is a from-scratch reimplementation of the subset that matters most to its author, plus the features the original never shipped:

- **Move history** — every card records which lanes it has lived in and when (optionally with time of day), stored as a hidden comment block in the Markdown itself, ready for later analysis
- **Multi-select** — Ctrl/Cmd-click several cards and drag them together
- **Edits save on blur** — no lost edits when focus leaves a card
- **Undo/redo on the board** — Ctrl/Cmd+Z / Ctrl/Cmd+Shift+Z, plus pane-header buttons
- Tri-state checkboxes, important-card marking, per-tag colors, due-date chips with a picker, drag-to-reorder lanes, an archive browser, search (Ctrl/Cmd+F), and safe handling of files changed externally (sync)

**[→ User guide](docs/user-guide.md)** — how to use everything below, with shortcuts.

## Features

### Boards

- Lanes drag-reorder by their header, collapse to a narrow strip (chevron in the lane header, stored compatibly with the original plugin's `list-collapse` setting)
- A lane renamed (double-click its title) to end in `(N)` — e.g. `Doing (3)` — gets a work-in-progress limit; the count turns red when exceeded. Visual signal only, nothing is blocked
- A lane can be flagged **Complete** from its menu ("Mark cards complete on entry"): cards moved into it are checked automatically. Moving a card out never un-checks it — the checkbox is otherwise yours
- The archive keeps finished cards out of view without deleting them: toolbar archive icon → browse, restore to any lane, or delete

### Cards

- Click a card to edit; edits commit when focus leaves. Escape cancels
- Clicking the checkbox cycles unchecked → in progress (`- [/]`) → checked, rendered with your theme's own task-checkbox styling
- `Ctrl/Cmd+!` (hovered card or the whole selection), or the context menu, toggles `#important` — red edge, red pill
- Due dates: `@{YYYY-MM-DD}` on the card renders as a relative chip (overdue red, today orange); set or change it from the context menu or by clicking the chip
- Internal links open on click (Ctrl/Cmd-click for a new tab) and show the Page Preview popover on hover
- Every card touched by Boardwalk gets a stable block ID (`^abc123`), so cards are linkable: context menu → "Copy link to card"

### Move history

Boardwalk appends a ledger to the board file recording, per card, when it entered each lane:

```
%% boardwalk-history:
abc123: 2026-08-20 Backlog | 2026-08-24 09:15 Doing
%%
```

Plain ISO dates in an Obsidian comment — invisible in reading view, harmless to other tools. "Include time in move history" (on by default) adds `HH:mm`. Entries are healed if a card is found in a different lane than the ledger claims (e.g. after a raw-Markdown edit).

**Caveat:** the original Kanban plugin rebuilds board files on save and silently drops the ledger. Boardwalk therefore mirrors every board's history into its own plugin data as a backup; if a board's ledger goes missing while a backup exists, Boardwalk offers a one-click restore banner — it never silently rewrites your file.

## Install

Install from Obsidian's **Community plugins** browser (search "Boardwalk" or "kanban"), or from the [directory listing](https://community.obsidian.md/plugins/boardwalk). Alternatives:

- **BRAT**: add this repository in [BRAT](https://github.com/TfTHacker/obsidian42-brat)
- **Manual**: copy `main.js`, `manifest.json`, and `styles.css` from the [latest release](https://github.com/zeiosmb/obsidian-boardwalk/releases/latest) into `<vault>/.obsidian/plugins/boardwalk/` and enable the plugin

Files with `kanban-plugin` frontmatter open as boards automatically; the view toggles back to raw Markdown from the pane menu or the "Toggle board / markdown view" command.

Desktop only for now (mobile later — the original plugin reads the same files in the meantime).

## Building from source

```
npm install
npm run build   # typecheck + bundle → main.js
npm test        # parser round-trip and ops tests
```

The parse⇄serialize round-trip tests are the safety net: a board written by the original plugin re-saves byte-identical.

## License

GPL-3.0 (see [LICENSE](LICENSE)). Boardwalk is an independent, from-scratch reimplementation that is file-format-compatible with [obsidian-kanban](https://github.com/obsidian-community/obsidian-kanban) © mgmeyers (GPL-3.0), which served as the feature reference.