Markdown Checkboxes

Checkboxes (also called task lists) are a great way to create to-do lists, track progress, and organize tasks in your Markdown documents. They're especially useful in GitHub, GitLab, and other platforms that support interactive checkboxes.

Basic Checkbox Syntax

The syntax for checkboxes uses square brackets with a space or 'x' inside:

- [ ] Unchecked checkbox
- [x] Checked checkbox
- [ ] Another unchecked item

Result:

  • Unchecked checkbox
  • Checked checkbox
  • Another unchecked item

Important Syntax Rules

1. Space Requirements

  • Must have space after the hyphen: - [ ] not -[ ]
  • Space inside brackets for unchecked: [ ] not []
  • Lowercase 'x' for checked: [x] not [X]

2. List Format

Checkboxes must be part of a list (using -, +, or *):
- [ ] This works
* [ ] This also works
+ [ ] This works too

[ ] This doesn't work (not in a list)

Nested Checkboxes

You can create nested task lists with sub-tasks:

- [ ] Main task
- [ ] Sub-task 1
- [x] Sub-task 2 (completed)
- [ ] Sub-task 3
- [x] Another main task
- [x] Its sub-task

Result:

  • Main task
  • Sub-task 1
  • Sub-task 2 (completed)
  • Sub-task 3
  • Another main task
  • Its sub-task

Practical Examples

Daily To-Do List

## Today's Tasks

- [ ] Check emails
- [ ] Review project proposal
- [x] Team meeting at 10 AM
- [ ] Update documentation
- [ ] Plan tomorrow's work

Project Planning

## Website Redesign Project

- [x] Research phase
- [x] User interviews
- [x] Competitor analysis
- [x] Requirements gathering
- [ ] Design phase
- [x] Wireframes
- [ ] Visual design
- [ ] Prototype

Mixing with Other Formatting

You can combine checkboxes with other Markdown formatting:

- [x] **Important task** (completed)
- [ ] *Regular task* (in progress)
- [ ] `Code review` for project
- [ ] [Link to documentation](https://example.com)
- [ ] ~~Cancelled task~~ (struck through)

Result:

  • Important task (completed)
  • Regular task (in progress)
  • Code review for project
  • Link to documentation
  • Cancelled task (struck through)

Troubleshooting

Common Issues

  1. Checkbox not rendering: Check spacing and list format
  2. Not interactive: Platform may not support interactive checkboxes
  3. Inconsistent appearance: Different platforms style checkboxes differently

Correct vs Incorrect Syntax

❌ Incorrect:

-[ ] No space after hyphen
- [] No space in brackets
- [X] Uppercase X
[ ] Not in a list

✅ Correct:

- [ ] Space after hyphen
- [ ] Space in brackets
- [x] Lowercase x

Checkboxes are perfect for organizing tasks and tracking progress. They make your documents interactive and help keep projects organized!

Ready to add some visual content? Learn about images in Markdown next.