Markdown Task Lists: Checklists in Markdown

Task lists add checkboxes to markdown documents. The syntax is - [ ] for an unchecked box and - [x] for a checked one. Task lists are a GitHub Flavored Markdown (GFM) extension, not part of the original spec, but most modern parsers support them.

Basic Syntax

- [x] Write the draft
- [x] Add code examples
- [ ] Review with team
- [ ] Publish

The checkbox markers must start with - (a list marker), then [ ] or [x] with a space between the brackets for unchecked items and an x for checked items.

Both lowercase x and uppercase X work on most parsers, but lowercase is the convention.

Interactive vs Static Checkboxes

On GitHub, task lists in issues and pull requests are interactive. You can click a checkbox to toggle it, and GitHub updates the markdown source file automatically. This makes task lists useful for tracking progress directly in an issue.

On most other platforms (VS Code preview, MDtoLink, static site generators), checkboxes render as visual indicators but are not clickable. They are static.

Obsidian renders interactive checkboxes in its editor, storing the state in the markdown file.

Task Lists in GitHub Issues

GitHub issues show a progress indicator when a task list is present. If an issue contains a task list with 4 items and 2 are checked, the issue list shows “2 of 4” with a progress bar.

## Release Checklist

- [x] Merge feature branch
- [x] Update version number
- [ ] Write release notes
- [ ] Tag the release

This turns GitHub issues into lightweight project trackers without extra tooling.

Sub-Issues from Task Lists

On GitHub, you can convert a task list item into its own issue:

1. Open the issue containing the task list
2. Hover over an unchecked item
3. Click the circle icon to create a sub-issue

The original task list item becomes a link to the new issue, and checking/closing the sub-issue checks off the parent task.

Nested Task Lists

You can nest task lists using standard list indentation:

- [ ] Backend
  - [x] Database schema
  - [x] API endpoints
  - [ ] Authentication
- [ ] Frontend
  - [ ] Component library
  - [ ] Page layouts
  - [x] Design mockups

Parent items do not auto-check when all children are checked. You must check the parent manually.

Task Lists with Other Content

Task list items with descriptions:

- [x] **Set up the database**
  Created PostgreSQL instance and ran migrations.
- [ ] **Write API tests**
  Need coverage for all CRUD endpoints.

Task list items with links:

- [x] Fix login bug ([#42](https://github.com/user/repo/issues/42))
- [ ] Update docs ([PR pending](https://github.com/user/repo/pull/55))

Task list items with code:

- [x] Install the CLI: `npm install -g mdtolink`
- [ ] Configure: create `.mdtolink.yml`

Practical Templates

Pull Request Checklist

## PR Checklist

- [ ] Tests pass locally
- [ ] No new warnings or errors
- [ ] Documentation updated (if applicable)
- [ ] Breaking changes documented
- [ ] Reviewed by at least one teammate

Sprint Planning

## Sprint 14 Goals

- [x] User authentication flow
- [x] Password reset email
- [ ] Profile settings page
- [ ] API rate limiting
- [ ] Error tracking integration

Meeting Action Items

## Action Items (March 4 Standup)

- [ ] @david: Share API spec with frontend team
- [ ] @sarah: Review pricing page copy
- [x] @mike: Deploy staging environment

Release Checklist

## v2.1.0 Release

- [ ] All tests passing on main
- [ ] Changelog updated
- [ ] Version bumped in package.json
- [ ] Release notes drafted
- [ ] Tag created and pushed
- [ ] npm package published

Platform Differences

Common Mistakes

Missing space inside brackets. [-] or [X ] (extra space) will not render as a checkbox:

<!-- Wrong -->
- [-] Item
- [X ] Item

<!-- Correct -->
- [ ] Unchecked
- [x] Checked

Forgetting the list marker. The [ ] must follow a list marker (-, *, or +):

<!-- Wrong: no list marker -->
[ ] Not a task

<!-- Correct -->
- [ ] A task

Using task lists for non-task content. If the items are informational rather than actionable, use a regular list. Task lists imply something needs to be done or tracked.

FAQ

How do I create a checkbox in markdown?

Use - [ ] for an unchecked checkbox and - [x] for a checked one. The dash is a standard list marker, and the brackets with a space or x create the checkbox. This is a GFM extension supported by most modern parsers.

Are markdown checkboxes interactive?

On GitHub (in issues, pull requests, and comments) and in Obsidian, yes. Clicking the checkbox toggles its state and updates the source. On most other platforms, including VS Code preview and static sites, checkboxes are visual-only.

Can I track progress with markdown task lists?

On GitHub, issues with task lists show a progress bar (e.g., “3 of 5”) in the issue list. This gives you lightweight project tracking without a separate tool. You can also convert individual tasks into sub-issues for more detailed tracking.

Do task lists work in README files?

Yes, task lists render visually in README files on GitHub, GitLab, and most markdown viewers. They will not be interactive in a README (only in issues and PRs on GitHub), but the checkboxes still display correctly.

Try It Out

Build a task list and see it render in the MDtoLink editor. When your checklist is ready, publish it to a shareable URL for your team.

See all markdown syntax in the markdown cheat sheet. For regular lists (without checkboxes), see the markdown lists guide.