Markdown Task Lists: Checkbox Syntax Guide

- [ ] Incomplete task item
- [x] Completed task item
  - [ ] Nested sub-task

Task lists—also known as checklist items, todos, or action items—are one of the most practical extensions to the original Markdown specification.

Whether capturing follow-up deliverables during a team meeting, maintaining a daily sprint log, or organizing software deployment steps, task lists bridge the gap between static text and actionable task management.

Standardized by GitHub Flavored Markdown (GFM) and natively integrated into Oyma, task lists render as interactive checkboxes that you can toggle directly without editing raw text.

Standard task list syntax

To create a task item, prefix an unordered or ordered list item with square brackets containing a space (for an incomplete task) or an x (for a completed task):

- [ ] Incomplete task awaiting action
- [x] Completed task marked as done

Notice the critical spacing requirements:

1. A space must follow the bullet character (-).
2. Exactly one space must sit inside the brackets for an unchecked box ([ ]).
3. Exactly one space must follow the closing bracket before the task description begins.

Case insensitivity: [x] vs [X]

The GFM specification defines task completion as case-insensitive. Both lowercase [x] and uppercase [X] represent completed tasks:

- [x] Completed using lowercase x
- [X] Completed using uppercase X

Recommendation: Consistently use lowercase [x], which is the format written by Oyma and Obsidian when toggling checkboxes via click or keyboard shortcut.

Nested task hierarchies

Complex deliverables often involve multiple constituent steps. You can nest task lists using standard list indentation (two to four spaces):

- [ ] Launch Q4 Security Overhaul
  - [x] Audit network egress logs
  - [x] Configure FileVault encryption policies
  - [ ] Rotate third-party API tokens
    - [ ] Update Anthropic BYOK key
    - [ ] Update OpenAI BYOK key
  - [ ] Publish audit summary in vault

In Oyma, nested tasks maintain clean alignment and can be collapsed via gutter disclosure arrows.

Combining task lists with formatting, dates, and [[WikiLinks]]

Task items in Oyma can contain rich inline formatting, tags, dates, and bidirectional wiki links:

- [ ] Schedule follow-up with [[Sarah Connor]] for [[2026-10-15]] #client-review
- [x] Review **architecture proposal** and verify SQLite WAL configuration
- [ ] Run automated tests: `pnpm verify` before merging to `main`

This flexibility allows you to integrate task management directly into your knowledge graph without separating tasks into a disconnected third-party todo app.

Interactive toggling in Oyma

In Oyma, task lists are fully interactive:

• Click to toggle: Click any checkbox in the live-preview editor to flip its status between - [ ] and - [x]. The underlying Markdown file on disk updates instantly.
• Keyboard shortcut: Place your cursor on any line and press ⌘Enter to toggle the task state or convert a standard paragraph into a task item.
• Visual styling: Completed tasks feature subtle dimmed contrast and optional strikethrough, keeping your active priorities visually prominent.

Frequently asked questions

What is the exact syntax for a Markdown task list item?

A task list item requires a bullet marker (`-`, `*`, or `+`), followed by a space, an opening square bracket (`[`), a single space or lowercase/uppercase `x`, a closing square bracket (`]`), another space, and your task description text (`- [ ] Task text`).

Can I use task checkboxes inside ordered (numbered) lists?

Yes. GFM supports task checkboxes in ordered lists: `1. [ ] First action item`, `2. [x] Second action item`.

Can I click checkboxes directly in the editor in Oyma?

Yes. In Oyma's live-preview editor, clicking any checkbox toggles its state between `- [ ]` and `- [x]` immediately on disk while applying a subtle strikethrough styling to completed items.

Does CommonMark support task lists natively?

Standard CommonMark 0.31 does not include task lists; task lists are a formal extension standardized by GitHub Flavored Markdown (GFM) and universally adopted by Obsidian, Oyma, and modern Markdown editors.