GitHub Task Lists

GitHub Task Lists are checklists created using GitHub Flavored Markdown (GFM). They use Markdown checkbox syntax to represent tasks that are completed or still in progress.

Unlike regular bullet lists, task lists can become interactive on supported GitHub pages. In Issues, Pull Requests, and other collaborative views, users can check or uncheck items directly from the GitHub interface without editing the Markdown source.

Task Lists are commonly used for:

• Release checklists
• Feature roadmaps
• Bug tracking
• Documentation progress
• Project planning
• Team collaboration

Because they combine simple Markdown syntax with GitHub's interactive interface, Task Lists have become one of the most widely used GFM features.

If you're new to Markdown checklists in general, see the Markdown Task Lists guide for core checkbox syntax across editors.

GitHub Task Lists make project progress easy to understand at a glance. Instead of maintaining separate documents or spreadsheets, teams can manage work directly inside GitHub using simple Markdown checkboxes.

Common benefits include:

• Track completed and pending work
• Create release and deployment checklists
• Organize feature development
• Manage bug-fix progress
• Improve collaboration during code reviews
• Keep project documentation up to date

For individuals, Task Lists provide a lightweight way to organize personal to-do lists. For teams, they create a shared view of project progress directly within GitHub.

GitHub Task Lists use simple Markdown checkbox syntax. An unchecked task starts with - [ ], while a completed task uses - [x].

- [ ] Write documentation
- [x] Create repository
- [ ] Review pull request
- [ ] Publish release

Output

Each task is displayed as a checkbox when rendered on GitHub.

When editing Markdown manually:

• - [ ] creates an unchecked task.
• - [x] creates a completed task.
• Both uppercase (X) and lowercase (x) are accepted.

On supported GitHub pages, users can simply click the checkbox to update its status without modifying the Markdown source.

GitHub Task Lists are supported across several GitHub features, making them useful for everything from project planning to technical documentation. While the Markdown syntax remains the same, the user experience varies depending on where the task list is used.

In interactive locations such as Issues, Pull Requests, and Discussions, users can check or uncheck tasks directly from the GitHub interface. In README files and most Wikis, task lists are rendered as checkboxes but typically serve as documentation rather than interactive project tracking.

Using Task Lists in README Files#

Task Lists are commonly used in README files to communicate project status, installation progress, release plans, and future improvements.

Typical examples include:

• Feature roadmaps
• Installation checklists
• Project milestones
• Release planning
• Documentation progress

Although README task lists are generally not interactive, they provide a clear visual overview of completed and upcoming work for anyone visiting the repository.

See the GitHub README Guide for full README structure and templates.

Using Task Lists in GitHub Issues#

GitHub Issues provide the best experience for Task Lists because checkboxes become interactive.

Instead of editing Markdown manually, collaborators can check or uncheck tasks directly from the GitHub interface. GitHub automatically updates the rendered checklist, making Issues an effective tool for tracking bugs, feature development, release planning, and team workflows.

Interactive task lists are especially useful for:

• Bug tracking
• Sprint planning
• Feature implementation
• Release checklists
• Team collaboration

Because task progress is visible to everyone involved, Issues are one of the most common places to use GitHub Task Lists.

Using Task Lists in Pull Requests#

Task Lists help reviewers and contributors track work before a Pull Request is merged.

Common examples include:

• Completing code reviews
• Running tests
• Updating documentation
• Verifying deployments
• Resolving review comments

A checklist makes it easier for reviewers to confirm that required tasks have been completed before approving changes.

Using Task Lists in Discussions#

GitHub Discussions support Task Lists for collaborative conversations, planning sessions, and community feedback.

Teams often use checklists to organize ideas, gather feedback, assign follow-up work, or summarize discussion outcomes.

GitHub Task Lists can be nested to break larger tasks into smaller, manageable subtasks. This is useful for organizing complex features, release checklists, or multi-step workflows.

- [ ] Release v2.0
  - [x] Complete development
  - [x] Run automated tests
  - [ ] Update documentation
  - [ ] Publish release notes

Output

Nested task lists improve readability by grouping related work under a single parent task, making large projects easier to plan and track.

See Markdown Lists for general list nesting rules.

Combining Task Lists with Links#

- [ ] Read the [Installation Guide](installation.md)
- [ ] Review the API documentation
- [ ] Submit the first pull request

This allows contributors to open the required documentation directly from the checklist. See Markdown Links for inline and reference link syntax.

Combining Task Lists with Inline Code#

- [ ] Run `npm install`
- [ ] Execute `npm run dev`
- [ ] Test the application

Using inline code makes commands easier to identify and copy. See Markdown Code Blocks for fenced blocks and syntax highlighting.

Combining Task Lists with Headings#

For larger projects, divide your checklist into sections using Markdown headings.

## Frontend

- [x] Create homepage
- [ ] Build dashboard

## Backend

- [x] Database setup
- [ ] User authentication

## Documentation

- [ ] README update
- [ ] API guide

Task Lists are a feature of GitHub Flavored Markdown (GFM), GitHub's extension of the CommonMark specification.

While standard Markdown does not define checkbox syntax, GFM adds support for task lists using - [ ] and - [x]. GitHub then renders these checkboxes across supported features such as README files, Issues, Pull Requests, Discussions, and Wikis.

If you want to learn more about the full GFM specification, including tables, footnotes, syntax highlighting, and other extensions, see the GitHub Flavored Markdown (GFM) guide.

Task list syntax is not part of the original Markdown specification created by John Gruber. Instead, it was introduced through GitHub Flavored Markdown (GFM) and later adopted by many modern Markdown editors and documentation tools.

If you're writing Markdown outside GitHub, check whether your editor or platform supports GitHub Flavored Markdown before using task lists.

💡 Tip: If you only want to learn Markdown checkbox syntax that works across supported Markdown editors, see the Markdown Task Lists guide. This guide focuses specifically on GitHub's implementation.

Follow these recommendations to make GitHub Task Lists easier to read and maintain.

Keep Tasks Short and Actionable#

Each task should describe a single action rather than combining multiple steps into one checkbox.

Group Related Work#

Use nested task lists to organize larger features, releases, or documentation projects into logical sections.

Keep Task Lists Up to Date#

Mark completed work promptly so collaborators always see accurate project progress.

Use Task Lists Where Collaboration Matters#

Task Lists work best in GitHub Issues and Pull Requests, where contributors can update progress directly from the GitHub interface.

Use Meaningful Task Order#

Arrange tasks in the order they should be completed to make project workflows easier to follow.

Even experienced developers make small mistakes that reduce the usefulness of Task Lists.

Using Task Lists for Large Documentation#

Long documentation pages are usually easier to read with headings and regular lists. Reserve Task Lists for items that actually need to be completed.

Combining Multiple Actions in One Task#

Instead of writing one long checkbox, split complex work into smaller tasks or nested subtasks.

Forgetting to Update Completed Tasks#

Outdated Task Lists quickly lose their value. Keep checklists synchronized with actual project progress.

Assuming Every Markdown Platform Supports Task Lists#

Task Lists rely on GitHub Flavored Markdown (GFM). Some Markdown parsers may ignore checkbox syntax or display it as plain text.

Using Task Lists When a Numbered Process Is Better#

If readers need to follow steps in sequence, a numbered list is often more appropriate than a checklist. See Markdown Lists for ordered and unordered list patterns.

Website Launch Checklist#

# Website Launch Checklist

## Development

- [x] Homepage completed
- [x] Responsive layout
- [ ] Contact form testing

## SEO

- [x] Meta title
- [x] Meta description
- [ ] XML sitemap

## Deployment

- [ ] Upload files
- [ ] Configure domain
- [ ] Enable HTTPS

Open Source Release Checklist#

## Release Checklist

- [x] Update version number
- [x] Run automated tests
- [ ] Update CHANGELOG
- [ ] Publish release notes
- [ ] Create GitHub release

Bug Fix Checklist#

## Bug Fixes

- [x] Fix login issue
- [ ] Resolve image loading bug
- [ ] Improve error messages
- [ ] Add automated tests

Documentation Progress#

## Documentation Tasks

- [x] Introduction
- [x] Installation Guide
- [x] Getting Started
- [ ] API Reference
- [ ] Tutorials
- [ ] FAQ

Feature Roadmap#

## Development Progress

- [x] Project setup
- [x] Authentication
- [x] User dashboard
- [ ] Notifications
- [ ] Payment integration

The best way to learn GitHub Task Lists is by using them in real projects.

Open the Markdown Editor to write and preview task lists before adding them to your repository. If you're starting from scratch, use the Markdown Task List Generator to create properly formatted checklists instantly.

Practice creating:

• A release checklist
• A bug-fix checklist
• A feature roadmap
• A documentation progress tracker
• A deployment checklist with nested tasks

As you become familiar with GitHub Task Lists, you'll naturally start using them in README files, Issues, Pull Requests, Discussions, and project documentation.

Summary#

GitHub Task Lists make it easy to organize work, track progress, and collaborate using simple Markdown checkbox syntax.

In this guide, you learned:

• What GitHub Task Lists are
• How to create task lists using GitHub Flavored Markdown (GFM)
• Where task lists work across GitHub
• How nested task lists improve project organization
• The differences between standard Markdown and GitHub Task Lists
• Best practices for collaborative development
• Common mistakes to avoid

Whether you're maintaining an open-source project, planning a release, managing issues, or documenting development progress, GitHub Task Lists provide a simple and effective way to keep work organized.