Markdown Checklist Syntax: Checkboxes, Task Lists, and Fixes

Markdown Checklist Syntax: Checkboxes, Task Lists, and Fixes

A Markdown checklist uses a hyphen, a space, and square brackets on a task line: - [ ] marks an open task and - [x] marks a finished one. Renderers that support the task list extension draw those markers as checkboxes. Renderers that skip the extension print the brackets as plain text. This guide shows the exact syntax, builds a small working task list, explains why some checkboxes respond to clicks and others do not, and walks through fixes for lines that refuse to render.

Start with checked and unchecked tasks

- [ ] Send the draft to the reviewer
- [x] Save a copy of the signed PDF

Each task line has four parts: a hyphen, one space, a bracket pair, and the task text. The bracket pair holds a space for an open task and the letter x for a finished one. The GitHub Flavored Markdown specification accepts lowercase or uppercase x between the brackets; lowercase is the form most writers use. The specification also requires at least one whitespace character between the bracket pair and the task text, so - [x]Task is not a task list item.

Task lists are an extension, not core Markdown. GFM is a strict superset of CommonMark, and checkboxes live in the extension layer of that specification. A renderer that implements CommonMark only shows the same lines as an ordinary bullet with literal brackets. That output is correct behavior for that renderer, not a mistake in your file.

Build a useful small task list

Here is a three-item document handoff checklist with one child task:

- [x] Confirm every image path resolves
- [x] Update the changelog entry
- [ ] Hand off to the reviewer
- [ ] Attach the latest export

The source stores two things separately. List structure comes from the hyphen lines and their indentation. Task state comes from the character inside the brackets: a space or an x. Renaming a task or moving it up and down never touches its state, and changing state means editing one character.

The child task "Attach the latest export" uses two-space indentation, which lines up under a - marker. Indentation rules in Markdown are defined relative to the parent list marker, not by a fixed global number, so the exact width a renderer accepts for nested items varies. Verify the indented child renders as a nested checkbox in your target renderer before you publish. No tool promises one indentation width that works everywhere.

Understand rendered checkboxes versus interaction

A drawn checkbox and a clickable checkbox are different things. The GFM specification replaces the bracket marker with a semantic checkbox element and leaves interaction undefined: implementers may render the checkboxes as disabled elements, or they may handle checking and unchecking in the rendered document.

In practice you meet three kinds of behavior:

• Static box. The renderer draws a checkbox that does nothing when clicked. Published web pages usually behave this way.
• Interactive box. The application toggles the box and rewrites the source line for you, changing - [ ] to - [x]. Issue trackers and task-focused editors often work this way.
• No box. The renderer does not support the extension, so the brackets stay visible.

A screenshot cannot tell you which behavior you have. Click the box in the live document, then open the source file and check whether the brackets changed. That one check separates a preview from a real editing control.

Fix checkboxes that show as text

Missing hyphen. This source is a paragraph, and the brackets print as text:

- [ ] Send the draft to the reviewer

Add the list marker and the same line becomes a checkbox item:

- [ ] Send the draft to the reviewer

Spacing. Without the space after the hyphen, Markdown sees a paragraph, not a list item. The space after the closing bracket matters for the same reason:

-[x] Save a copy of the signed PDF

The corrected form:

- [x] Save a copy of the signed PDF

Code block context. Inside a fenced code block, every line is literal text by design. A checklist that looks broken inside a fence is behaving as specified. Move the task lines outside the fence and they render.

Unsupported extension. If your source matches the correct form and the renderer still shows brackets, the syntax is fine and the renderer is CommonMark-only. Paste the same lines into a GFM-based surface, such as a GitHub issue or a renderer that previews task lists, to confirm.

Keep tasks in a local Markdown file with Fylune

Because a checklist is only brackets inside an ordinary text file, the state travels with the file. Fylune, a local-first document workspace for Markdown and MDX, renders task lists, tables, diagrams, formulas, media, and code inside the document experience while the file stays in your project folder (Fylune features, fetched 2026-09-28 during this content task).

A practical loop: create handoff.md in a project folder, paste the checklist above, and save. To change a task, edit the bracket in the source from - [ ] to - [x] and save. The file remains a plain Markdown document that Git, Finder, and other editors read without conversion. Reopen the file later and the same lines render with their states intact. The features page states that opening, editing, searching, and organizing local Markdown and MDX files is free, and that editing works without an account or network (Fylune features). Fylune is in macOS alpha; the current download route is on the download page. If you also embed diagrams, the Mermaid guide covers that syntax: How to use Mermaid in Markdown.

Set expectations before you build a workflow on this notation. A Markdown checklist stores state as text. It does not schedule reminders, repeat tasks, assign work to teammates, or manage projects in the cloud, and Fylune does not add those features.

Questions before choosing a task workflow

Do Markdown checklists work everywhere? No. Task lists are an extension in the GFM specification, and not every renderer implements it. The same file can show checkboxes on GitHub and literal brackets in a CommonMark-only tool. Test your destination before you depend on the notation.

Do the boxes have to be clickable? No. The checkbox is a rendering of state that lives in the source brackets. A static checkbox is fine for a published document. Clicking is an application behavior, and it varies by tool.

How do I keep the source portable? Keep the plain form: hyphen, space, brackets, space, text. Store the file as ordinary .md in a folder and avoid app-specific task metadata. Any editor can then read the file, and your checked and unchecked states survive tool changes.

When should I use a real task manager instead? When you need reminders, due dates, recurring tasks, or team assignment. A Markdown checklist answers "what is done inside this document," not "who owes what by when."

If your documents live as local Markdown files, Fylune previews tasks, tables, and diagrams in place. The macOS alpha is available on the download page.

Sources

• GitHub Docs, "Basic writing and formatting syntax": https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
• GitHub Flavored Markdown Specification, version 0.29-gfm, section 5.3 "Task list items (extension)": https://github.github.com/gfm/
• Fylune Features page (fetched 2026-09-28 during this content task): https://www.fylune.com/features

SEO metadata for CMS handoff

• SEO title: Markdown Checklist Syntax: Checkboxes, Task Lists, and Fixes
• Meta description: Write a Markdown checklist with checked and unchecked tasks, understand renderer limits, and fix syntax that displays as plain text.
• Slug: markdown-checklist-syntax
• Canonical URL: https://www.fylune.com/blog/markdown-checklist-syntax
• Author: Orion Wells, Founder of Aurcue (CMS author 5)
• Structured data: use the existing CMS BlogPosting/Article and breadcrumb contract only; set datePublished on actual publication.