Why Some Markdown Checkboxes Are Clickable and Others Aren't
You click a checkbox in one Markdown file and it toggles. Click the same-looking checkbox in another file, and nothing happens. The syntax is identical in both places. What differs is what the platform behind it is willing to do with a click.
Quick answer
A Markdown checkbox is written the same way everywhere: a hyphen, a space, [ ] or [x]. Whether clicking it does anything is a different question, and the syntax has no say in the answer. Some platforms — GitHub issues and comments, GitLab issues and merge requests — wire a checkbox to a live edit of the file behind it, so a click rewrites [ ] to [x] on the spot. Everywhere else, including a plain task list viewed as a static file, the checkbox renders but does nothing when you click it. That's not a bug in either renderer. It's a gap the Markdown spec leaves open on purpose.
How it actually works
Task lists are an extension, not core Markdown
Checkbox syntax comes from GitHub Flavored Markdown, not from Markdown itself. The GFM spec lists task list items as an extension, the same category as tables and strikethrough — additions layered on top of CommonMark, not requirements every parser has to implement. CommonMark's own maintainers have said as much directly: task lists are unlikely to ever join the core spec, since they weren't part of the original Markdown.
Because interactivity was never specified, every renderer decides on its own what a [ ] should look like and do — inert text, a static glyph, or a live control you can click. It's the same reason the same Markdown file renders differently everywhere: the source is identical, but nothing obligates two renderers to treat it the same way once it gets past parsing.
What happens when a click actually does something
Where click-to-toggle exists, it isn't cosmetic. GitHub documents task lists as clickable inside comments and issue or pull request bodies — checking one there edits the real, underlying Markdown, flipping [ ] to [x] in the source. That's also why the same feature goes read-only the moment you view a task list rendered inside a repository file instead of an issue. A file view has no live editing session attached to the click, so GitHub falls back to a plain rendering. Changing the state there takes write access and an actual file edit.
When to use it (and when to skip it)
Where it's a first-class feature
GitHub issues, pull requests, and comments — plus GitLab issues and merge requests — all treat a checkbox as part of a document you're actively editing, so a click is really a small, immediate write. GitLab goes further with its own extension: an inapplicable, indeterminate checkbox state written as [-], which isn't part of GFM at all. If anything, platforms keep adding divergent behavior on top of the base syntax, not converging toward one shared standard.
Where it quietly stops working
The same platforms that support click-to-toggle have documented exceptions. On GitLab, a checkbox written as raw HTML — often the workaround for placing one inside a table cell, since GitLab-flavored tables don't support block-level task lists — renders visually but doesn't respond to clicks. Only checkboxes produced from the native list syntax get the live behavior. The same logic explains why nested task lists can behave inconsistently across renderers: indentation rules that hold up on one platform can silently break the structure a click-to-toggle feature depends on.
The practical rule
Not looking at an issue, a pull request, or a merge request on a platform that documents the feature? Assume the checkbox is decoration. A note, a static page, an exported document, or a plain preview has no live document behind the click to write back to — so treating every checkbox as something you toggle by editing the text is the one approach that works no matter where the file ends up.
How Carets fits in
Carets treats a checkbox the same way in every context: as plain text you edit directly, not as a feature that depends on a particular renderer wiring it up. Because Carets works from Markdown, plain text, and code in one native editor, a task list you write on your iPhone reads and edits identically on Mac or in a pushed file on GitHub — nothing about it depends on a specific rendering environment to function. Your files stay portable and future-proof, organized into files, projects, and tags the way you'd organize any other writing.
Get Carets on the App Store for iPhone, iPad, and Mac.
Frequently Asked Questions
Why does a checkbox in one Markdown file toggle when I click it, but not in another?
It depends on where the file is rendered, not on the [ ]/[x] syntax itself. Platforms that treat a task list as a live document — GitHub issues and comments, GitLab issue and merge request descriptions — wire the checkbox to an edit that rewrites the underlying Markdown. A plain preview, a static site, or a rendered README file has no live document to write back to, so the same syntax renders as a static checkbox glyph or plain text instead.
Is checkbox interactivity part of the Markdown spec?
No. Task-list syntax itself is a GitHub Flavored Markdown extension on top of CommonMark, not part of the core spec, and CommonMark's maintainers have said it's unlikely to ever be folded in. The spec only defines how [ ] and [x] parse into a checked or unchecked list item — it says nothing about whether clicking one should do anything, so every renderer decides that on its own.
Does clicking a checkbox just change how it looks, or does it edit my file?
On platforms that support it, clicking edits the source. GitHub and GitLab both implement click-to-toggle as a real edit that rewrites [ ] to [x] (or back) in the underlying Markdown, the same as if you'd typed the change yourself. It isn't a cosmetic, browser-only state — that's precisely why it only works where there's an editable document behind the checkbox to write to.
Why isn't a checkbox inside a Markdown table clickable, even on a platform that normally supports it?
This is a documented GitLab quirk: GitLab Flavored Markdown tables don't support block-level task lists, so a checkbox inside a table cell is usually written as raw HTML instead of the native list syntax — and only checkboxes produced by the native syntax get the click-to-toggle behavior. The raw-HTML version renders but stays inert.
Should I rely on clickable checkboxes for tracking anything important?
Only where the platform makes it a first-class feature — GitHub issues and pull requests, GitLab issues and merge requests. Anywhere else, including a note, a README view, a static page, or an export, treat the checkbox as a plain visual marker you edit by hand. That's the more durable habit anyway: a task list you maintain by editing the text directly keeps working no matter which renderer eventually opens the file.
Conclusion
The checkbox character is universal. The click is not. [ ] and [x] parse the same way in every GFM-aware renderer, but whether a click does anything depends on a platform-specific feature built on top of that syntax, not a guarantee from the spec. Before you rely on a click to save anything, know which surface you're actually looking at — an editable document, or just a plain rendering of one.