Markdown Checklist Generator

Markdown task lists: checkboxes in version control

A Markdown checklist is an extension introduced by GitHub Flavored Markdown (GFM) and later adopted across the ecosystem. The syntax is minimal: a bullet, a space, square brackets containing either a space (unchecked) or an x (checked). On GitHub, GitLab, Bitbucket, VS Code preview and Obsidian, those tokens are rendered as interactive checkboxes — readers can click them directly on a pull request or issue and the underlying Markdown is updated.

## Pre-merge checklist
- [x] Unit tests added
- [x] Lint passes (`npm run lint`)
- [ ] Docs updated
- [ ] Screenshots attached
  - [ ] Light mode
  - [ ] Dark mode

Where checklists actually pay off

• Pull request templates in .github/PULL_REQUEST_TEMPLATE.md — every PR opens with the same boxes (tests, docs, screenshots, breaking changes flagged).
• Issue templates for bug reports and feature requests so reporters do not skip steps.
• RFCs and ADRs with an embedded TODO list of decisions still to make.
• Onboarding docs ("first day", "first week") tracked in the repo, versioned alongside the code.
• Retrospectives and release readiness lists.

Nesting, indentation and detail lines

Sub-items are nested by indenting two spaces (sometimes four, depending on the parser). You can also mix free text between items by indenting under the parent without the - [ ] prefix — it appears as a continuation paragraph. CommonMark without the GFM extension renders - [ ] as literal text, so it is worth checking your target renderer before relying on the interactive behavior.

GitHub-specific behavior

On GitHub, checking a box in a pull request body re-commits the description and emits an event other automations can subscribe to. Including closes #123 in the body still closes the linked issue on merge — independently of whether its companion checkbox is ticked. Tools like the GitHub CLI, vim-markdown, the VS Code extension Markdown All in One and Obsidian provide toggle shortcuts so you do not have to edit the brackets by hand.

Checklists vs Jira, Linear, Trello

A Markdown list lives inside a document and travels with the code — it is great for contextual tracking next to the work itself. A task tracker (Jira, Linear, Trello) is the source of truth for what is actually planned, who owns it and when it is due. The healthy split is: real units of work in the tracker, ephemeral contextual checklists inline in the repo. Try not to duplicate; pick one as authoritative for each piece of work.

FAQ

Does it render the same everywhere? Anywhere that supports GFM does: GitHub, GitLab, Bitbucket, VS Code, Obsidian, Foam, most static-site generators with the remark-gfm plugin. Pure CommonMark renderers will leave the brackets as text.

Can I nest checklists deeply? Yes — keep the same indent step (two or four spaces). Beyond three levels readability drops, so consider splitting into sections instead.

Does ticking a box persist? Only inside hosts that re-write the file (GitHub issues/PR descriptions, Obsidian, VS Code). In a static rendering (a built docs site), clicking the checkbox does nothing because there is no file to update.

Do non-ASCII brackets break the syntax? Yes. Some locales auto-replace [ ] with full-width or curly variants — make sure your editor keeps ASCII square brackets, otherwise the parser will not detect the task.