Understanding Markdown task lists
A Markdown task list is an ordinary list where each item begins with [ ] (an empty checkbox) or [x] (a checked one), so - [ ] Add tests renders as an unchecked box and - [x] Add tests renders as a checked one. Task lists are a GitHub Flavored Markdown (GFM) extension — not part of the core CommonMark standard — so they produce real checkboxes on platforms that opt into GFM (GitHub, GitLab, Obsidian, Notion) and render as literal text everywhere that doesn't (Reddit, Discord, plain Slack, strict CommonMark parsers). On GitHub, checking a box also drives an automatic "3 of 5" progress counter on the issue.
That is the summary an AI overview gives you. What it can't give you is the part that actually saves you time: exactly which characters the parser is matching (and the tiny mistakes that silently break the checkbox), a platform-by-platform map of where the boxes are clickable versus read-only, and the patterns teams use to run real projects out of issues and pull requests. This guide covers all three.
Task lists blur the line between documentation and project management. You can drop them into pull request descriptions, GitHub issues, project wikis, and README files — putting the checklist inside the version-controlled document instead of a separate tool. That integration is the whole appeal: the same file that describes the work also tracks it.
Basic task list syntax
Creating a task list is a matter of adding a checkbox marker to a normal list item. Use any list bullet (-, *, or +), then [ ] for an open task or [x] for a completed one:
- [ ] Incomplete task
- [x] Completed task
- [ ] Another task
The parser is matching an exact pattern: bullet, space, [, a single character (a space or x), ], space, then the task text. Two mistakes silently break it:
- [](no space inside the brackets) renders as literal text, not a checkbox. An empty box needs a real space:- [ ].-[ ](no space after the bullet) isn't a list item at all.
Capitalization doesn't matter — both [x] and [X] mark a task complete. The full syntax reference:
| Syntax | Result |
|---|---|
- [ ] Task | Unchecked box (note the space between the brackets) |
- [x] Task | Checked box, marked complete |
- [X] Task | Also checked — capital X is accepted |
* [ ] Task / + [ ] Task | Also valid — any list bullet works |
- [ ] Task | Nested subtask (indent 2+ spaces under a parent) |
- [] Task | ❌ Renders as literal text — the space is missing |
When rendered on a GFM-aware platform these become checkboxes. Whether you can click them depends on where they appear — the next section maps that out. You can paste any of these snippets into a live renderer to see the result:
Where task lists work (and where they don't)
Because task lists are a GFM extension rather than core Markdown, support is uneven — and the most useful distinction is not "supported vs. not" but rendered-and-clickable vs. rendered-but-read-only vs. shown-as-literal-text. This is the single fact the generic answers get wrong: several popular chat apps do not render - [ ] as a checkbox at all.
| Platform | Renders - [ ]? | Clickable? | Notes |
|---|---|---|---|
| GitHub issues & PRs | Yes | Yes | Auto "X of Y" progress counter |
GitHub README / .md files | Yes | No | Read-only render |
| GitLab issues, MRs, wikis | Yes | Yes | Same behavior as GitHub |
| Obsidian | Yes | Yes | Extra states like [/], [-] |
| Notion | Yes | Yes | Maps to native to-do blocks |
| VS Code Markdown preview | Yes | No | Static preview only |
| Exported HTML / PDF | Yes | No | State is frozen at export time |
| CommonMark (strict) | No | No | Not part of the spec |
| No | No | Shows the literal [ ] | |
| Discord | No | No | Shows the literal [ ] |
| Slack (messages) | No | No | Use Slack Lists (paid) instead |
The pattern: task lists are interactive on the tools built around version control and note-taking, static everywhere they're rendered to a fixed output, and simply not a feature in most chat apps. In GitHub issues and pull requests they're fully interactive — a click on the box edits the issue body and flips [ ] to [x] in the discussion:
## What needs to be done:
- [x] Add authentication
- [ ] Implement password reset
- [ ] Add two-factor authentication
- [x] Write documentation
- [ ] Add unit tests
In a README or a static site generator (or an exported HTML or PDF file), that same list renders as proper checkboxes but they're read-only — they show the state that was saved, and clicking does nothing.
Nested Task Lists
Task lists can be nested, creating hierarchical task structures:
- [x] Feature development
- [x] Design phase
- [x] Frontend implementation
- [ ] Backend implementation
- [ ] Testing
- [ ] Deployment
- [ ] Staging deployment
- [ ] Production deployment
- [ ] Post-launch monitoring
Nested tasks are useful for breaking large projects into manageable components. Parent tasks can represent epics while child tasks represent stories or specific work items.
The checkbox system works at all nesting levels. You can track completion at both high-level and detailed levels, enabling flexible project visibility.
Task Lists with Descriptions
While the basic syntax is simple, you can add descriptions by using continuation:
- [ ] **Critical Bug Fix**
Fix authentication token expiration issue that affects 10% of users
Priority: High
Assigned to: John
- [x] **Performance Optimization**
Reduce page load time from 3s to under 1s
Completed by: Sarah
This approach combines task structure with detailed information, creating rich task documentation.
Using Task Lists in Project Management
Task lists enable lightweight project management directly in version control. Rather than maintaining tasks in separate tools, embed them in documentation, issues, and pull requests.
Sprint Planning: Create task lists for sprint goals and track completion throughout the sprint.
Release Notes: Document what was completed for each release using task list format.
Feature Tracking: Track feature implementation status with tasks for each component.
Bug Triage: Create task lists for bugs discovered, assigned, and fixed.
Onboarding: Create task lists for new team member onboarding steps.
Code Review Checklists: Include task lists in pull request descriptions for reviewers to verify code quality standards.
Task Lists in GitHub Issues
GitHub issues integrate task lists seamlessly:
## Description
This PR adds email notifications to the notification system.
## Testing Checklist
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] No new console errors
- [ ] Performance acceptable
## Review Checklist
- [ ] Code follows style guidelines
- [ ] Comments added for complex sections
- [ ] Documentation updated
- [ ] No breaking changes introduced
GitHub automatically calculates completion percentage for issues containing task lists, displaying progress at the top of the issue.
Task Lists for Code Review
Pull request descriptions can include task lists helping reviewers verify code quality:
## What does this PR do?
Implements user registration functionality with email verification.
## How to test
1. Navigate to /register
2. Fill in the form
3. Submit to receive verification email
## Code Review Checklist
- [ ] No console errors
- [ ] Error handling appropriate
- [ ] Accessibility standards met
- [ ] Performance acceptable
- [ ] Security best practices followed
- [ ] Comments clear and helpful
- [ ] Tests cover new code
- [ ] Documentation updated
Reviewers use these checklists to systematically verify code quality.
Task Lists for Documentation
Documentation can use task lists to track completeness:
# Installation Guide
## Operating System Installation
### Windows
- [x] Windows 10 installation steps
- [x] Windows 11 installation steps
- [ ] Windows Server installation steps
### macOS
- [x] Intel installation steps
- [x] Apple Silicon installation steps
### Linux
- [x] Ubuntu installation steps
- [ ] Fedora installation steps
- [ ] Debian installation steps
This shows readers which documentation is complete and which sections are still being written.
Task Lists for Meeting Notes
Meeting notes often include action items tracked with task lists:
# Team Meeting - January 15, 2025
## Attendees
John, Sarah, Mike, Lisa
## Decisions Made
- Approved new authentication system design
- Extended deadline to March 15
## Action Items
- [ ] John: Complete authentication mockups (Due: Jan 22)
- [ ] Sarah: Research third-party integrations (Due: Jan 25)
- [ ] Mike: Write API specifications (Due: Jan 30)
- [ ] Lisa: Prepare budget for new tools (Due: Feb 1)
Task lists keep meeting action items organized and trackable.
Advanced Task List Patterns
Progressive Disclosure: Start with high-level task list, then expand to details as needed:
- [ ] **Phase 1: Core Features**
- [ ] User authentication
- [ ] Basic CRUD operations
- [ ] Search functionality
- [ ] **Phase 2: Advanced Features**
- [ ] Analytics dashboard
- [ ] API integrations
- [ ] Advanced reporting
- [ ] **Phase 3: Polish**
- [ ] Performance optimization
- [ ] UI refinement
- [ ] Documentation
Dependency Tracking: Note dependencies between tasks:
- [ ] Setup database (BLOCKED: Waiting for infrastructure team)
- [ ] Design database schema (DEPENDS ON: Database setup)
- [ ] Write ORM models (DEPENDS ON: Database schema design)
- [ ] Implement API endpoints (DEPENDS ON: ORM models)
Status Tracking: Use descriptions to track status beyond simple completion:
- [ ] Feature X (Status: In Progress, 50% complete, Assigned to: John)
- [ ] Feature Y (Status: Waiting for design review)
- [x] Feature Z (Status: Complete, shipped in v1.2)
Task List Limitations and Workarounds
Some platforms have limitations on task list interactivity. Read-only views might not allow clicking checkboxes. Nested task limits might exist on some platforms.
For detailed project management, task lists are better suited as high-level tracking. Detailed project management might still benefit from dedicated tools. However, many teams successfully manage entire projects using GitHub issues with task lists.
Synchronization across systems can be tricky. If you use both GitHub issues and a separate project management tool, keep them synchronized carefully.
Best Practices for Task Lists
Keep task descriptions concise. Long descriptions make task lists unwieldy. Link to detailed documentation instead.
Use consistent formatting. If some tasks have descriptions and some don't, standardize the format across the entire list.
Update regularly. Mark tasks as complete promptly so everyone sees accurate progress. Stale task lists lose credibility.
Avoid overcomplicating. While nested tasks are useful, excessive nesting becomes confusing. Keep the structure clear.
Link to relevant issues or PRs. If a task has an associated issue or PR, link to it for easy reference.
Include due dates when important. Add due dates directly in task descriptions when deadlines matter.
Assign responsibility. For team projects, note who's responsible for each task to avoid duplicated work.
Tools that support task lists
GitHub: Full support in issues, pull requests, and discussions with interactive checkboxes and an automatic progress counter.
GitLab: Similar support to GitHub, with interactive task lists in issues and merge requests.
Notion: Renders - [ ] as native to-do blocks on import, with interactive checkboxes tied into its databases.
Obsidian: Native task-list support, plus non-standard states such as [/] (in progress) and [-] (cancelled) that themes and the Tasks plugin can style and filter.
Static site generators and Markdown editors: Most GFM-based renderers (MkDocs, Docusaurus, Hugo, VS Code preview, Markdown-to-HTML/PDF exporters) display checkboxes correctly but read-only.
A common misconception is that chat apps handle this syntax. They mostly don't: Discord, Reddit, and plain Slack messages render - [ ] as literal text, not a checkbox. Slack offers a separate built-in Lists feature (on paid plans) for structured task tracking, and in Discord the usual workaround is emoji such as ✅ and ⬜. When in doubt, paste your list into a live Markdown preview or the platform's own draft view before relying on it.
Conclusion
Task lists transform Markdown from static documentation into interactive project tracking. The simple syntax—checkboxes in lists—enables powerful workflows for code review, project management, and team coordination. Whether tracking sprint goals, documenting code review requirements, or managing meeting action items, task lists integrate progress tracking directly into version-controlled documents. Their widespread support across platforms makes them an essential tool for modern development teams and collaborative projects.