Markdown Checkbox: Task List Syntax and Fix Guide (2026)

TL;DR: Markdown checkboxes use - [ ] for unchecked and - [x] for checked items. The syntax is a GFM extension supported on 8 major platforms. Four of those (GitHub, GitLab, Obsidian, Typora) allow click-to-toggle. The four most common rendering failures all involve missing spaces in the bracket syntax.

Markdown checkboxes turn plain text into interactive task lists using - [ ] for unchecked and - [x] for checked items. Eight major platforms render them — GitHub, GitLab, Obsidian, Typora, VS Code, Bitbucket, Notion, and Pandoc — though only GitHub, GitLab, Obsidian, and Typora support click-to-toggle interactivity. Task lists are part of GitHub Flavored Markdown (GFM), not the core CommonMark specification, which means support varies by renderer. For the complete picture of GFM features including tables, alerts, and Mermaid diagrams, see our GitHub Markdown guide.

This guide covers the full syntax, nesting rules, inline formatting, platform differences, and the four mistakes that silently break checkbox rendering. If you also need to control how text wraps inside your lists, see the markdown line break guide for the four ways to force a new line.

What Are Markdown Checkboxes?

Markdown checkboxes are list items prefixed with a bracket pair that indicates completion state. The syntax comes from GitHub Flavored Markdown, which extended the original Markdown specification in 2014 to support task tracking directly in issues, pull requests, and README files.

A checkbox item is a standard unordered list item where the first content is a bracket pair:

- [ ] Unchecked task
- [x] Completed task

This renders as:

• Unchecked task
• Completed task

The bracket pair must appear immediately after the list marker and a space. GitHub renders these as actual HTML <input type="checkbox"> elements — and on github.com, they are clickable directly in issues and pull request descriptions.

Key distinction: Markdown checkboxes are purely a rendering feature. The underlying file always stores - [ ] or - [x] as plain text. "Checking" a box on GitHub edits the source Markdown automatically, but in a local .md file, you toggle the state by changing [ ] to [x] manually.

How Do You Create Markdown Checkboxes?

Type a list marker (-), a space, then [ ] or [x], followed by another space and your text. That is the entire syntax. Three elements, exact order — get one wrong and the checkbox silently fails. Here is each step.

Step 1: Start with a list marker

Use a hyphen (-), asterisk (*), or plus sign (+). Hyphens are the most common convention in GFM documentation:

- Item one
- Item two

Step 2: Add the checkbox bracket pair

Insert [ ] (with a space inside) for unchecked, or [x] for checked, between the list marker and the item text:

- [ ] Draft the README
- [ ] Add installation steps
- [x] Create the repository

Step 3: Separate the bracket from the text

A single space must follow the closing bracket before your task description. Missing this space is the most common cause of broken checkboxes:

- [ ] This renders correctly
- []This does not render as a checkbox

Complete example

Here is a full task list for a release checklist:

- [x] Write changelog
- [x] Bump version number
- [ ] Run test suite
- [ ] Tag release commit
- [ ] Publish to npm

On GitHub, this renders with a progress indicator showing "2 of 5 tasks complete" at the top of the issue or PR description. GitHub introduced task list support in 2014 as part of the GFM specification, and the syntax has remained stable since — every GFM-compatible tool parses - [ ] and - [x] the same way.

How Do You Nest and Format Markdown Checkboxes?

Indent with two or four spaces to nest subtasks, and use standard Markdown formatting (bold, italic, links, code) inside checkbox items. Everything you can put in a regular list item works inside a checkbox item too.

Nested checkboxes

Indent child items by two or four spaces (depending on the parser) to create subtasks:

- [ ] Backend API
  - [x] Design endpoints
  - [ ] Write integration tests
  - [ ] Deploy to staging
- [ ] Frontend
  - [ ] Build components
  - [ ] Connect to API

Most GFM-compatible renderers accept two-space indentation. Some parsers (notably Pandoc) require four spaces. When in doubt, use four — four-space indentation works across every parser that supports task lists.

Bold and italic formatting

Wrap task text with standard Markdown emphasis markers:

- [ ] **Critical:** fix authentication bug
- [ ] *Optional:* update color scheme
- [ ] ~~Cancelled:~~ migrate legacy database

Links and code inside checkboxes

You can embed links in markdown and inline code directly in checkbox items:

- [ ] Review the [API documentation](https://example.com/docs)
- [ ] Run `npm test` before merging
- [x] Update `package.json` version field

Combining with blockquotes

Checkboxes work inside blockquotes on most platforms, though rendering support is less consistent:

> **Sprint goals:**
> - [ ] Ship v2.0
> - [ ] Fix 3 critical bugs
> - [x] Update documentation

Which Platforms Support Markdown Checkboxes?

Markdown checkboxes are a GFM extension, not part of the CommonMark specification. Support varies across platforms and tools. Here is a breakdown of the major renderers.

Of the ten platforms listed, eight render checkboxes and four support click-to-toggle interaction. GitHub and GitLab edit the underlying Markdown source when you click, while Obsidian and Typora toggle the state in their editor view. CommonMark strict parsers and Reddit do not support task list syntax at all.

If you write markdown checkboxes in a file and preview it locally, the rendering depends entirely on your viewer. Most code editors with Markdown preview (VS Code, IntelliJ) support GFM task lists. Dedicated Markdown viewers like MacMD Viewer render checkboxes natively with full GFM support, including syntax highlighting and Mermaid diagrams alongside your task lists.

You can also test how your checkboxes render by converting your Markdown to HTML with our free Markdown to HTML converter — it uses a GFM-compatible parser that handles task lists.

What Are Common Markdown Checkbox Mistakes?

Four syntax errors cause nearly all broken checkbox rendering. Miss a single space and the checkbox fails silently — no error message, just raw brackets in your output. Every mistake involves spacing: a missing space inside the brackets, a missing space after the closing bracket, an uppercase X instead of lowercase, or a missing list marker before the brackets. The fix is always the same pattern: - [ ] (hyphen, space, open bracket, space, close bracket, space) followed by your text.

Missing space inside brackets

The bracket pair must contain exactly one space for unchecked items. An empty bracket pair renders as plain text on most platforms:

- [] This breaks — no space inside brackets
- [ ] This works — one space inside

Missing space after the closing bracket

The checkbox syntax requires a space between ] and the task text:

- [ ]No space after bracket — breaks on GitHub
- [ ] Space after bracket — renders correctly

Using the wrong case for the check mark

GFM specifies lowercase x. Some parsers accept uppercase X, but lowercase is the safe choice for maximum compatibility:

- [x] Lowercase x — works everywhere
- [X] Uppercase X — works on GitHub, may fail elsewhere

Forgetting the list marker

The bracket pair only becomes a checkbox when it follows a valid list marker. Without it, the brackets render as literal text:

[ ] This is not a checkbox — no list marker
- [ ] This is a checkbox — has a list marker

How Do You Preview Markdown Checkboxes on Mac?

macOS has no built-in Markdown renderer. TextEdit shows - [ ] as raw text. You need a third-party tool — here are three options, from free to purpose-built.

VS Code — Open the .md file and press Cmd+Shift+V to toggle the built-in Markdown preview. VS Code uses a GFM-compatible renderer that displays checkboxes correctly, though they are not interactive in the preview pane.

MacMD Viewer — A native macOS app built with SwiftUI that renders Markdown files with full GFM support, including checkboxes, syntax highlighting, Mermaid diagrams, and table formatting. It registers as the default .md handler, so double-clicking any Markdown file opens a rendered view instantly. At 2 MB, it launches faster than Electron-based alternatives. Download MacMD Viewer ($19.99, one-time purchase).

Terminal with Glow — Install Glow via Homebrew (brew install glow) and run glow README.md to render Markdown with checkbox support directly in your terminal.

Frequently Asked Questions

How do I make a checkbox in Markdown?

Type a list marker (hyphen, asterisk, or plus), a space, then [ ] for unchecked or [x] for checked, followed by a space and your task text. Example: - [ ] My task. This syntax is part of GitHub Flavored Markdown and works on GitHub, GitLab, VS Code, Obsidian, and most modern Markdown renderers.

Are Markdown checkboxes part of the official specification?

No. Checkboxes (task lists) are a GFM extension, not part of the CommonMark specification. GitHub formalized the syntax in their GFM spec as a strict superset of CommonMark. Most modern tools support them, but strict CommonMark parsers and some platforms like Reddit do not render them.

Can I make Markdown checkboxes clickable?

Only on platforms that support interactive checkboxes. GitHub issues and pull request descriptions allow clicking to toggle checkboxes, which edits the underlying Markdown source. Obsidian and Typora also support click-to-toggle. In static renderers (VS Code preview, Pandoc output, most viewers), checkboxes display but require manual editing of the [ ] / [x] text to change state.

Do Markdown checkboxes work in README files?

Yes. GitHub renders checkboxes in README.md files displayed on repository pages. They appear as styled checkboxes but are not clickable in README views — only in issues and PR descriptions. GitLab README files also render checkboxes with the same visual treatment.

What is the difference between a Markdown checkbox and a task list?

They are the same feature. "Task list," "checklist," and "checkbox" all refer to the GFM syntax - [ ] / - [x]. GitHub's documentation uses "task list" officially, while most developers say "checkbox" or "checklist" informally. The HTML output is identical: an <input type="checkbox"> element inside a list item.