Add underscore notation [_] for unchecked task list items (#87)

Implements support for using underscore as an alternative to space
for unchecked task list items: `[_]` is now equivalent to `[ ]`.

This is useful for:
- Mobile devices where spaces inside brackets are hard to type
- Editors without monospaced fonts where `[ ]` may look ambiguous
- Visual clarity as underscore resembles an empty checkbox

Related to upstream discussion: jgm/djot#305
where jgm expressed support for this feature.

Changes:
- Update ListItem to explicitly handle underscore as unchecked marker
- Add official tests for underscore notation
- Add unit test in DjotConverterTest
- Update syntax.md and enhancements.md documentation

Author: dereuromark

docs/enhancements.md

@@ -15,6 +15,7 @@ They are either on the way to get incorporated upstream - or may be incorporated
 - [Optional Modes](#optional-modes)
   - [Significant Newlines Mode](#significant-newlines-mode)
 - [Language Features Beyond Spec](#language-features-beyond-spec)
+  - [Task List Underscore Notation](#task-list-underscore-notation)
   - [List Item Attributes](#list-item-attributes)
   - [Table Row and Cell Attributes](#table-row-and-cell-attributes)
   - [Boolean Attribute Shorthand](#boolean-attribute-shorthand)
@@ -249,6 +250,38 @@ They said:
 
 These are djot syntax features we've implemented that aren't yet in the upstream spec.
 
+### Task List Underscore Notation
+
+**Related:** [jgm/djot#305](https://github.com/jgm/djot/issues/305)
+
+**Status:** Implemented in djot-php
+
+The underscore `[_]` can be used as an alternative to space `[ ]` for unchecked task list items:
+
+```djot
+- [_] unchecked with underscore
+- [ ] unchecked with space
+- [x] checked item
+```
+
+**Output:**
+```html
+<ul class="task-list">
+<li><input type="checkbox" disabled> unchecked with underscore</li>
+<li><input type="checkbox" disabled> unchecked with space</li>
+<li><input type="checkbox" disabled checked> checked item</li>
+</ul>
+```
+
+**Rationale:** The underscore notation is useful when:
+- Typing on mobile devices where spaces inside brackets can be difficult
+- Using editors without monospaced fonts where `[ ]` may look ambiguous
+- The underscore visually resembles an empty checkbox in source
+
+Both notations are fully equivalent and can be mixed within the same list.
+
+---
+
 ### List Item Attributes
 
 **Related:** [jgm/djot#262](https://github.com/jgm/djot/pull/262)
@@ -811,6 +844,7 @@ vendor/bin/phpunit
 
 | Feature                           | Upstream PR/Issue                                                   | Status     |
 |-----------------------------------|---------------------------------------------------------------------|------------|
+| Task list underscore notation     | [djot:305](https://github.com/jgm/djot/issues/305)                  | Open       |
 | List item attributes              | [djot:262](https://github.com/jgm/djot/pull/262)                    | Open PR    |
 | Table row/cell attributes         | [djot:250](https://github.com/jgm/djot/issues/250)                  | Open       |
 | Boolean attribute shorthand       | [djot:257](https://github.com/jgm/djot/issues/257)                  | Open       |

docs/syntax.md

@@ -228,21 +228,23 @@ Indent with 2+ spaces for nested lists.
 
 #### Task Lists
 
-Use `[ ]` for unchecked and `[x]` or `[X]` for checked items.
+Use `[ ]` or `[_]` for unchecked and `[x]` or `[X]` for checked items.
+
+The underscore notation `[_]` is useful on mobile devices or in editors without monospaced fonts, where the space in `[ ]` can be hard to type or see.
 
 **Input:**
 ```djot
-- [ ] Todo item
+- [ ] Todo item (space)
+- [_] Todo item (underscore)
 - [x] Done item
-- [ ] Another todo
 ```
 
 **Output:**
 ```html
 <ul class="task-list">
-<li><input type="checkbox" disabled> Todo item</li>
+<li><input type="checkbox" disabled> Todo item (space)</li>
+<li><input type="checkbox" disabled> Todo item (underscore)</li>
 <li><input type="checkbox" disabled checked> Done item</li>
-<li><input type="checkbox" disabled> Another todo</li>
 </ul>
 ```
 

src/Node/Block/ListItem.php

@@ -8,7 +8,7 @@
  * List item
  *
  * For task lists, stores the raw marker character from inside brackets:
- * - ' ' (space) = unchecked
+ * - ' ' (space) or '_' (underscore) = unchecked
  * - 'x' or 'X' = checked/completed
  * - Extended markers (for custom rendering via events):
  *   - '-' = cancelled/not applicable
@@ -32,7 +32,7 @@ public function __construct(protected ?string $taskMarker = null)
     /**
      * Get the raw task marker character
      *
-     * Returns the character inside the brackets: ' ', 'x', 'X', '-', '/', '>', '?', etc.
+     * Returns the character inside the brackets: ' ', '_', 'x', 'X', '-', '/', '>', '?', etc.
      * Returns null if this is not a task list item.
      */
     public function getTaskMarker(): ?string
@@ -43,7 +43,7 @@ public function getTaskMarker(): ?string
     /**
      * For task lists: null = not a task, true = checked, false = unchecked
      *
-     * Note: This method only recognizes standard markers (' ', 'x', 'X').
+     * Note: This method only recognizes standard markers (' ', '_', 'x', 'X').
      * For extended markers, use getTaskMarker() and handle in render events.
      */
     public function getChecked(): ?bool
@@ -52,8 +52,8 @@ public function getChecked(): ?bool
             return null;
         }
 
-        // Standard markers
-        if ($this->taskMarker === ' ') {
+        // Standard markers - space and underscore are both unchecked
+        if ($this->taskMarker === ' ' || $this->taskMarker === '_') {
             return false;
         }
         if (strtolower($this->taskMarker) === 'x') {

tests/TestCase/DjotConverterTest.php

@@ -161,6 +161,21 @@ public function testTaskList(): void
         $this->assertStringContainsString('Checked', $result);
     }
 
+    public function testTaskListUnderscoreNotation(): void
+    {
+        $djot = "- [_] Unchecked with underscore\n- [ ] Unchecked with space\n- [x] Checked";
+
+        $result = $this->converter->convert($djot);
+
+        $this->assertStringContainsString('task-list', $result);
+        // Both underscore and space should render as unchecked checkboxes
+        $this->assertSame(2, substr_count($result, '<input disabled="" type="checkbox"/>'));
+        $this->assertSame(1, substr_count($result, 'checked=""'));
+        $this->assertStringContainsString('Unchecked with underscore', $result);
+        $this->assertStringContainsString('Unchecked with space', $result);
+        $this->assertStringContainsString('Checked', $result);
+    }
+
     public function testThematicBreak(): void
     {
         $djot = "Before\n\n***\n\nAfter";

tests/official/task_lists.test

@@ -59,3 +59,42 @@ baz
 </li>
 </ul>
 ```
+
+Underscore notation for unchecked items:
+```
+- [_] unchecked with underscore
+- [x] checked item
+.
+<ul class="task-list">
+<li>
+<input disabled="" type="checkbox"/>
+unchecked with underscore
+</li>
+<li>
+<input disabled="" type="checkbox" checked=""/>
+checked item
+</li>
+</ul>
+```
+
+Mixed underscore and space notation:
+```
+- [_] underscore unchecked
+- [ ] space unchecked
+- [x] checked
+.
+<ul class="task-list">
+<li>
+<input disabled="" type="checkbox"/>
+underscore unchecked
+</li>
+<li>
+<input disabled="" type="checkbox"/>
+space unchecked
+</li>
+<li>
+<input disabled="" type="checkbox" checked=""/>
+checked
+</li>
+</ul>
+```