How to Make Checkboxes in Markdown: Task List Syntax Guide

To make a checkbox in Markdown, turn a list item into a task item with brackets: - [ ] for an open task and - [x] for a completed one. That is the whole trick, and it comes from the GitHub Flavored Markdown (GFM) task list extension rather than core Markdown. Many Markdown apps render it as a checklist automatically; others show the brackets as plain text, which is where most confusion starts.

This guide covers the exact markdown checkbox syntax, checked and unchecked states, nesting, checkboxes in tables and ordered lists, and why a task list sometimes fails to render. Everything here uses standard GFM examples you can paste into a file and test in one minute.

dc93cec5 783a 417c b441 e2ea50f825b1 — Editorial illustration of a Markdown task list document with empty and checked checkboxes

What a Markdown checkbox actually is

A checkbox, a checklist, and a todo list in Markdown are the same feature with different names. The GFM extension calls it a task list: a list item whose first block starts with a bracket marker. The Markdown Guide extended syntax reference describes it the same way: dashes and brackets with a space, [ ] for an open item and [x] for a selected one.

Task list syntax is an extension, not part of original Markdown. Markdown Guide notes that extended elements depend on the processor or lightweight markup language an app uses, so the same file can look interactive in one tool and literal in another.

Basic checkbox syntax and the mistakes that break it

Paste this into any GFM-compatible file:

```markdown

[x] Write the press release
[ ] Update the website
[ ] Contact the media
```

When the app supports task lists, you see real checkboxes next to the text; on GitHub you can click them and the file records the state change as a text edit from - [ ] to - [x]. Five details decide whether it renders:

A list marker first. Start with `- `, `* `, or `1. `. A bracket alone is not a list.
One space between the marker and the bracket. -[ ] is plain text.
Exactly one space inside the brackets. [ x ] does not become a checkbox.
x marks the item done. Use lowercase x; it is the form GitHub documents and every GFM renderer accepts.
No extra characters before the bracket. The task marker must open the item's first paragraph.

If you want to show a literal [x] in text, for example when writing about the syntax, escape the brackets with backslashes: \[x\]. This is the standard escape for a checkbox-looking fragment on GitHub, and it is the subject of a long-running Stack Overflow question about escaping the checkbox mark.

Markdown checklist patterns for real documents

A markdown checklist gets useful once you combine it with structure. Three patterns cover most cases.

Nested task lists

Indent the child items by two spaces under the parent task:

```markdown

[ ] Ship the release notes
[x] Draft the copy
[ ] Get review from the team
[ ] Update the changelog
```

Nested lists inherit the parent's indentation. If a child shows as a separate list at the wrong level, check that you used spaces, not tabs, and that the indent is at least two characters deeper than the parent marker.

Checkboxes in tables

Standard Markdown table cells cannot contain list items. Markdown Guide states that lists cannot be used in table cells, though some processors accept HTML inside a cell. The practical GitHub workaround is an HTML checkbox:

```markdown
| Step | Done |
| ------ | ------------------------------- |
| Draft | <input type="checkbox" disabled /> |
| Review | <input type="checkbox" /> |
```

This renders on GitHub and other HTML-tolerant renderers, but it is HTML, not task list syntax: other strict Markdown tools will show the tags as text. The common Stack Overflow thread on checkboxes in GitHub Markdown tables covers exactly this trade-off. If portability matters, keep the checkbox rows as a task list above or below the table instead.

Checkboxes in ordered lists

GFM task markers also work in numbered lists:

```markdown

[x] Outline the guide
[ ] Write the sections
[ ] Add examples
```

The number replaces the dash; the bracket rules stay identical.

Using a markdown todo list in project docs

Because a checked item is still plain text, a markdown todo list behaves well inside real files:

State lives in the diff. Toggling - [ ] to - [x] is a one-character change Git can show, so a task list at the top of a README or plan file doubles as a lightweight status record.
One line per task. Long sentences hide progress. Short, verb-first items scan better when you return to the file weeks later.
Group by milestone headings. A ## This week section with a short task list beats one giant checklist.
Keep done items visible for a while. Struck-through or checked items give context to what remains; delete them when the list gets long.

Why your checkbox renders as plain brackets

The most common markdown task list problem is not syntax, it is the app. Support varies because task lists are a GFM extension:

| Environment | Task list behavior |
| --- | --- |
| GitHub | Renders GFM task lists as clickable checkboxes in issues, files, and comments |
| VS Code | Built-in Markdown preview renders task lists; extensions such as the Markdown Checkbox extension add list-level toggling |
| Obsidian | Renders checkboxes in preview; community threads such as "How do I make a checkbox" mostly trace back to syntax or editing-mode confusion rather than missing support |
| Logseq | Users have asked for full GFM checkbox syntax support, as in the Logseq forum discussion |
| Joplin and DEVONthink | Checkbox rendering and customization come up repeatedly, for example the Joplin forum thread on checkbox syntax |
| JetBrains IDE previews | Rendering exists, but interactivity is still being requested; see the YouTrack issue on clickable preview checkboxes |

When brackets stay visible, check in this order:

The line starts with a list marker, then a space, then the bracket.
There is exactly one space inside the brackets.
Your app's Markdown flavor enables GFM. Some processors need a plugin before they render task lists at all; a parser such as Redcarpet, for example, gained checkbox rendering only through an add-on library.
You are in preview or live-render mode, not raw text editing.

Editing task lists in a local-first editor

If your task list lives in a project folder that other tools and AI agents also touch, the editor matters. Fylune is a local-first document workspace for macOS that renders rich Markdown inside the document experience, including task lists, tables, Mermaid diagrams, and KaTeX formulas, per its documented product capabilities. The selected project folder stays the source of truth, and core editing needs no account or network, so the file you toggle stays an ordinary .md file that GitHub, VS Code, or any GFM tool reads with the same - [x] syntax.

If an agent or a teammate edits your task-list file while you have it open, review the external changes before accepting them rather than letting a silent overwrite decide what is done.

Quick reference

```markdown

[ ] Open task
[x] Completed task

[ ] Task in an ordered list

[ ] Nested subtask

\[x\] shown as plain text
```

| You type | You get |
| --- | --- |
| - [ ] Task | Unchecked checkbox (GFM renderers) |
| - [x] Task | Checked checkbox (GFM renderers) |
| -[ ] Task | Plain text: missing space after the dash |
| - [ x ] Task | Plain text: wrong spacing inside brackets |
| \[x\] | Literal brackets, no checkbox |

FAQ

Can I put a checkbox in a Markdown table?

Not with task list syntax. Markdown list items are not allowed inside table cells, so the checkbox must come from HTML: an <input type="checkbox"> in the cell, as covered in the GitHub Markdown table checkbox thread. Remember the HTML version only renders in tools that permit inline HTML.

Are Markdown checkboxes clickable?

It depends on the app. GitHub renders them as interactive checkboxes you can click in issues and files. Some preview panes render the checkbox visually but not as a toggle, which is exactly what the JetBrains YouTrack issue requests. In a raw text editor, you always toggle a task by changing [ ] to [x] in the file itself.

How do I make a checkbox in Obsidian?

Use the same GFM syntax, - [ ] and - [x]. Obsidian renders task list checkboxes in its preview. If you see plain brackets, the likely causes are the spacing mistakes listed above or editing the file in a mode that shows the source rather than the rendered result; the Obsidian forum thread on making a checkbox is a good place to see how these cases resolve.

Sources

Markdown Guide, "Extended Syntax," task lists section: https://www.markdownguide.org/extended-syntax/ (checked 2026-09-28)
Stack Overflow, "How to draw checkbox or tick mark in GitHub Markdown table": https://stackoverflow.com/questions/47344571/how-to-draw-checkbox-or-tick-mark-in-github-markdown-table
Stack Overflow, "Github markdown escape checkbox mark": https://stackoverflow.com/questions/34643752/github-markdown-escape-checkbox-mark
VS Code Marketplace, "Markdown Checkbox" extension: https://marketplace.visualstudio.com/items?itemName=PKief.markdown-checkbox
Obsidian Forum, "How do I make a checkbox": https://forum.obsidian.md/t/how-do-i-make-a-checkbox/31096
Logseq Forum, "Support checkboxes syntax from GitHub Flavoured Markdown": https://discuss.logseq.com/t/support-checkboxes-syntax-from-github-flavoured-markdown/7330
Joplin Forum, "Extend customize checkbox markdown sintax": https://discourse.joplinapp.org/t/extend-customize-checkbox-markdown-sintax/43692
JetBrains YouTrack, "Markdown checkbox in preview should be clickable": https://youtrack.jetbrains.com/projects/IJPL/issue/IJPL-178532
GitHub, brightbit/markdown_checkboxes (Redcarpet plugin): https://github.com/brightbit/markdown_checkboxes
Fylune product capabilities: docs/config.json canonical snapshot (SELLING_POINT:rich-markdown, SELLING_POINT:local-first-offline, SELLING_POINT:free-core-editor), updated 2026-08-20

If you want to try a markdown checklist in a local-first editor, download Fylune for macOS.

Structured data (injected by the CMS)

```json
{"@context":"https://schema.org","@type":"BlogPosting","headline":"How to Make Checkboxes in Markdown: Task List Syntax Guide","datePublished":"2026-09-28T09:00:00+08:00","author":{"@type":"Person","name":"Nina@Aurcue","jobTitle":"Chief Marketing Officer at Aurcue","url":"https://www.tiktok.com/@NinaAurcue"},"publisher":{"@type":"Organization","name":"Fylune"},"mainEntityOfPage":"https://www.fylune.com/blog/markdown-checkbox-task-list"}
{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"Can I put a checkbox in a Markdown table?","acceptedAnswer":{"@type":"Answer","text":"Not with task list syntax. Markdown list items are not allowed inside table cells, so the checkbox must come from an HTML input element, which only renders in tools that permit inline HTML."}},{"@type":"Question","name":"Are Markdown checkboxes clickable?","acceptedAnswer":{"@type":"Answer","text":"It depends on the app. GitHub renders them as interactive checkboxes you can click in issues and files. Some preview panes render the checkbox visually but not as a toggle, and in a raw text editor you toggle a task by changing [ ] to [x] in the file itself."}},{"@type":"Question","name":"How do I make a checkbox in Obsidian?","acceptedAnswer":{"@type":"Answer","text":"Use the same GFM syntax, - [ ] and - [x]. Obsidian renders task list checkboxes in its preview. If you see plain brackets, check the spacing rules or your editing mode."}}]}
```