GitHub Task Lists

GitHub Task Lists are checklists created with Markdown that allow you to track tasks visually.

Each task begins with a checkbox. Unchecked tasks represent work that still needs to be completed, while checked tasks show completed work.

A simple example looks like this:

- [ ] Design the homepage
- [ ] Build the navigation menu
- [x] Create the project repository

Output

This simple format makes it easy to see the current progress of a project.

Task Lists are especially useful when multiple people are working together because everyone can quickly understand what has already been finished.

Task Lists improve project organization. Instead of keeping progress in separate notes or spreadsheets, you can manage tasks directly inside GitHub.

Some common benefits include:

• Track completed work
• Plan future features
• Organize project roadmaps
• Create release checklists
• Manage bug fixes
• Plan documentation updates
• Improve team collaboration
• Keep project goals visible

Because Task Lists are built into GitHub, they're easy for contributors to update as work progresses.

GitHub Task Lists use a very simple Markdown format.

For an unchecked task:

- [ ] Write the documentation

For a completed task:

- [x] Write the documentation

The only difference is the letter inside the square brackets:

• A space ([ ]) creates an unchecked task.
• A lowercase x ([x]) marks the task as completed.

GitHub automatically converts these into interactive checkboxes in supported locations.

Let's create a simple checklist for launching a website.

- [x] Register the domain
- [x] Set up web hosting
- [ ] Write documentation
- [ ] Test the contact form
- [ ] Launch the website

Output

This type of checklist is commonly used for project planning. As tasks are completed, contributors can update the checkboxes to reflect the current progress.

GitHub uses two types of checkboxes.

Unchecked Task

- [ ] Update the README

This indicates that the task still needs to be completed.

Checked Task

- [x] Update the README

This indicates that the work has already been finished.

Using checked and unchecked tasks together gives readers an instant overview of project progress.

GitHub Task Lists are supported in several places across GitHub:

• README.md files
• GitHub Issues
• Pull Requests
• GitHub Discussions
• Repository Wikis
• GitHub Pages (when using GitHub Flavored Markdown)

This flexibility makes Task Lists useful for both personal projects and large open-source repositories.

For example, you might use:

• A README checklist to show planned features
• An Issue checklist to track bug fixes
• A Pull Request checklist to confirm testing steps before merging
• A Wiki checklist to organize documentation tasks

Example: Feature Roadmap

Many open-source projects use Task Lists to share their development roadmap.

## Upcoming Features

- [x] User authentication
- [x] Dark mode
- [ ] PDF export
- [ ] Cloud backup
- [ ] Multi-language support

Visitors can immediately see which features are available and which ones are still under development.

Example: Documentation Checklist

## Documentation Progress

- [x] Installation Guide
- [x] Quick Start Guide
- [ ] API Reference
- [ ] FAQ
- [ ] Troubleshooting Guide

This keeps documentation organized and helps teams know which sections still need to be completed.

Why Developers Like GitHub Task Lists

Task Lists are popular because they are:

• Easy to write
• Easy to update
• Easy to understand
• Built into GitHub
• Perfect for collaboration
• Great for tracking progress
• Useful in both small and large projects

Instead of maintaining separate task management documents, developers can keep project planning alongside the source code and documentation.

Using Task Lists in GitHub README Files

One of the most common places to use Task Lists is in a project's README.md file. A README is often the first page visitors see, so it's a great place to share your project's current status or future plans.

## Project Roadmap

- [x] Initial release
- [x] Responsive design
- [x] User authentication
- [ ] PDF export
- [ ] Dark mode
- [ ] Multi-language support

Many open-source projects use this approach to keep their community informed. See the GitHub README Guide for full README structure and templates.

Using Task Lists in GitHub Issues

GitHub Issues are commonly used to report bugs, request new features, and manage project work. Task Lists help break large issues into smaller, manageable steps.

## Tasks

- [ ] Investigate the bug
- [ ] Find the root cause
- [ ] Fix the problem
- [ ] Test the solution
- [ ] Close the issue

Instead of describing everything in one paragraph, contributors can work through each task one by one. This makes issues easier to manage, especially when multiple people are involved.

Using Task Lists in Pull Requests

Task Lists are also useful in Pull Requests. Before merging code, developers often create a checklist to confirm that everything has been completed.

## Before Merging

- [x] Code reviewed
- [x] Tests passed
- [ ] Documentation updated
- [ ] Version number updated

Many development teams include a checklist in every Pull Request to improve code quality and maintain consistency.

Using Task Lists in GitHub Discussions

GitHub Discussions support Task Lists as well. For example, if you're planning a community event or gathering feedback for a new feature, you can organize ideas into a checklist.

## Community Feedback

- [x] Collect suggestions
- [ ] Review feedback
- [ ] Prioritize requests
- [ ] Publish roadmap

This keeps community discussions organized and easy to follow.

Using Task Lists in GitHub Wikis

Repository Wikis often contain technical documentation. Task Lists can help documentation teams track progress while creating guides.

## Documentation Progress

- [x] Installation Guide
- [x] Quick Start
- [ ] Configuration Guide
- [ ] Troubleshooting
- [ ] FAQ

Instead of maintaining a separate spreadsheet, contributors can update progress directly inside the Wiki.

Creating Nested Task Lists

Sometimes one task contains several smaller tasks. GitHub allows nested Task Lists by indenting child items.

- [ ] Launch the website
  - [x] Design homepage
  - [x] Build navigation
  - [ ] Write documentation
  - [ ] Final testing

Output

Nested Task Lists make large projects easier to organize. 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. It's a simple way to improve navigation inside your repository.

See Markdown Links for inline and reference link syntax.

Combining Task Lists with Inline Code

You can also include inline code inside task descriptions. This is especially helpful for technical documentation.

- [ ] 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.

## Frontend

- [x] Create homepage
- [ ] Build dashboard

## Backend

- [x] Database setup
- [ ] User authentication

## Documentation

- [ ] README update
- [ ] API guide

Grouping related tasks with Markdown headings improves readability and makes long checklists much easier to manage.

GitHub Task Lists are a feature of GitHub Flavored Markdown (GFM).

Standard Markdown does not include interactive checkboxes. GitHub extends the original Markdown syntax by adding support for Task Lists, tables, strikethrough text, and several other useful features.

When you use the correct Task List syntax on GitHub, the platform automatically displays each item as a checkbox.

- [ ] Write documentation
- [x] Fix login bug
- [ ] Publish release

GitHub renders these items as checkboxes, making it easy to track progress directly from the page.

💡 Deep dive: Read the complete GitHub Flavored Markdown guide for GFM extensions, CommonMark differences, and compatibility notes.

Task Lists are not part of the original CommonMark specification. Instead, they are included as an extension in GitHub Flavored Markdown.

Many modern Markdown editors also support Task Lists, but not every Markdown parser does.

Platform	Task Lists Supported
GitHub	✅ Yes
GitLab	✅ Yes
Obsidian	✅ Yes
VS Code Preview	✅ Yes
Many Markdown Editors	✅ Yes
Basic CommonMark Parser	❌ Not Always

If your Markdown will only be viewed on GitHub, you can safely use Task Lists.

If you're publishing Markdown somewhere else, check whether the platform supports GitHub Flavored Markdown.

Write Clear Task Names

Each task should clearly explain what needs to be done.

Instead of writing:

- [ ] Fix

Write:

- [ ] Fix mobile navigation menu

Specific task names help everyone understand the work without needing additional explanation.

Keep Tasks Short

A Task List should be easy to scan. Avoid writing long sentences inside a checkbox.

Instead of:

- [ ] Update all project documentation, review every page, check formatting, and verify every example.

Break it into smaller tasks:

- [ ] Update documentation
- [ ] Review formatting
- [ ] Verify examples

Smaller tasks are easier to complete and track.

Group Related Tasks

If your checklist is long, divide it into sections.

## Frontend

- [ ] Homepage
- [ ] Dashboard

## Backend

- [ ] Authentication
- [ ] Database

## Documentation

- [ ] README
- [ ] API Guide

Grouping tasks improves readability.

Update Task Lists Regularly

A checklist only stays useful if it's kept up to date. As work is completed, mark completed items with [x]. An outdated checklist can confuse contributors and make a project appear inactive.

Use Task Lists for Progress Tracking

Task Lists work best when they're used to track progress over time.

## Version 2.0

- [x] User login
- [x] Dashboard
- [ ] Export reports
- [ ] Email notifications

Readers can quickly see what's finished and what's still planned.

Many developers make the same mistakes when creating Task Lists. Here are the most common ones.

Incorrect Syntax

The checkbox must contain a space or an x.

Correct:

- [ ] Task

- [x] Task

Incorrect:

-[ ] Task

-[x] Task

Even small formatting errors can prevent the checklist from rendering properly.

Forgetting the Space

Always leave a space after the closing bracket.

Correct:

- [ ] Write documentation

Incorrect:

- [ ]Write documentation

This small detail improves readability and follows standard Markdown formatting.

Making One Huge Checklist

A checklist with fifty or more items is difficult to read. Instead, divide it into sections with headings — Development, Testing, Documentation, Deployment.

Using Task Lists for Everything

Task Lists are great for tracking work, but they aren't the best choice for every situation.

Use:

• Markdown Lists bullet lists for simple information
• Numbered lists for step-by-step instructions
• Markdown Tables for comparing information
• Task Lists for tracking progress

Choosing the right format improves your documentation.

Never Updating Completed Tasks

A checklist that never changes quickly loses its value. Whenever a task is finished, mark it as completed. This gives contributors an accurate view of the project's current status.

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

This type of checklist is useful for personal websites, business sites, and documentation projects.

Open Source Release Checklist

## Release Checklist

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

Using a checklist reduces the chance of forgetting important release tasks.

Documentation Project

## Documentation Tasks

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

As each guide is completed, contributors simply mark the task as finished. This provides a clear overview of documentation progress.

Software Development Progress

## Development Progress

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

This type of checklist is common in software repositories.

Bug Fix Checklist

## Bug Fixes

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

Using a checklist helps developers track which bugs have already been fixed.

Content Publishing

## Blog Publishing

- [x] Write article
- [x] Add images
- [ ] Proofread
- [ ] Publish
- [ ] Share on social media

Task Lists aren't only useful for developers—they also work well for content teams and marketing projects.

Documentation Roadmap

## Documentation Roadmap

- [x] Markdown Basics
- [x] Markdown Syntax
- [x] GitHub README Guide
- [x] GitHub Task Lists
- [ ] VS Code Markdown
- [x] Mermaid Diagrams
- [ ] Markdown Best Practices

This is a simple way to show readers what documentation is already available and what topics are coming next.

The best way to learn is by writing checklists yourself.

1. Open the Markdown Task List Generator and create a sample roadmap or release checklist.
2. Paste the Markdown into the Markdown Editor and preview how checkboxes render.
3. Try building checklists for three GitHub contexts:
   • A README roadmap section
   • An Issue bug-fix task breakdown
   • A Pull Request merge checklist
4. Add nested sub-tasks under at least one parent item.
5. Review your syntax against this checklist:

• Space inside brackets: [ ] or [x]
• Space after the dash: - [ ] Task
• Headings to group long lists
• Links or inline code where helpful

Keep the Markdown Cheat Sheet open for quick syntax lookup.

GitHub Task Lists provide a simple and effective way to organize work using Markdown checkboxes. Whether you're maintaining an open-source project, planning new features, or writing technical documentation, Task Lists help you track progress in a clear and structured format.

In this guide, you learned:

• What GitHub Task Lists are
• How to create checklists using Markdown
• Where Task Lists work on GitHub
• How to use them in README files, Issues, Pull Requests, Discussions, and Wikis
• How to create nested Task Lists
• Best practices for writing useful checklists
• Common mistakes to avoid
• Real-world examples you can adapt for your own projects

Well-organized Task Lists improve collaboration, make project progress easier to understand, and help contributors focus on the next steps. Keep your checklists updated, write clear task descriptions, and use them where they add real value to your documentation.

Continue learning Markdown with these guides:

Available now

• Markdown Basics — core concepts for beginners
• Markdown Cheat Sheet — quick syntax lookup
• Markdown Syntax — complete reference with examples
• Markdown Headings — document structure with H1–H6
• Markdown Paragraphs — blank lines and spacing
• Markdown Line Breaks — soft breaks, hard breaks, and <br> tags
• Markdown Lists — ordered, unordered, nested, and task lists
• Markdown Links — inline, reference, and relative links
• Markdown Images — syntax, URLs, alt text, and GitHub paths
• Markdown Tables — syntax, alignment, and GitHub GFM
• Markdown Code Blocks — fenced blocks and syntax highlighting
• Markdown Blockquotes — syntax, nesting, and GitHub callouts
• Markdown Horizontal Rules — section dividers with ---, ***, and ___
• Markdown HTML — use HTML tags inside Markdown documents
• Markdown Task Lists — checkbox syntax, nested checklists, and GitHub GFM
• Markdown Footnotes — references, citations, and GitHub GFM support
• GitHub Markdown — GFM syntax, README examples, and GitHub-specific features
• GitHub Flavored Markdown (GFM) — deep dive into GFM extensions and compatibility
• Markdown Emojis — Unicode emojis and GitHub emoji shortcodes
• Markdown Escaping Characters — backslash escaping, special characters, and code block alternatives
• Markdown Comments — HTML comments for hidden notes, TODOs, and editor reminders
• GitHub README Guide — templates, essential sections, and professional README workflows
• GitHub Task Lists — README, Issues, PR checklists, and GFM checkbox syntax
• VS Code Markdown — preview, shortcuts, extensions, and documentation workflow in Visual Studio Code
• Obsidian Markdown — vaults, internal links, backlinks, graph view, and note organization
• Markdown Math — LaTeX equations, inline math, block math, and platform support
• Mermaid Diagrams — flowcharts, sequence diagrams, class diagrams, and platform support
• Markdown Best Practices — write clearer, more professional documentation

Coming soon

• Markdown Examples