Kanban Todo Board

Kanban Todo Board

Kanban boards for Obsidian, stored as plain files in your vault. Plan with an Eisenhower matrix, put a column in order with a priority duel, keep a log of everything you have finished, and watch a radar chart grow as you complete labelled work. Available in English and German.

---

Why this plugin

Boards are .kanban files sitting in your vault next to your notes — plain JSON, versionable with git, syncable with whatever you already use, readable without the plugin. Nothing lives in a hidden database.

On top of the board there are three views that read from every board in the vault:

Inside a board, any column can also be put in order with a priority duel: pick the more important of two cards, again and again.

---

Installation

Not in the community plugin list yet. The plugin is awaiting review by the Obsidian team. Until it is listed, install it with BRAT (easiest, updates itself) or manually from a GitHub release. Both put the plugin in the same place, so you can switch between them later — and once the plugin is listed, the official install simply takes over.

Option A: BRAT (recommended)

BRAT installs plugins straight from GitHub releases and keeps them up to date. Works on desktop and mobile.

1. Settings → Community plugins → turn off Restricted mode (if it is on)
2. Browse → search for BRAT → Install → Enable
3. Open the command palette (Cmd/Ctrl + P) → BRAT: Add a beta plugin for testing
4. Paste jakobeilts/kanban-levelup-obsidian and confirm
5. Settings → Community plugins → enable Kanban Todo Board

Updating with BRAT: BRAT checks for new releases when Obsidian starts (if Auto-update plugins at startup is on in the BRAT settings). To update right away: command palette → BRAT: Check for updates to all beta plugins and UPDATE, then reload Obsidian (Cmd/Ctrl + P → Reload app without saving).

Option B: Manual install from a release

1. Open the latest release and download the three files main.js, manifest.json and styles.css (not the source code zip)
2. Open your vault folder and go to .obsidian/plugins/. Create the folder kanban-level-up there if it does not exist
3. Put the three files directly into that folder:

   <YourVault>/.obsidian/plugins/kanban-level-up/
   ├── main.js
   ├── manifest.json
   └── styles.css
   

4. In Obsidian: Settings → Community plugins → turn off Restricted mode → enable Kanban Todo Board (click the reload icon next to Installed plugins if it does not show up yet)

The .obsidian folder is hidden. On macOS press Cmd + Shift + . in Finder to show it; on Windows enable Hidden items in the Explorer View menu. Not sure where your vault is? In Obsidian, click the vault name in the bottom-left corner → Manage vaults.

From the terminal (macOS/Linux), with the three files in your Downloads folder:

VAULT="$HOME/path/to/YourVault"          # quotes matter if the path contains spaces
mkdir -p "$VAULT/.obsidian/plugins/kanban-level-up"
cp ~/Downloads/{main.js,manifest.json,styles.css} "$VAULT/.obsidian/plugins/kanban-level-up/"

Updating from an older version

Already have an earlier version (for example 1.0.0)? Your boards and settings carry over — you only swap the program files.

If you installed with BRAT: see Updating with BRAT above.

If you installed manually:

1. Download main.js, manifest.json and styles.css from the latest release
2. Copy them into <YourVault>/.obsidian/plugins/kanban-level-up/ and replace the existing files
3. Reload Obsidian: Cmd/Ctrl + P → Reload app without saving (or turn the plugin off and on again under Community plugins)
4. Check the version under Settings → Community plugins → Kanban Todo Board

What to keep in mind:

• Do not delete the plugin folder to "start clean". Besides the three program files it contains data.json with your labels, skill chart scores and settings. Replace only the three files.
• Your boards are safe either way. They are the .kanban files in your vault, not part of the plugin folder.
• Folder name must be kanban-level-up (the plugin ID). Version 1.1.0 used the ID kanban-todo-board by mistake and therefore installed into a folder of that name. If you have a kanban-todo-board folder: install 1.1.1 or newer into kanban-level-up as described above, copy data.json from kanban-todo-board into kanban-level-up (if it exists), enable the plugin again under Community plugins, then delete the kanban-todo-board folder. The same applies to any other old copy (e.g. a folder named kanban-levelup-obsidian).
• Switching from manual to BRAT needs no clean-up: BRAT writes into the same kanban-level-up folder and keeps data.json.
• Going back to an older version is safe: older versions simply ignore fields they do not know (such as Eisenhower categories or the duel order).

What's new

1.2.0

• 📅 Deadlines — light yellow the day before, light red on the day and after; optional setting to show due cards first (details)
• Undo / redo with Cmd/Ctrl + Z for everything on a board — including deleted cards and whole columns (details)
• Position numbers on cards in open columns
• Dragging a card no longer resets the scroll position; the moved card stays in view and is briefly highlighted
• Fix: dragging a card down within the same column dropped it one slot too low

1.1.2

• Restores the plugin ID kanban-level-up used by 1.0.0 and by the community directory. 1.1.0 had changed it to kanban-todo-board, which made Obsidian treat it as a separate plugin — see Updating from an older version if you installed 1.1.0
• Requires Obsidian 1.8.7 or newer (the APIs the plugin uses were not available in the previously declared 0.15.0)
• Code clean-up from the community directory's automated review: Obsidian DOM helpers throughout, stricter typing, no builtin-modules build dependency
• Label names containing &, < or > now display correctly in the skill chart

1.1.0

• 🧭 Eisenhower matrix — sort open tasks into urgent/important quadrants; categories are stored per card
• 🥊 Priority duel — order a column by picking the more important of two cards (details)
• 🌐 German translation — choose Automatic, English or Deutsch under Settings → Kanban Todo Board → Language
• Long columns scroll properly, and cards no longer shrink when a column fills up
• Description and author link in the plugin listing updated

Troubleshooting

---

Requirements

Obsidian 1.8.7 or newer (since plugin version 1.1.2). Works on desktop and mobile, though the card action buttons are revealed on hover and are therefore easier to reach with a pointer.

---

📋 Kanban Board

Creating a board

• Click the dashboard ribbon icon or run the command New Kanban Board
• Enter a name — a .kanban file is created in your vault root and opened immediately
• The board appears in your file list like any other note

Columns

• Add a column: Click the + icon at the right edge of the board
• Rename a column: Double-click the column title to open the column settings
• Delete a column: Click the trash icon in the column header
• Mark as Done: In the column settings modal, toggle "Mark as Done column"

⚠️ Important: The "Done" status is set explicitly — it is NOT inferred from the column name. This means you can rename your Done column to anything (e.g. "🎉 Completed", "Shipped", "Archiv") without breaking Skill Chart or All Done Todos tracking.

Cards

• Add a card: Click + Add card at the bottom of any column
• Edit a card: Hover over a card → click the pencil icon
• Delete a card: Hover over a card → click the × icon
• Move a card: Drag and drop, or use the ◀ ▶ arrow buttons. The board keeps its scroll position and briefly highlights the moved card, so you never lose sight of it
• Cards support a title, optional description, one or more labels, an optional Eisenhower category and an optional deadline
• Position number: every card in an open column shows its position (1 = top = most important). Done columns show none

Undo and redo

Every change on a board can be taken back: deleted cards and columns, moves, edits, a duel result, even changes made from the Eisenhower matrix.

On macOS Ctrl + Z works as well. The board must be the active tab. Deleting a card or column shows a short notice with the shortcut, and Skill Chart points are restored together with the cards. The history keeps the last 50 changes per open board and starts fresh when the board is reopened or the file changes on disk (for example through sync). Both actions are also available in the command palette (Undo last board change, Redo board change), so you can assign your own hotkeys under Settings → Hotkeys.

Deadlines

Give a card a deadline in the card dialog (date picker; the × clears it). The card then shows a small calendar chip and changes colour as the day approaches:

Cards in a Done column never change colour. The colours follow your computer's calendar day and update on their own when the date changes, even if Obsidian stays open.

By default deadlines do not affect the order of a column. Turn on Settings → Kanban Todo Board → Show due cards first to show red cards (due today or overdue) at the top of their column. This only changes the display: the saved order stays as it is, so the card returns to its place once it is done or the deadline moves. Deadlines also appear in the Eisenhower matrix and in the priority duel.

Auto-archive

Cards in Done columns that are older than 7 days are automatically hidden from the board view. They continue to count in the Skill Chart and appear on the All Done Todos page. A small note in the Done column shows how many items are archived.

---

🧭 Eisenhower Matrix

Open via the ribbon (grid icon) or command Open eisenhower matrix.

What it shows

A 2×2 matrix of the currently active board — the board you last opened. Axes are urgent / not urgent (columns) and important / not important (rows):

• Only open cards appear. Cards in a Done column are excluded — those belong to All Done Todos and the Skill Chart.
• Cards without a category collect in a "Not categorised" tray below the matrix.
• The board name is shown in a dropdown at the top; switching it also changes which board the matrix follows.

Assigning a category

• Drag & drop: drag a card into any quadrant, or back into the tray to clear its category
• Card dialog: pick a category under "Eisenhower category" when creating or editing a card (on the board or in the matrix)
• The category shows as a colored chip on the Kanban card

Working with cards

Cards show only their title, source column and labels. If a card has a description, a chevron appears to the left of the title — click anywhere on the card to expand it. Expanded cards stay expanded while the view is open.

Hovering a card reveals two buttons:

• ✓ Mark as done — moves the card into the board's Done column, exactly as dragging it there would: it gets a completion timestamp, raises the Skill Chart for each of its labels, and appears in All Done Todos. If the board has no column marked as Done, a notice says so and nothing is moved.
• ✎ Edit — opens the same card dialog as on the board

Changes are written straight into the board's .kanban file. If the board is open in a Kanban view, the change is routed through that view so both stay in sync.

---

🥊 Priority duel

Order a column by deciding between two cards at a time instead of dragging cards around.

Click the swords icon in a column header (not available in Done columns or with fewer than two cards). Two cards appear side by side — pick the one that should come first:

Not sure what a part of the dialog means? Click the small ? next to its heading to expand an explanation.

How the next pair is chosen

Each card gets a priority score (Bradley–Terry model). The current column order counts as a starting point, so with zero duels nothing changes and every duel only moves cards where you disagree with the existing order. The next pair is always the one whose outcome is expected to reveal the most about the order (information gain in bits).

Cards added to the column since the last applied duel start without that head start: they are placed in the middle with wide uncertainty, so the first duels go to finding their spot instead of making them climb up from the bottom one neighbour at a time.

When to stop

• The "Order settled" meter fills once every card has been in a duel, new cards have had enough duels to find their spot, and the top of the list has kept its order for several duels in a row.
• The information chart shows the expected gain per duel and how many ranks each duel moved — when both flatten out, more duels are not worth it.
• The current order panel shows each card's score, its uncertainty and how far it moved compared to the column.

As a guide: a column that was already roughly in order usually settles after about half of n·log₂n duels (≈ 15 for 10 cards, ≈ 45–75 for 20). Columns of 30+ cards get tedious — consider duelling only the part you will work on soon.

Nothing is written until you apply

The review screen shows the new order with ↑/↓ changes. Apply writes it into the column; Discard drops the duels. Closing the dialog with Esc keeps your duels in memory until Obsidian restarts, so reopening the same column resumes where you left off.

Applying also stores the resulting order in the column (rankedIds in the .kanban file). That is how the next duel recognises which cards are new.

---

✅ All Done Todos

Open via the ribbon (checkmark icon) or command Open All Done Todos.

• Aggregates all completed cards from all .kanban files in your vault
• Shows the completion date and time for each card
• Grouped by day, sorted newest first
• Displays the board name each card belongs to
• Shows assigned labels

Cards are tracked here regardless of whether they are still visible on the Kanban board or have been auto-archived.

---

📡 Skill Chart

Open via the ribbon (activity icon) or command Open Skill Chart.

How it works

Every time a card is moved into a Done column, the Skill Chart increments by 1 for each label on that card. Moving the card back out decrements it. The chart grows over time as you complete labeled work.

Radar chart

• One axis per label defined in settings
• The shape shows the distribution of your completed work across label types
• Long label names wrap automatically and are never clipped

Comparison / history

The plugin takes automatic snapshots of your scores (at most once per 20 hours). You can compare your current chart against any past point:

• Quick presets: 1W, 2W, 1M, 3M, 6M — sets the comparison range to that many days ago
• Custom date range: Set a "From" and "To" date manually using the date pickers
• Toggle: Disable comparison entirely with the toggle switch
• The dashed polygon on the chart shows your skills at the start of the selected period
• The stats grid shows the delta (e.g. +3) per label

---

🏷 Labels

Manage labels in Settings → Kanban Todo Board → Labels:

• Add labels with + Add label
• Rename labels inline — changes reflect immediately on all open boards
• Change color using the color picker — the label preview updates live
• Delete labels (note: cards retain the label ID, so re-adding a label with the same name won't reconnect them)

Labels assigned to a card are shown as color-coded chips on the card. They drive the Skill Chart axes.

---

⚙️ Settings

Eisenhower categories are stored per card inside the .kanban file, not in the plugin settings. Existing boards keep working — cards without a category simply start in the "Not categorised" tray.

---

📁 File structure

kanban-levelup-obsidian/
├── main.ts                 # Plugin logic: board, views, modals, settings (TypeScript source)
├── duel-ranker.ts          # Priority duel: ranking model and pair selection (no Obsidian imports, testable in Node)
├── duel-modal.ts           # Priority duel: the duel / review dialog
├── i18n.ts                 # All UI texts in English and German; add a language by adding a dictionary
├── deadline.ts             # Deadline logic: due states, colours, chip, "due cards first" ordering
├── main.js                 # Bundled output — this is what Obsidian loads
├── styles.css              # Styles (uses Obsidian CSS variables — adapts to any theme)
├── manifest.json           # Plugin metadata
├── versions.json           # Plugin version → minimum Obsidian version
├── esbuild.config.mjs      # Build config
├── version-bump.mjs        # Keeps manifest/versions in step with `npm version`
├── scripts/seed-board.mjs  # Development helper: generates a board full of test data
└── .github/workflows/release.yml  # Builds and publishes a release on tag push

Board data is stored in .kanban files in your vault (plain JSON).
Label definitions and Skill Chart scores are stored in .obsidian/plugins/kanban-level-up/data.json.

---

💻 Development

Requires Node.js 16 or newer.

git clone https://github.com/jakobeilts/kanban-levelup-obsidian.git
cd kanban-levelup-obsidian
npm install

npm run dev     # Watch mode — rebuilds on file changes
npm run build   # Type-check with tsc, then bundle with esbuild

To try a build in Obsidian, copy main.js, manifest.json and styles.css into <YourVault>/.obsidian/plugins/kanban-level-up/ and reload the app. Developing directly inside a vault's plugin folder works too — npm run dev then rebuilds in place.

Test data

scripts/seed-board.mjs writes a .kanban file full of generated cards into a vault, so the board and the Eisenhower matrix can be checked with realistic amounts of content. It is a development helper only — it is not bundled into main.js and never reaches users.

npm run seed -- --vault ~/Documents/Obsidian/Vaults/<YourVault>
npm run seed -- --vault <path> --cards 200 --name "Stress test" --force
npm run seed -- --vault <path> --sparse   # leaves two quadrants empty

The generated board covers all four quadrants, uncategorised cards, a Done column with completion dates spread over 14 days (so both visible and auto-archived cards appear), and a handful of layout edge cases: an overlong title with an unbreakable word, a card carrying every label, one with neither label nor description, and emoji/special characters.

Two caveats:

• Labels are read from the plugin's data.json. If the plugin has never been enabled in that vault, the file does not exist yet and cards are generated without labels — enable the plugin once, then re-run.
• Skill chart scores are event-driven: they are written when a card is moved into a Done column at runtime. Seeded Done cards therefore appear in All Done Todos but do not raise the chart.

---

🚀 Releasing

Releases are built and published by .github/workflows/release.yml when a version tag is pushed. Obsidian looks for a tag that matches manifest.json exactly, so tags carry no v prefix.

npm version minor        # bumps package.json, manifest.json and versions.json, commits, tags
git push && git push --tags

npm version runs version-bump.mjs, which writes the new version into manifest.json and adds a versions.json entry mapping it to the current minAppVersion. The workflow then type-checks, builds, verifies that the tag and the manifest agree, and attaches main.js, manifest.json and styles.css to the release as individual files — which is the layout Obsidian's installer expects.

---

🤝 Contributing

Bug reports and feature requests are welcome in the issue tracker. For pull requests, please run npm run build first — it type-checks as well as bundles — and describe what you changed and how you tested it.

---

📄 License

MIT © Jakob Eilts