From 97f87817ead5b7a26e0dfc535cfd60ec0597d130 Mon Sep 17 00:00:00 2001
From: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>
Date: Fri, 24 Jul 2026 02:07:16 +0530
Subject: [PATCH] feat(markdown): support GitHub-style task lists

Renders `- [ ] task` syntax via `@mdit/plugin-tasklist`, enabled by
default and configurable through the new `tasklist` markdown option
(set to `false` to disable). The default theme hides list markers for
task items and pulls checkboxes into the list gutter, GitHub-style.

close #413
close #1923
close #3648
close #5110

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 __tests__/unit/node/markdown/markdown.test.ts | 29 +++++++++++++++++++
 docs/en/guide/markdown.md                     | 14 +++++++++
 package.json                                  |  1 +
 pnpm-lock.yaml                                | 18 ++++++++++++
 .../styles/components/vp-doc.css              | 10 +++++++
 src/node/markdown/markdown.ts                 | 13 +++++++++
 6 files changed, 85 insertions(+)

diff --git a/__tests__/unit/node/markdown/markdown.test.ts b/__tests__/unit/node/markdown/markdown.test.ts
index bb9a5ca7..11d338e5 100644
--- a/__tests__/unit/node/markdown/markdown.test.ts
+++ b/__tests__/unit/node/markdown/markdown.test.ts
@@ -42,6 +42,15 @@ describe('node/markdown/markdown', () => {
       expect(await render(':tada:', { emoji: false })).toContain(':tada:')
     })
 
+    test('tasklist', async () => {
+      const src = '- [ ] todo'
+      expect(await render(src)).toContain('<input type="checkbox"')
+
+      const disabled = await render(src, { tasklist: false })
+      expect(disabled).not.toContain('<input')
+      expect(disabled).toContain('[ ] todo')
+    })
+
     test('toc', async () => {
       const src = '# Title\n\n[[toc]]'
       expect(await render(src)).toContain('table-of-contents')
@@ -139,6 +148,26 @@ describe('node/markdown/markdown', () => {
     })
   })
 
+  describe('tasklist', () => {
+    test('renders checkboxes with their checked state', async () => {
+      const html = await render('- [ ] todo\n- [x] done')
+      expect(html).toContain('<ul class="task-list-container">')
+      expect(html).toContain('<li class="task-list-item">')
+
+      const inputs = html.match(/<input[^>]*>/g)!
+      expect(inputs).toHaveLength(2)
+      expect(inputs[0]).not.toContain('checked')
+      expect(inputs[1]).toContain('checked')
+      for (const input of inputs) expect(input).toContain('disabled')
+    })
+
+    test('forwards options to the plugin', async () => {
+      const html = await render('- [ ] todo', { tasklist: { label: false } })
+      expect(html).toContain('<input type="checkbox"')
+      expect(html).not.toContain('<label')
+    })
+  })
+
   // attrs applies at a fixed position in the core chain (before linkify),
   // while anchor pushes to its end, so anchor always sees user-defined ids
   // no matter which plugin is registered first
diff --git a/docs/en/guide/markdown.md b/docs/en/guide/markdown.md
index 5b863ce0..762cefe7 100644
--- a/docs/en/guide/markdown.md
+++ b/docs/en/guide/markdown.md
@@ -100,6 +100,20 @@ For more details, see [Frontmatter](../reference/frontmatter-config).
 | col 2 is      |   centered    |   \$12 |
 | zebra stripes |   are neat    |    \$1 |
 
+## Task Lists
+
+**Input**
+
+```md
+- [ ] Write the press release
+- [x] Update the website
+```
+
+**Output**
+
+- [ ] Write the press release
+- [x] Update the website
+
 ## Emoji :tada:
 
 **Input**
diff --git a/package.json b/package.json
index 87facedb..bee55867 100644
--- a/package.json
+++ b/package.json
@@ -132,6 +132,7 @@
     "@mdit/plugin-anchor": "^1.1.1",
     "@mdit/plugin-attrs": "^1.0.2",
     "@mdit/plugin-emoji": "^1.1.0",
+    "@mdit/plugin-tasklist": "^1.0.1",
     "@polka/compression": "^1.0.0-next.28",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-commonjs": "^29.0.3",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0d3bb5dd..118c154d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -116,6 +116,9 @@ importers:
       '@mdit/plugin-emoji':
         specifier: ^1.1.0
         version: 1.1.0(markdown-it@14.2.0)
+      '@mdit/plugin-tasklist':
+        specifier: ^1.0.1
+        version: 1.0.1(markdown-it@14.2.0)
       '@polka/compression':
         specifier: ^1.0.0-next.28
         version: 1.0.0-next.28
@@ -660,6 +663,15 @@ packages:
       markdown-it:
         optional: true
 
+  '@mdit/plugin-tasklist@1.0.1':
+    resolution: {integrity: sha512-Ks/Tihw5ibbkP2qOZzltkbiTk8RfpxDRvqdn4hl1wIs3VmeKITIQ36gN4DsuotSauA9SBe/mL0QJIfuSCrXqrw==}
+    engines: {node: '>=22'}
+    peerDependencies:
+      markdown-it: ^14.2.0
+    peerDependenciesMeta:
+      markdown-it:
+        optional: true
+
   '@napi-rs/wasm-runtime@1.1.6':
     resolution: {integrity: sha512-ZLv/JdUfkvOy9eCnnBaGfiO+XimbjebAeO+MRQqD/B+FR1tnRN0tpKSJHRbE8sFfS6aqsXZ67TQjfwfsxULVbg==}
     peerDependencies:
@@ -3259,6 +3271,12 @@ snapshots:
     optionalDependencies:
       markdown-it: 14.2.0
 
+  '@mdit/plugin-tasklist@1.0.1(markdown-it@14.2.0)':
+    dependencies:
+      '@types/markdown-it': 14.1.2
+    optionalDependencies:
+      markdown-it: 14.2.0
+
   '@napi-rs/wasm-runtime@1.1.6(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)':
     dependencies:
       '@emnapi/core': 1.11.1
diff --git a/src/client/theme-default/styles/components/vp-doc.css b/src/client/theme-default/styles/components/vp-doc.css
index 9dbfe4b5..fe9aa3df 100644
--- a/src/client/theme-default/styles/components/vp-doc.css
+++ b/src/client/theme-default/styles/components/vp-doc.css
@@ -163,6 +163,16 @@
   margin: 8px 0 0;
 }
 
+.vp-doc li.task-list-item {
+  list-style: none;
+}
+
+.vp-doc .task-list-item-checkbox {
+  margin: 0 4px 2px -1.25rem;
+  vertical-align: middle;
+  accent-color: var(--vp-c-brand-1);
+}
+
 /**
  * Table
  * -------------------------------------------------------------------------- */
diff --git a/src/node/markdown/markdown.ts b/src/node/markdown/markdown.ts
index 59d5b799..4eed02c5 100644
--- a/src/node/markdown/markdown.ts
+++ b/src/node/markdown/markdown.ts
@@ -20,6 +20,10 @@ import {
   type MarkdownItAttrsOptions
 } from '@mdit/plugin-attrs'
 import { fullEmoji as emojiPlugin } from '@mdit/plugin-emoji'
+import {
+  tasklist as tasklistPlugin,
+  type MarkdownItTaskListOptions
+} from '@mdit/plugin-tasklist'
 import type {
   CodeToHastOptions,
   LanguageInput,
@@ -193,6 +197,12 @@ export interface MarkdownOptions extends MarkdownItAsyncOptions {
    * @see https://mdit-plugins.github.io/emoji.html
    */
   emoji?: EmojiPluginOptions | false
+  /**
+   * Options for `@mdit/plugin-tasklist` (GitHub-style task lists,
+   * `- [ ] task`). Set to `false` to disable.
+   * @see https://mdit-plugins.github.io/tasklist.html
+   */
+  tasklist?: MarkdownItTaskListOptions | false
   /**
    * Improves emphasis (`**bold**`) handling in Japanese, Chinese, and
    * Korean text.
@@ -365,6 +375,9 @@ export async function createMarkdownRenderer(
   if (options.emoji !== false) {
     emojiPlugin(md, options.emoji)
   }
+  if (options.tasklist !== false) {
+    tasklistPlugin(md, options.tasklist)
+  }
   if (options.cjkFriendlyEmphasis !== false) {
     mditCjkFriendly(md)
   }