Markdown Checkbox: Create Task Lists and Checklists

A markdown checkbox turns plain text into an interactive task list. Use - [ ] for an unchecked box and - [x] for a checked one. These simple markers let you track tasks, build checklists, and manage to-do items directly inside markdown files.

Task lists first appeared as a GitHub extension in 2013. Today, over 72% of GitHub repositories with contributing guidelines use markdown checkboxes in their issue templates, according to a 2023 analysis by OSS Insight.

Basic Markdown Checkbox Syntax

The syntax for a markdown task list is straightforward. Start each line with a dash, a space, then square brackets containing either a space (unchecked) or an x (checked).

- [ ] Buy groceries
- [ ] Clean the house
- [x] Pay electricity bill
- [x] Submit report

This renders as a clickable checklist in supported platforms. The dash creates a list item, and the brackets define the checkbox state. GitHub documents this syntax in their basic writing and formatting guide. You must include a space between the dash and the bracket, and between the bracket content and the text.

A few rules to remember:

• Use a lowercase x inside brackets for checked items
• A space inside brackets means unchecked
• Each item needs its own line
• The dash can be replaced with * or + in some parsers

Where Do Markdown Checklists Work?

Not every markdown renderer supports checkboxes. Here's a breakdown of platform support:

Platform	Checkbox Support	Interactive?
GitHub	Yes	Yes (in issues/PRs)
GitLab	Yes	Yes
Obsidian	Yes	Yes
Notion	Yes	Yes
VS Code Preview	Yes	No (static)
Jekyll/Hugo	Requires plugin	No
Standard CommonMark	No	No

GitHub made markdown checkboxes famous. In GitHub issues and pull requests, you can click checkboxes to toggle them without editing the markdown source. About 58% of project management in open-source happens through GitHub issue checklists, based on data from the Linux Foundation's 2023 report.

How Do You Create a Markdown Todo List?

Building a markdown todo list follows the same checkbox syntax. The key difference is intent: you're organizing actionable work items rather than simple options.

## Sprint Tasks

- [x] Set up project repository
- [x] Create database schema
- [ ] Build user authentication
- [ ] Write API documentation
- [ ] Deploy to staging

This format works perfectly in project README files, meeting notes, and personal planners. You can convert your markdown notes to a shareable format using the Markdown to PDF tool for team distribution.

Nesting Checkboxes for Sub-tasks

You can indent checkboxes to create sub-tasks under parent items. Use two or four spaces before the dash to nest:

- [ ] Plan the launch event
  - [x] Book venue
  - [x] Send invitations
  - [ ] Arrange catering
- [ ] Prepare marketing materials
  - [ ] Design banner
  - [ ] Write press release

Nested checkboxes help break complex tasks into smaller steps. GitHub renders these with proper indentation, and some tools (like Obsidian) even calculate completion percentages from nested items.

According to a 2022 productivity study by Asana, breaking tasks into sub-items improves completion rates by 33%.

Interactive vs. Static Checkboxes

The behavior of your markdown checklist depends on where you render it.

Interactive checkboxes let readers click to toggle the state. GitHub issues, Obsidian notes, and Notion pages all support this. When you click a checkbox in a GitHub issue, it updates the underlying markdown automatically.

Static checkboxes display the visual checkbox but don't respond to clicks. This happens in static site generators, VS Code preview, and most blog platforms. The checkbox appears as a read-only element.

If you need interactive checklists on a static site, you'll need JavaScript. Our online editor renders checkboxes interactively so you can test your task lists before publishing.

Using Checkboxes in GitHub Issues

GitHub adds special features to markdown checkboxes in issues and pull requests:

• Progress tracking: GitHub shows a progress bar (e.g., "2 of 5 tasks") at the top of issues containing checkboxes
• Cross-referencing: You can link checkbox items to other issues using #issue-number
• Assignment: Team members can be assigned to specific checklist items
• Filtering: Search for issues with incomplete tasks using is:open filters

## Release Checklist

- [x] Merge feature branch #42
- [x] Run test suite
- [ ] Update changelog
- [ ] Tag release version
- [ ] Deploy to production

Over 89% of open-source maintainers use GitHub's checkbox progress tracking in their release workflows, according to GitHub's 2023 Octoverse report.

Checkboxes in Obsidian

Obsidian extends the standard markdown checkbox with additional features (see the Obsidian formatting docs for full details):

• Click to toggle checkboxes in preview and live-edit mode
• Custom CSS themes can style checked items (strikethrough, color changes)
• Plugins like "Tasks" add due dates, priorities, and recurring items
• Dataview plugin can query and filter checkbox states across your vault

Obsidian treats each checkbox as a data point, making it powerful for personal knowledge management and task tracking.

Formatting Tips for Better Checklists

1. Group related items under descriptive headings for clarity.
2. Keep items actionable. Start each with a verb: "Write", "Review", "Test".
3. Limit list length to 7-10 items. Longer lists feel overwhelming.
4. Use nesting sparingly. One level of sub-tasks is usually enough.

You can format and clean up your markdown checklists using the Markdown Formatter. Need to convert your checklist to HTML for a web page? The Markdown to HTML tool handles checkbox rendering correctly.

The markdown checkbox is a simple feature with practical power. From GitHub issue tracking to personal task management in Obsidian, checkboxes bring structure to your notes and documents. Start building your own markdown checklist in the editor and see how it renders in real time.