Markdown Task Lists & Checkboxes - Complete Guide
Master markdown task lists with interactive checkboxes. Learn syntax, nested lists, GitHub integration, and best practices for project tracking and documentation.
Markdown Task Lists & Checkboxes
Markdown task lists use checkboxes with - [ ] for incomplete and - [x] for completed items. On GitHub, these render as interactive checkboxes that automatically commit changes when checked. Perfect for tracking progress in issues, PRs, and documentation.
Quick answer: Create task lists with - [ ] for unchecked and - [x] for checked items. In GitHub issues and PRs, checkboxes are clickable and auto-commit. Use nested lists for subtasks and structure.
Basic Task List Syntax
Simple Task List
Rendered Output
- Completed task
- Incomplete task
- Another completed task
- Another incomplete task
Task List Structure
Key points:
- [x]= Completed/checked- [ ]= Incomplete/unchecked- Space inside brackets
[]is required for unchecked
Nested Task Lists
Two-Level Nesting
Rendered Output
- Setup project
- Initialize repository
- Add .gitignore
- Create README.md
- Implement features
- User authentication
- Data persistence
- API endpoints
Three-Level Nesting
Best practice: Limit nesting to 2-3 levels. Too many levels make task lists hard to read.
Task List Use Cases
GitHub Issue Tracking
Pull Request Checklist
Sprint Planning
Tutorial Checklist
- Install dependencies
- Copy environment template
- Edit .env with your values
- Start development server
Verification
- Verify server starts without errors
- Access application at
- Test database connection
- Run automated tests
Next Steps
- Read the documentation
- Explore the codebase
- Try running the example application
- Join the community Discord
Task List Best Practices
1. Use Descriptive Task Names
2. Keep Tasks Atomic
3. Organize with Headings
4. Use Nesting for Subtasks
5. Include Context and Due Dates
6. Mark Completed Items Clearly
Use - [x] for completed tasks. Some editors render these with strikethrough:
- Completed task
- Incomplete task
7. Limit Task List Length
Long task lists are hard to maintain. Consider breaking into multiple lists:
Task List in Different Contexts
README.md Task Lists
Task lists in README files show project status:
Note: Checkboxes in README files are static (not clickable) on GitHub.
GitHub Issues (Interactive)
Task lists in GitHub issues are interactive:
Interactive: Clicking checkboxes automatically commits changes to the issue.
Pull Requests (Tracking)
Use task lists in PRs for review progress:
Markdown Files (Static)
Task lists in regular markdown files render as static checkboxes:
Advanced Task List Features
Task List with Links
Task List with Code
Task List with Emojis
Task List with Priority Labels
Common Pitfalls
Inconsistent Formatting
Too Many Levels
Overly Broad Tasks
Missing Context
FAQ
Are task lists standard markdown?
No, task lists are part of GitHub Flavored Markdown (GFM). They work on GitHub, GitLab, and GFM-compatible platforms.
Can I use task lists in regular markdown files?
Yes, but checkboxes are static (not clickable) outside of GitHub issues and PRs. They'll render visually but won't be interactive.
Do task lists work in all markdown editors?
No, only GFM-compatible editors support task lists. Standard markdown editors may not render checkboxes correctly.
Can I have multiple task lists in one document?
Yes, you can have multiple task lists with different headings and contexts in a single markdown file.
How do I indicate task priority?
Add labels or emojis: - [ ] [High] Task or - [ ] :fire: Important task
What happens when I check a box on GitHub?
Checking a box in a GitHub issue or PR automatically commits the change to the issue/PR history.
Summary
Task List Syntax:
Nested Tasks:
Best Practices:
- Use descriptive, specific task names
- Keep tasks atomic (one action per checkbox)
- Organize with headings and nesting
- Include context, due dates, and priority
- Limit nesting to 2-3 levels
- Break long lists into multiple sections
Use Cases:
- GitHub issue tracking
- Pull request checklists
- Sprint planning
- Tutorial guides
- Release checklists
- Project status tracking
— Free editor with GFM support for task lists and interactive checkboxes.
Data sources: GitHub Flavored Markdown specification, GitHub documentation, CommonMark specification.
Practice
Try it in the editor.
Open Markdown Visualizer and test the ideas from this article in a live editor with instant preview.