Creating Interactive Checklists with GitHub Flavored Markdown Task Lists

Desired Outcome

Create a Markdown list where each item shows a clickable checkbox that can be toggled in supported platforms (e.g., GitHub issues, GitLab merge requests).

Prerequisites

You need a Markdown renderer that implements GitHub Flavored Markdown (GFM) task‑list syntax or an equivalent extension. Examples include:

• GitHub’s web interface
• GitLab’s preview
• Bitbucket
• Node‑based markdown-it with the markdown-it-task-lists plugin
• Pandoc invoked with +task_lists

If you are using a plain CommonMark parser without extensions, the syntax will be ignored.

Procedure

1. Open or create a Markdown file (e.g., checklist.md).
2. Write each task on its own line, starting with a hyphen, a single space, an opening bracket, a space, a closing bracket, and another space. Use - [ ] for an unchecked item and - [x] for a checked item.
3. Ensure the line is not indented beyond the list marker; extra spaces or tabs can cause the line to be treated as a code block.
4. Optionally surround the list with blank lines to separate it from surrounding paragraphs.

- [ ] Buy milk
- [x] Walk the dog
- [ ] Review pull request

Expected Checks

After rendering in a GFM‑compatible viewer:

• Each line displays a clickable checkbox.
• Clicking the box toggles the state; on platforms that support editable task lists (e.g., GitHub issue comments) the underlying Markdown changes from - [ ] to - [x] or vice‑versa.
• In static HTML output you will see elements like <input type='checkbox' disabled> for unchecked items and <input type='checkbox' checked disabled> for checked ones.

Recovery Options (Troubleshooting)

• If the checkboxes appear as plain text - [ ], verify that your renderer supports GFM task lists. Enable the appropriate extension (e.g., add the tasklists plugin to markdown-it) or switch to a known GFM environment.
• Check for unintended indentation: remove any leading spaces or tabs before the hyphen.
• As a fallback, you can embed raw HTML: <input type='checkbox'> Buy milk. This works in any Markdown processor that allows inline HTML, but the state will not be persisted in the Markdown source.