C.W.K.
Stream
Lesson 02 of 08 · published

Task Lists — Checkboxes That Actually Commit

~10 min · markdown, gfm, tasks, github

Level 0Plaintext
0 XP0/64 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete

Lists with checkboxes that GitHub takes seriously

GFM task lists are unordered list items prefixed with [ ] (incomplete) or [x] (complete). The bracketed bit must come right after the list marker, with a single space.

What changes on GitHub

On issues, PRs, and discussions, task list items render as interactive checkboxes. Anyone with write access can toggle them. Each toggle becomes a real edit to the issue body — there is an audit trail in the issue's edit history.

GitHub also computes a completion percentage from task lists in PR descriptions. PR list views display '3 / 8' next to the title. Cheap progress bar for free.

Nesting tasks

Indent the same way you nest any list: 2-space increments. Nested tasks render as nested checkboxes; the parent is independent of children (toggling a parent does not toggle children).

Principle: A task list in an issue is a contract with the team. Each box is one verifiable, atomic step. Vague items ('improve performance') don't deserve a checkbox; concrete ones ('add index on users.email') do.

Code

Basic task list·markdown
- [ ] Read the spec
- [x] Sketch the schema
- [ ] Write the migration
- [ ] Add tests
Nested tasks (substeps)·markdown
- [ ] Ship release v2
  - [x] Tag the commit
  - [x] Update CHANGELOG
  - [ ] Push the tag
  - [ ] Announce in #general
Mixed with regular bullets·markdown
- Notes (no checkbox, just context)
- [ ] Action: file the bug
- [ ] Action: run the migration
- Owner: @cwk

External links

Exercise

Open one of your in-flight issues or PR descriptions. Convert every plain bullet that names an action to a task list item. Notice how the issue immediately becomes a live tracker rather than a one-time write-up. Toggle a couple of boxes from the GitHub UI and watch the edit history append.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.