How to manage tasks in plain markdown

A task in plain markdown is a list item with a bracket pair in front of it. Write - [ ] Book the venue for something outstanding and - [x] Book the venue for something done. That syntax comes from GitHub Flavored Markdown. Every major code host and most notes apps understand it, so a checklist you write in one tool opens as a checklist in the next.

The part that takes thought is the filing, not the syntax. Keep each task in the note where its context lives, the project note or today’s daily note, rather than one giant file. Then use search to pull every open item together when you want one list.

The checkbox syntax in full

The bullet marker can be a hyphen, an asterisk, or a plus sign, and numbered list items work too. The space inside the brackets is what marks a task as open.

What you type	What it means
- [ ] Draft the invoice	An open task
- [x] Draft the invoice	A completed task
- [X] Draft the invoice	Also completed, capital X is equally valid
- Draft the invoice	A plain bullet, not a task

Indent a task to nest it under its parent. Two spaces is enough in most renderers, and a few older ones want four, so use four if the nesting does not appear. Few tools tick the parent for you when every child is done, so tick both yourself.

- [ ] Ship the March newsletter
  - [x] Write the draft
  - [ ] Get sign-off from Priya
  - [ ] Schedule the send

Keep each task to one line. Wrapped text still renders, but it breaks most search patterns.

Where to keep a todo in markdown

The simplest way to keep a todo in markdown is one todo.md file. It is a fine starting point, but it separates the task from everything you know about it. Six weeks in you get lines like “chase the thing from Tuesday” and no way to remember what the thing was.

The second pattern is one checklist per project note. The task sits under the decisions and links that explain it, which is where you want it when you pick the work up. The cost is that your open work is scattered across dozens of files, so you need search to see it all.

The third is capture in daily notes and promote later. Tasks go into today’s note as they occur to you, and the survivors move into the relevant project note. The second and third work well together, and there is more on that in daily notes in plain markdown.

Adding the details you need

Plain text has no fields, so any extra detail is a convention you invent and then keep. Put a due date at the end of the line as YYYY-MM-DD, which sorts correctly as text and is unambiguous internationally. Mark context with a tag like #waiting or #office. Name the person you are waiting on in full, not in initials you will not decode in six months.

- [ ] Send revised quote to Bramley #waiting @due(2026-09-14)
- [ ] Replace the office door lock #office

The @due(...) wrapper is the spelling Jotura’s task list reads, which is why it appears here. A bare due 2026-09-14 is equally good plain text that any search finds, it just will not drive a date-aware task view. Resist a richer schema than this: a convention you follow half the time is worse than none.

Finding every open task across a folder

This is where markdown tasks either work or quietly fail. If you cannot see all your open items in one place, you will stop trusting the system.

Because tasks are lines of text, any search tool finds them. Ripgrep is a fast command-line search tool you install separately, and one pattern lists every open task in a folder and below.

rg -n --glob "*.md" "^\s*[-*+] \[ \] " .

The [-*+] character class catches asterisk and plus bullets as well as hyphens, and the glob keeps the search to markdown files. Change the pattern to see finished work, or to narrow by tag.

rg -n --glob "*.md" "^\s*[-*+] \[[xX]\] " .
rg -n --glob "*.md" "^\s*[-*+] \[ \] .*#waiting" .

Dates work the same way. A YYYY-MM-DD date starts with year then month, so 2026-09 is a prefix that matches every day in September.

rg -n --glob "*.md" "^\s*[-*+] \[ \] .*@due\(2026-09" .

If you do not have ripgrep, grep is already on macOS and Linux, and PowerShell covers Windows.

grep -rEn --include="*.md" "^[[:space:]]*[-*+] \[ \] " .

Get-ChildItem -Recurse -Filter *.md | Select-String -Pattern '^\s*[-*+] \[ \] '

That is enough for a lot of people, and it costs nothing. What it does not give you is a live view you can tick items off from.

Where checklists are already clickable

Plenty of tools turn those brackets into a checkbox you can click. GitHub and GitLab do it in issues, pull requests, and rendered .md files, and VS Code does it with an extension. Most notes apps that open a folder of markdown do the same, Obsidian and Logseq among them.

On this topic specifically, Obsidian is the strongest option. Its Tasks and Dataview community plugins add recurring tasks, due-date queries, and live filtered task views, none of which plain markdown or Jotura can do. Jotura has no plugin system at all. If plugin-driven task queries are what you want, use Obsidian.

A built-in task view without leaving markdown

Jotura is a free notes app that opens a vault, meaning an ordinary folder of .md files on your disk. It reads checklist markdown across that folder into one task list, and ticking an item writes the x back into the file it came from.

That list is a rolling window, not everything you have ever written. A task appears if its file was modified recently, if it sits in a dated daily note inside the window, or if it carries a future @due(...) date. The window defaults to 30 days and is a setting. An undated task in a file you have not opened for months stays hidden until you open it or date it, so keep the search patterns above for the exhaustive sweep.

Task state is never held anywhere but the file. Jotura keeps a search index in a .jotura folder for speed, but that index is derived: delete it and your tasks are untouched. Saving a file you did not edit produces a byte-identical file, so nothing rewrites your checkboxes into a house style.

It is closed source, it has no plugin system, and there is no iOS app, so an iPhone capture habit is not something it can serve.

Ticking a task from a script or an agent

A checkbox is one character, so any script can flip it. On Linux, sed does it in a line, and on macOS the same command needs sed -i ''.

sed -i 's/- \[ \] Schedule the send/- [x] Schedule the send/' Projects/newsletter.md

That works, and it has two problems. It rewrites every matching line, and it will happily overwrite a change someone made a second earlier.

The jotura command-line tool ships with the app and closes both gaps. Read the file first, then write against the hash you read, using jq to pull the hash out of the JSON.

HASH=$(jotura read Projects/newsletter.md --json | jq -r .hash)
jotura edit Projects/newsletter.md \
  --replace "- [ ] Schedule the send" \
  --with "- [x] Schedule the send" \
  --if-hash "$HASH"

--replace requires a unique match and exits with code 4 if the string appears more than once. If the file changed since your read, the command exits with code 2 instead of overwriting. When the text is not unique, edit by position instead.

jotura edit Projects/newsletter.md --replace-line 12 --with "- [x] Schedule the send"

An out-of-range line number exits with code 5. The full command list is in the jotura CLI reference.

What plain markdown tasks cannot do

There are no reminders. A text file cannot interrupt you, so a deadline that needs to buzz your phone belongs in a calendar, with the note linking to it.

There is no recurrence. A weekly task has to be recreated, by hand or by a script you run yourself.

There is no shared state for a team. Two people editing one checklist over a file sync can both tick different lines, and how that resolves depends on the sync tool. Jotura’s paid Sync can share a folder or a single note, with editor and viewer roles, and merges concurrent edits automatically. Both people need their own subscription at £4 per month or £40 per year, so a two-person checklist is two subscriptions, and there is no free trial.

Obsidian Sync is $4 to $8 per month on annual billing, so the two are near parity on price. Pick on features, not cost, and weigh the plugin point above.

Finally, there is no reporting layer. You will not get burndown charts, story points, or dependency graphs out of a folder of text. That is the trade: you give up structured project management and you get files that outlive any app.

Archiving what you finish

Completed tasks pile up and make a note harder to read. Move them to the bottom under a ## Done heading, or cut them into an archive note per quarter such as Archive/2026-Q3.md. In the second case, add a wikilink back to the project note so the trail survives. See wikilinks and backlinks in plain markdown for how that works.

Delete nothing that explains a decision. A ticked task with a date is often the only record of when something happened.

Frequently asked questions

Does the checkbox syntax work everywhere? It works in GitHub, GitLab, most static site generators, and most notes apps. It is not in the original Markdown specification or in CommonMark: it is a GitHub Flavored Markdown extension. A strict CommonMark renderer shows the brackets as literal text, and the file is still readable.

Should I use a task manager instead? If your work runs on deadlines, assignments, and notifications, use a real task manager and keep your notes separate. Markdown tasks suit people whose tasks are mostly a byproduct of thinking and writing.

How do I stop the list growing forever? Review it on a fixed schedule and delete without ceremony. Any task you have carried for three months is not a task. It is a wish, and removing it makes the remaining list trustworthy again.