GuideBy MarkovoPublished October 20, 2026

Markdown Checkboxes: Syntax and Render Fixes

Write a Markdown checkbox as - [ ] task or - [x] task, then render it with task list support enabled. Diagnose failures in three places: the source can have a malformed marker, the renderer can leave valid brackets as text, or the application can display a box without saving its state. ¹⁷

Classify the failure before changing the Markdown checkbox

Repair malformed markers in the source, literal valid brackets in the renderer, and disappearing ticks in storage. A visible bullet tells you the renderer recognized a list, while a checkbox requires an additional transformation. Rewriting the same valid task line cannot add a missing renderer feature.

The first pair of symptoms occurred in our renderer probes. The state checks describe how to diagnose an application's behavior. We did not click through GitHub.com or VS Code. Local HTML output establishes what a converter emitted, not what another product lets a user save. ⁷

Write task markers inside list items

Put the task marker at the beginning of a list item's text. For a portable starting example, use a hyphen, a space, the bracketed state, another space, and the task label:

- [x] alpha
        - [ ] beta
        

The checked form contains x. The unchecked form contains a space. GFM also accepts uppercase X. An empty bracket pair, spaces around the letter, and a label joined to the closing bracket are different inputs. Our malformed examples stayed as bracketed text even in the local path that rendered the valid example as checkboxes. ¹⁷

Task markers need their list container. In our bare-marker sample, brackets at the start of a paragraph stayed text. In the fenced sample, the same task lines stayed code. That behavior is useful in documentation: a code fence presents the characters a reader should copy, while the unfenced list presents the tasks. ⁷

Nesting adds a list-structure question before it adds a checkbox question. Our nested sample placed a child task under its parent and produced nested checkboxes in Pandoc's GFM path. A child appearing alongside its parent points to indentation or list parsing. A child nested correctly but still showing brackets points to task processing. Inspect the list hierarchy before changing the checked state. ⁷

A pipe table is a different container. Our table sample produced a table in the table-capable configurations, but its task-looking cell stayed text. For a status table, write a textual status such as Done or Pending. For work someone needs to tick off, put the task in a list beside the table. ⁷

Numbered tasks also need an implementation-specific check. GFM defines the marker through list items, so a rule that says only hyphens can ever work is too narrow. Yet our local Pandoc GFM path left the numbered sample as brackets while converting the hyphen sample. Use the output from the intended renderer to decide whether numbered tasks fit that workflow. ¹⁷

Use a renderer configuration that processes task lists

Use a task-list-capable configuration when valid markers remain literal text. The following paths received identical source text. They demonstrate configured behavior, not a compatibility ranking for every installation of these libraries. ⁷

CommonMark keeps the task markers as text

Our markdown-it-py CommonMark configuration created the list but left its state markers visible. The preset's rule list does not include task list processing. Changing CSS does not perform the missing task-list parsing step. ²

Output from our basic task-list sample in both CommonMark configurations, unedited:

<ul>
        <li>[x] alpha</li>
        <li>[ ] beta</li>
        </ul>
        

The CommonMark configuration with breaks=True emitted the same output. In the pinned source, the soft-break renderer chooses between a newline and a line-break element. That option does not register a task parser or replace the bracket marker. ²³⁷

Python-Markdown's selected extensions leave brackets intact

Our Python-Markdown configuration enabled tables and fenced code, but did not convert the task markers. Extensions add particular syntax features. Enabling a table feature does not imply that every other extended Markdown feature is active. ⁴⁷

Output from our basic task-list sample, unedited:

<ul>
        <li>[x] alpha</li>
        <li>[ ] beta</li>
        </ul>
        

This is a configuration result, not a claim that Python-Markdown cannot support task lists through additional extensions. If an existing publishing pipeline uses it, compare the enabled extension set with the feature the document needs.

Pandoc GFM renders the basic list but leaves a numbered-list boundary

Our Pandoc GFM path generated checkbox inputs for the basic task list. The output contains a checked input for alpha and an unchecked input for beta. It also wraps each label around its input. ⁵⁷

Output from our basic task-list sample, unedited:

<ul class="task-list">
        <li><label><input type="checkbox" checked="" />alpha</label></li>
        <li><label><input type="checkbox" />beta</label></li>
        </ul>
        

The numbered sample exposed a narrower result than a general claim of task list support would suggest. The list remained ordered, but its markers did not become inputs. This is the observed behavior of the tested version and configuration, not evidence that GitHub.com behaves the same way. ⁷

Output from our numbered task-list sample, unedited:

<ol type="1">
        <li>[x] alpha</li>
        <li>[ ] beta</li>
        </ol>
        

An ordered list that survives while its task markers remain shows that list recognition succeeded. A table that survives without checkbox inputs shows that table support succeeded. Neither success proves that the task transformation ran for that container. ⁷

Save task state where the document can retain it

Keep task state in the Markdown source or in an application that writes it back. A generated checkbox element defines a displayed control. The HTML fragments above contain no mechanism for editing the original Markdown file. Changing a control in a browser would need a separate save operation to persist as a source edit.

For a static document, replace the space inside the marker with x and save the Markdown. For an application-backed checklist, the application must associate a rendered task with stored content and persist the change. GFM leaves interaction behavior to implementations. GitHub documents tasklists in comments as clickable controls, but that is documented platform behavior, not a result of our local renderer experiment. ¹⁶

Document conversion adds a source-review step. After PDF to Markdown conversion, compare each task label and its completed or pending state with the original document before turning it into an editable task list. A printed square can be decorative, and changing it into an unchecked task would assign meaning the source may not have. This is a manual cleanup workflow, not a claim that the conversion service implements task list rendering.

For a static checklist, keep readable task markers in the source and use a renderer that handles the required list form. For work that needs saved ticks, use source edits or an application with a save path. Literal brackets call for a syntax or renderer repair; disappearing ticks call for a storage repair.

How we tested

The experiment compares local HTML structure and does not test GitHub.com, VS Code, browser interaction, accessibility behavior, visual styling, or persistence. No Markovo renderer or conversion API participated in these tests.

The checkbox probe ran on 2026-10-19 with Python 3.11.14, markdown-it-py 4.0.0, Python-Markdown 3.10.2, and Pandoc 3.11. It reused the runner's basic checkbox source and added boundary cases. ⁷⁸

Run the probe from the repository root, using the existing environment:

.venv/bin/python runs/2026-10-19-markovo-markdown-checkbox/lab/checkbox_probe.py
        

The probe source contains every input and call. It writes HTML as .txt evidence files rather than executing it. The original runner command was .venv/bin/python tools/lab_markdown_render.py --lab runs/2026-10-19-markovo-markdown-checkbox/lab. The checkbox-only rerun preserved unrelated upstream rows. ⁸

Counts below come directly from results.json, restricted to relevant samples. Each cell is list items / checkbox inputs. The parser counts HTML start tags, counts checked and disabled attributes on inputs separately, and assigns no visual-quality score. This is a rendering probe, so PDF recall, OCR metrics, and tools/lab_score.py do not apply. ⁷⁸

Pandoc's basic and nested samples each contained a single checked input. Its uppercase sample also contained a checked input. None of the emitted inputs had a disabled attribute. The table sample produced a table in Python-Markdown and Pandoc GFM, but not in the CommonMark configurations. Those observations do not establish browser click behavior or storage. ⁷

Raw outputs use lab/renderers/<sample>--<renderer>.txt. The quoted basic outputs are CommonMark, CommonMark with breaks, Python-Markdown, and Pandoc GFM. The numbered example is Pandoc GFM's raw ordered-list output. The full checkbox count table includes checked, disabled, and table counts.

Source inspection used the pinned CommonMark preset's make() rule list and RendererHTML.softbreak(). Local extracts are the preset and the soft-break function. Pandoc's pinned specFor selects taskListSpec when its task-list extension is enabled. That entry point alone does not establish which list containers the dependency transforms. The numbered-list conclusion comes from the output, without attributing an unverified internal cause. ²³⁹

Sources

1. GFM task list items specification
2. markdown-it-py CommonMark preset, v4.0.0
3. markdown-it-py HTML renderer, v4.0.0
4. Python-Markdown extensions
5. Pandoc task_lists extension
6. GitHub tasklists documentation
7. Local renderer results and configuration
8. Reproducible checkbox probes
9. Pandoc CommonMark reader, 3.11