How to Create a Checkbox List (To-Do List) in Markdown

A to-do list is one of the first things most people want to build when they start writing in Markdown, and for good reason: plain text is the perfect medium for capturing tasks quickly. The good news is that GitHub Flavored Markdown (GFM) ships with a dedicated task list extension that renders checkbox items as real, interactive boxes on platforms that support it. This guide explains the syntax for a markdown checkbox list, how to nest items, how checked and unchecked boxes differ, and which tools render them best.

What Is a Markdown Checkbox List?

A markdown checkbox list (also called a task list or to-do list) is an extension to standard Markdown that turns ordinary list items into items with a clickable checkbox. The feature was popularized by GitHub, which added the task list extension to its GFM spec so that issues, pull requests, comments, and README.md files could show actionable items that contributors could tick off.

The task list extension is not part of John Gruber's original Markdown. It comes from GitHub Flavored Markdown, so it works on GitHub, GitLab, Obsidian, and most modern editors — but it may render as a plain bulleted list in very basic or legacy Markdown parsers.

A rendered checkbox list looks like this in most viewers:

• Confirm the bug reproduces
• Write a failing test
• Open a pull request
• Ask for review

Each box is plain text under the hood, which means your to-do list stays portable, diff-friendly, and searchable no matter where you open it.

Markdown Task List Syntax for To-Do Lists

The markdown task list syntax for to-do lists is intentionally tiny. You start a list item with a hyphen (-) or a plus (+) or an asterisk (*), then place square brackets with a space or an x inside, followed by the task text.

- [ ] Draft the outline
- [ ] Write the introduction
- [x] Pick a title
- [x] Schedule the publish date

The rules that matter:

A few common mistakes to avoid:

• There must be a single space between the hyphen and the opening bracket: - [ ], not -[ ].
• There must be a single space inside empty brackets: [ ], not []. An empty [] will not render as a checkbox.
• The x is case-insensitive, but lowercase x is the convention most people expect.

Here is a slightly larger example you can paste into any GFM-aware editor:

## Sprint 24 tasks

- [x] Migrate the legacy endpoint
- [x] Update the API documentation
- [ ] Deploy to staging
- [ ] Run the smoke test suite
- [ ] Tag the release

Create Nested Checkbox Lists in Markdown

When a single task hides several sub-steps, you can create nested checkbox lists in markdown by indenting the child items by two or four spaces (match whatever your document already uses; two spaces is the most common on GitHub).

- [ ] Launch the landing page
  - [x] Write the hero copy
  - [x] Pick brand colors
  - [ ] Optimize images
  - [ ] Add analytics
- [ ] Set up email forwarding

Indentation is load-bearing here. If the child items are not indented consistently, the parser will treat them as a separate list and your nesting will collapse. The table below shows what happens with different indents:

Nesting is not limited to two levels. Three or four levels work, although once you go that deep it is usually a sign that the task deserves its own document.

Check and Uncheck Boxes in a Markdown To-Do List

Toggling a box means flipping the character inside the brackets. Replacing [ ] with [x] marks the task done; reversing it marks it incomplete. On platforms with a rendered view (GitHub, GitLab, Obsidian, most modern Markdown editors), you can simply click the box and the underlying text is rewritten for you.

Before:
- [ ] Review the pull request

After:
- [x] Review the pull request

If you keep your to-do list inside a git-tracked file, every toggle becomes a line in the diff, which makes progress easy to track over time.

Old trick: some people used to fake checkboxes with the Unicode characters ☐ and ☑. That still works as plain text, but you lose the click-to-toggle behavior and the semantic structure that task list syntax gives you, so prefer the bracket syntax whenever you can.

A few toggling shortcuts worth knowing:

• In Obsidian, use Cmd/Ctrl + L to toggle the current line.
• In VS Code with the Markdown All in One extension, use Alt + C to check or uncheck.
• On GitHub, click the box directly in the rendered preview.

Best Tools for a Markdown Checkbox To-Do List

Because the task list extension is part of GFM, support is broad but not universal. Here is a quick map of where checkbox lists render as interactive boxes versus where they fall back to plain bullets.

If you want to turn a finished to-do list into a shareable document, the cleanest path is to convert it to Word. Paste your Markdown — checkboxes included — into the Markdown to Word converter and you get a .docx file where each task becomes a real Word list item with the [x] or [ ] shown inline. From there you can reformat, comment, and share it with anyone who does not live in a text editor.

For a different audience, you can route the same Markdown through Markdown to PDF to produce a static snapshot of your task list, or use Markdown to HTML to embed it in a web page. And if you have plain-text notes that are not yet Markdown, the text to Markdown tool will normalize them so checkbox syntax works.

Conclusion: Build Better Markdown To-Do Lists

A markdown checkbox list is one of the highest-leverage features in GitHub Flavored Markdown: it takes five characters to write, it survives any text editor, and it renders as a real interactive box almost everywhere that matters. Keep your brackets consistent, indent nested items by two spaces, toggle by flipping x, and pick a tool that actually renders the boxes. When it is time to share the finished list outside a text editor, run it through the Markdown to Word converter to turn those checkboxes into a clean .docx the rest of your team can open without thinking about Markdown at all.