Markdown Kanban Board: Build One in a Single .md File

A markdown kanban board is a single plain-text file where headings are the columns and checkbox lines are the cards. Backlog, Doing, Done, a WIP limit written into the Doing heading, and card moves by cut and paste: that is the entire system. It takes ten minutes to set up and runs in any markdown editor. Here is the board, then the reasoning.

# Side project board

## Backlog
- [ ] Dark mode for the settings page
- [ ] Export to CSV
- [ ] Write the 2.5 changelog

## Doing (WIP limit: 3)
- [ ] Fix the sync retry bug
  - [ ] Reproduce on a fresh account
- [ ] Draft the launch post outline

## Done
- [x] Landing page headline test
- [x] Password reset flow

That file is a working kanban board. It renders as three sections with checkboxes in Obsidian, VS Code, Typora, Bear, and GitHub's preview. The broader case for running tasks this way is our guide to markdown task management; this page is the build.

Can you really run a kanban board in one markdown file?

Yes, and for solo projects it works better than expected, because kanban's core constraint is not a UI feature. The method, as defined by David Anderson's Kanban book and popularized by tools like Trello, is three ideas: visualize the work, limit work in progress, and make flow visible. Headings, checkbox lines, and a number in the Doing heading express all three.

What the file gives you that a board app does not:

• Diffs. git diff on the board shows exactly what moved this week, which is a standup report you did not have to write.
• Portability. The board opens in any editor on any OS, no account, no export flow. This is the same argument behind plain text kanban workflows generally.
• One text file as API. Any script can read the board. A two-line grep counts open cards; a small script can archive Done automatically.

What the file does not give you: drag and drop, per-card comments, attachments, and notifications. Hold that thought until the graduation section, because for one person those features are often cargo, not cargo capacity.

How do I set up the markdown kanban board?

Set up the board in five steps, about ten minutes total: create the file, write the column headings, add cards as checkboxes, set the WIP limit, and commit the file to Git.

Three setup decisions matter more than the rest.

Columns stay at three. Backlog, Doing, Done covers most personal work. The most common useful addition is a Waiting column for blocked items; add it only when a card has actually stalled on someone else twice. Every column beyond three is a new place for cards to hide.

Cards stay one line. A card is a verb-first sentence. If a card needs detail, the detail goes in indented sub-items or in a separate note linked from the card text, not in a paragraph inside the board file. Long card text is how the board file becomes unscrollable.

The file lives with the project. Put board.md at the root of the project folder or repo, not in a generic notes directory. The board that lives next to the work gets updated; the board three folders away becomes archaeology.

How do WIP limits work in plain text?

A WIP limit in plain text is an honor-system number written into the column heading. Nothing stops you from adding a fourth card to a Doing column capped at three. That sounds like a weakness, and for teams it is; for a solo board it is mostly fine, because the person violating the limit and the person harmed by it are the same person, looking at the same file.

Two conventions make the limit stick:

1. Write the limit in the heading text where it is always visible: ## Doing (WIP limit: 3), not in a comment at the bottom of the file.
2. Count during the daily glance. Opening the file takes two seconds; a Doing column with four cards under a "limit: 3" heading is visually wrong in a way that nags.

If you want enforcement, Obsidian's Kanban plugin renders a real drag-and-drop board from a markdown file and warns on WIP overflow, as of 2026 it is the closest thing to a board app that still saves plain markdown underneath. The file it writes stays portable.

What do I lose versus Trello or Linear?

As of 2026, the losses fall into four buckets, and being honest about them is cheaper than discovering them mid-project. Feature sets shift quickly, so treat this as a snapshot rather than a permanent scoreboard.

Markdown kanban vs board software: the tradeoffs

Capability	Markdown file	Board software
Moving cards	Cut and paste	Drag and drop
WIP enforcement	Convention in heading	Enforced or warned natively
Assignments, mentions	Name in card text	Native, with notifications
Due dates, reminders	Date in text, no alerts	Native automation
Audit trail	Full Git history	Activity log, varies
Longevity	Decades, any editor	Tied to vendor
Realtime multi-editor	Merge conflicts	Native

The pattern in the table: markdown wins on ownership and time, software wins on coordination and alerts. One person's side project lives almost entirely in the first category. A five-person launch team lives in the second.

When should I graduate to a real board tool?

Graduate when one of three signals shows up, not before: more than three people editing concurrently, work that depends on notifications to move, or a Doing column that has stopped being scannable at a glance.

The signals, unpacked:

• Concurrent editors. Two people with Git habits can share a board file. Past three, merge conflicts on the same lines become a weekly chore, and the file has failed at its one job, which is being boring.
• Notification-dependent work. If the workflow is "assign card, person gets pinged, card moves," plain text is the wrong substrate. Nothing in a .md file will ever ping anyone.
• Unscannable board. When the backlog passes roughly 50 cards or Doing regularly exceeds five, the file stops answering "what is the state of the project?" in one glance. Real tools add filtering and swimlanes precisely for this stage.

The graduation path keeps the file: export nothing, just start the new board in the tool and keep the markdown file as the archive. Portability was the point from the start. And if what you actually miss is capture speed rather than board features, that is a different fix: quik.md captures tasks by voice, files them into projects with AI, and exports plain markdown, so the board file and the task list stay in the same format. quik is a PWA, the free plan covers a daily AI-organize cap with browser speech recognition, and Pro is $14.99 monthly or $69.99 yearly with a 7-day trial, or $99.99 once for lifetime. The pillar on AI task managers maps where board tools, capture tools, and markdown files each fit.

Pricing shown reflects plans at the time of writing. Check quik.md/pricing for current rates.

FAQ

Can you make a kanban board in markdown?

Yes. Use headings as columns (Backlog, Doing, Done) and markdown checkbox lines as cards underneath each heading. Moving a card is cut and paste between sections. The board renders in Obsidian, VS Code, Typora, and GitHub, and the file's Git history doubles as a full log of every card move.

How do WIP limits work in a markdown kanban board?

A WIP limit in markdown is a convention, not an enforced rule: write the cap next to the column heading, like '## Doing (WIP limit: 3)', and hold yourself to it. Plain text cannot block a fourth card the way Trello or Linear can, so the limit works through the daily glance at the file, not through software.

What do I lose vs Trello or Linear?

As of 2026, the main losses are drag and drop, card assignments and notifications, due-date automation, attachments, and real-time collaboration on the same board. What you gain is a file that opens in any editor, syncs through Git, diffs line by line, and will still be readable when the current generation of board tools is gone.

When should I switch from markdown kanban to a real tool?

Switch when any of three signals appears: more than three people need to edit the board concurrently, you keep missing deadlines because nothing notifies you, or the Doing column regularly exceeds five cards and finding anything takes scrolling. Solo projects and two-person teams with Git habits usually never hit these limits.

How many columns should a markdown kanban board have?

Three columns (Backlog, Doing, Done) cover most personal workflows. Add a fourth only when a real constraint appears: a Waiting column for blocked items is the most common useful addition. Each extra column is one more place cards can stall unnoticed, so grow the board only when the three-column version demonstrably fails you.

What should you read next?

• Markdown task management, the strategic case for plain-text task systems.
• Markdown todo list templates, daily, GTD, weekly, and meeting files to pair with the board.
• Plain text productivity, why the format outlives every app built on top of it.
• AI task manager, where AI capture and routing fit next to a markdown board.

References

• Kanban: Successful Evolutionary Change for Your Technology Business, David J. Anderson.
• Obsidian Kanban plugin, mgmeyers.
• GitHub Flavored Markdown spec, GitHub.
• Getting Things Done, David Allen Company.