---
title: "Markdown Task Management: One List From Every Checkbox"
description: "Markdown task management done right: aggregate every - [ ] checkbox scattered across your notes into one filterable task list — no separate database, no export."
author: "MDflow"
date: 2026-07-14
reading_time: "11 min"
canonical_url: https://mdflow.cz/blog/markdown-task-management
md_url: https://mdflow.cz/blog/markdown-task-management.md
---

# Markdown Task Management: One List From Every Checkbox

*Published July 14, 2026 · 11 min read*


If you write in markdown, you already track tasks in markdown — probably without deciding to. A `- [ ]` here in your meeting notes, a `- [x]` there in a project doc, a checklist buried three folders deep in a spec you wrote last month. The syntax is effortless. The problem shows up later: those checkboxes are **scattered across dozens of files**, and there is no single place that answers "what do I actually have to do?"

The usual fix is to give up and move your tasks into a dedicated app — Todoist, Things, a Notion database. But that means your tasks now live somewhere *other* than the notes they came from, and you spend your day copying between the two. This post is about the other fix: **keep the checkboxes exactly where they are, in plain markdown, and let one view aggregate them for you.** We make [MDflow](/), which does exactly this, so treat this as a walkthrough of how the pattern works — and an honest account of where it fits.

> **TL;DR** — **Markdown task management** means tracking to-dos as ordinary `- [ ]` / `- [x]` checkboxes inside your notes. The hard part is that they scatter across many files. The solution is a view that **aggregates every checkbox across your workspace into one filterable list** — without a separate database, because the document body *is* the source of truth. [MDflow](/)'s [Tasks view](/markdown-tasks) does this: filter by status, due date, and owner, edit inline, and let AI agents add tasks over [MCP](/docs/mcp) or the [API](/docs/api). Available on every plan.

## What is markdown task management?

**Markdown task management is tracking your to-dos as checkbox lines inside ordinary markdown documents, rather than in a separate task application.** The syntax comes from GitHub Flavored Markdown (GFM), which added *task list items* — a list item whose marker is a bracket pair:

```markdown
- [ ] Draft the Q3 proposal
- [x] Send the signed contract
- [ ] Review the API design doc
```

An unchecked `- [ ]` is an open task; a checked `- [x]` is done. In any GFM-aware renderer — GitHub, VS Code, Obsidian, MDflow — these show as real, sometimes clickable, checkboxes. The appeal is obvious: there is no form to fill in, no "new task" modal, no context switch. You are writing a meeting note and a to-do falls out of the sentence, so you type `- [ ]` and keep going.

The weakness is equally obvious. Because tasks are just lines in whatever document you happened to be writing, they end up **everywhere and nowhere**. A checkbox in `sprint-notes.md`, another in `clients/acme/kickoff.md`, three more in a personal `ideas.md`. Individually they are fine. Collectively they are invisible — there is no page you can open that says "here is everything that is still `- [ ]`." Aggregation is the missing half of markdown task management, and it is the half this post is about.

## Why aggregated markdown tasks are useful

The value of aggregating markdown checkboxes is that you get the **capture speed of plain text and the overview of a real task manager at the same time** — without choosing one or the other. Split it by who benefits.

### For developers and knowledge workers

If you already live in markdown — engineers with `README`s and design docs, writers with drafts, anyone running a plain-text [second brain](/blog/best-second-brain-app) — an aggregated task view removes the last reason you kept a separate to-do app. You capture tasks inline, at the speed of typing, right next to the context that produced them. Then one view rolls them up so nothing is lost. This is the practical heart of **GTD in markdown**: the checkbox is your *capture*, and the aggregated, filterable list is your *engage* — the trusted place you review to decide what is next. Because the tasks never leave your documents, the context is always one click away: the task and the note that spawned it are the same file.

### For AI agents

Aggregated markdown tasks are a natural interface for AI agents precisely because a task is *just text*. An agent doesn't need a bespoke task API with its own schema — it writes a line to a document and a task exists. An agentic coding assistant can append `- [ ] (20260715) Add rate-limit tests` to a project doc as it works; a meeting-notes agent can extract action items into checkboxes; a research agent can leave follow-ups behind. Every one of those shows up in the same human-readable list you review. The task list becomes a **shared surface between you and your agents**, and because it is plain markdown, both sides read and write it the same way. (This is the write-back pattern we cover in [Let AI agents write to your knowledge base](/blog/ai-agents-write-to-knowledge-base).)

## Which applications benefit most

Aggregated markdown tasks fit best where tasks are *born inside documents* rather than entered into a dedicated queue. The clearest cases:

1. **Project and sprint notes.** Action items fall out of standups, retros, and planning docs as checkboxes; the aggregated view is your live backlog without re-entry.
2. **Client and consulting work.** Each client folder accumulates its own to-dos inline; filter the one list by owner or due date to run the whole book of business.
3. **Personal GTD and PKM.** If your notes *are* your system, your tasks should live there too — capture in context, review in aggregate.
4. **Spec-driven and agentic development.** Specs and plans carry their own checklists; agents tick them off and add new ones, and you watch progress in one place.
5. **Meeting and research notes.** Decisions and follow-ups get captured as `- [ ]` in the moment, then surface as tasks you can actually act on.

The common thread: these are all workflows where forcing tasks into a separate database would mean *duplicating* the note, and the duplication is exactly what rots.

## How MDflow fits

[MDflow](/) is a markdown workspace in the browser, and it treats task aggregation as a first-class feature built on one principle: **the checkbox in your document is the only copy of the task there ever is.**

What lines up today:

- **The Tasks view aggregates every checkbox in the workspace.** A dedicated [`/tasks`](/markdown-tasks) view scans every markdown document in your active workspace and collects each `- [ ]` and `- [x]` into one Asana-style list — grouped by folder and document, with indented subtasks nesting under their parent. You did not move or tag anything; MDflow just gathers what was already there.
- **No separate database — the document body is the source of truth.** Tasks are not a separate entity. They stay as checkbox lines inside document bodies. When you toggle, rename, reschedule, or reassign a task in the Tasks view, MDflow **rewrites that source line and saves the document.** There is nothing to keep in sync, so tasks can never drift from your notes.
- **Optional due dates and owners, still in plain markdown.** Add two parenthetical groups right after the checkbox — a due date as `(YYYYMMDD)` and an owner as `(email)`, in either order: `- [ ] (20260715)(jan@example.com) Send the invoice`. A task with no owner is yours. It is ordinary markdown text, so it travels with the file to any other tool.
- **Filter, search, and edit inline.** Filter by status (all, outstanding, completed), by due date (due/overdue, today, this week, next week), and by owner — each group showing a live count — plus a text search over descriptions. Edit in place: toggle done, rename, set or clear a due date from a picker, set or clear the owner. Overdue dates show red, today amber.
- **Capture from anywhere — including agents.** Create tasks inline under any document, or with a top-level quick-add that writes to a `Tasks` document in the active workspace. And because a task is just a line in a body, **anything that can write a document body can create a task** — including scripts and AI agents over the [HTTP API](/docs/api) or the [MCP server](/docs/mcp). An agent that appends a checkbox to a document adds a task that appears in your list right away.
- **Encrypted documents are respected.** [Client-side-encrypted](/blog/client-side-encryption-for-online-notes) documents are counted and skipped — never scanned — and all parsing happens in your browser against plaintext bodies, so the server never reads content to build the list.

An honest boundary: MDflow's Tasks view is **scoped to the active workspace**, and it aggregates checkboxes — it is not trying to be a full project manager with dependencies, Gantt charts, or automations. It also isn't Pro-gated: it is available to every signed-in user on any plan. The point is a faithful, filterable rollup of the markdown tasks you are already writing, not a new silo.

Where we are headed is **direction, not a dated commitment**: richer cross-workspace and saved-filter views, and deeper agent workflows around task creation and completion. The throughline stays fixed — your tasks remain plain markdown checkboxes inside your own documents, so they are never trapped in a task database you can't export.

## The bottom line

Markdown task management works because the checkbox is the fastest possible way to capture a to-do: you are already typing, and `- [ ]` costs nothing. What breaks it is scatter — dozens of checkboxes across dozens of files with no overview. The fix is not to abandon markdown for a task app; it is to **aggregate the checkboxes you already have** into one filterable list, while leaving them exactly where they were written.

That is the whole idea: the document body stays the single source of truth, and the task list is just a live view over it. No duplication, no export, no sync — and because it is plain markdown, your agents can capture tasks the same way you do.

If your notes already live in MDflow, every checkbox across your workspace is already in one place.

[Start free](/login) · [Connect an AI agent](/docs/mcp) · [Read the API docs](/docs/api)

## Frequently asked questions

### What is markdown task management?

Markdown task management means tracking to-dos as ordinary markdown checkboxes — lines like `- [ ] Draft the proposal` for open tasks and `- [x] Send invoice` for done ones — inside your regular notes, instead of in a separate task app. The checkbox syntax is part of GitHub Flavored Markdown, so it renders as a real checkbox in most markdown tools. The catch is that these checkboxes end up scattered across many files, which is why an aggregated view that collects them into one list matters.

### How do I aggregate markdown tasks scattered across many files?

You need a tool that scans every document and collects each `- [ ]` and `- [x]` line into one place. In MDflow, the built-in Tasks view does this automatically for the active workspace: every checkbox across all your markdown documents appears in one filterable list, grouped by folder and document, without you moving or copying anything. The checkbox lines stay in their original documents as the single source of truth.

### Can I manage markdown tasks without a database?

Yes. Because a markdown task is just a text line inside a document, there is no separate task table to keep in sync — the document body is the database. MDflow parses the checkboxes out of your plain markdown to build the Tasks view, and editing a task in that view rewrites the source line and saves the document. Nothing is duplicated, so your tasks can never drift out of sync with your notes.

### How do due dates and owners work in markdown tasks?

In MDflow you add an optional due date and owner with two parenthetical groups right after the checkbox: a due date as `(YYYYMMDD)` and an owner as `(email)`, in either order — for example `- [ ] (20260715)(jan@example.com) Send the invoice`. The Tasks view reads those and lets you filter by due date and owner and edit them inline. A task with no owner is yours. It is still plain markdown, so it travels with the file.

### Can an AI agent create markdown tasks for me?

Yes. Because a task is just a line in a document body, anything that can write a document body can create a task — including AI agents connected over MDflow's MCP server or HTTP API. An agent that appends `- [ ] (20260716) Follow up with the client` to a document creates a task that appears in your Tasks view immediately, scoped to that workspace.

## Further reading

- GitHub — [About task lists (GFM spec)](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists)
- Tiago Forte — [Getting Things Done and the second brain](https://fortelabs.com/blog/basboverview/)
- MDflow — [Markdown Task Manager](/markdown-tasks) · [Let AI agents write to your knowledge base](/blog/ai-agents-write-to-knowledge-base) · [The best second brain app](/blog/best-second-brain-app) · [API documentation](/docs/api)