How to use GitHub Markdown tasklists

What this covers

About tasklists explains Markdown task lists and the extra behavior when they live in an issue body. GitHub has retired tasklist blocks; prefer sub-issues for dedicated tracking sections (GitHub Blog, Adding sub-issues).

flowchart LR
    Syntax["Markdown Task List: - [ ] or - [x]"] --> Parser["GFM Tasklist Parser"]
    Parser --> Interactive["Interactive Checkbox in Issues/PRs"]
    Interactive --> Counter["Progress Counter: 2 of 5 completed"]

Markdown task lists

Each item is its own line with a clickable checkbox. References to issues, PRs, or discussions can unfurl title and state.

- [x] #739- [ ] https://github.com/octo-org/octo-repo/issues/740- [ ] Add delight to the experience when all tasks are complete :tada:

Issue-body extras

When the list is in an issue body:

• Progress appears in places like the repository issues list.
• Closing a referenced issue marks that task complete.
• Hover a task and use the convert control to turn it into an issue (keyboard shortcuts open the new-issue form with more detail).
• Referenced issues show they are Tracked by the parent issue.

Reorder and navigate

1. Hover left of a checkbox until the six-dot grip appears.
2. Drag the task to a new spot in the same comment (not across different comments).

From a tracked issue, open the tracking issue via the Tracked by control next to the status.

Further reading

• Basic writing and formatting syntax (task list syntax)
• Adding sub-issues