fix: parse nested list blocks with deeper indentation and tabs (#192)

* fix: parse nested list blocks with deeper indentation and tabs

* feat: add nestedBlocksInLists parser option (#191)

* fix: address review feedback for nested blocks in lists

- recognize all list-marker forms (parenthesized, alpha, roman numerals) when
  detecting immediate nested blocks, consistent with the list-marker parser
- base nested-content membership on the item content indent so an over-indented
  first nested line keeps trailing item content instead of detaching it into a
  top-level block and ending the list early
- correct the contradictory docblock in the tab-indentation nesting test
- document the nestedBlocksInLists option in the parser-options guide and the
  API reference

Author: dereuromark

docs/guide/parser-options.md

@@ -268,3 +268,79 @@ $converter = new DjotConverter(
     softBreakMode: SoftBreakMode::Break, // Optional: visible line breaks
 );
 ```
+
+## Nested Blocks in Lists Mode
+
+`nestedBlocksInLists` is a focused subset of [Significant Newlines](#significant-newlines-mode) mode. It lets indentation alone introduce nested blocks - sublists, blockquotes, and fenced code - inside an already-open list item, **without** enabling paragraph interruption anywhere else.
+
+Use it when you want markdown-like nested lists but otherwise spec-compliant djot: top-level paragraphs still require a blank line before any block.
+
+### Enabling Nested Blocks in Lists Mode
+
+```php
+use Djot\DjotConverter;
+use Djot\Parser\BlockParser;
+
+// Method 1: Factory method
+$converter = DjotConverter::withNestedBlocksInLists();
+
+// Method 2: Constructor parameter
+$converter = new DjotConverter(nestedBlocksInLists: true);
+
+// Method 3: Directly on the parser
+$parser = new BlockParser(nestedBlocksInLists: true);
+$parser->setNestedBlocksInLists(true);
+```
+
+### Behavior
+
+Indented content nests inside the open list item, even without a blank line:
+
+```php
+$converter = DjotConverter::withNestedBlocksInLists();
+$result = $converter->convert("- Item
+    - Nested one
+    - Nested two");
+```
+
+Output:
+```html
+<ul>
+<li>
+Item
+<ul>
+<li>
+Nested one
+</li>
+<li>
+Nested two
+</li>
+</ul>
+</li>
+</ul>
+```
+
+But a top-level block still does **not** interrupt a paragraph (this is what differs from significant newlines mode):
+
+```php
+$converter = DjotConverter::withNestedBlocksInLists();
+$result = $converter->convert("Here is a list:
+- one
+- two");
+```
+
+Output:
+```html
+<p>Here is a list:
+- one
+- two</p>
+```
+
+### nestedBlocksInLists vs significantNewlines
+
+| Behavior                                              | Default | `nestedBlocksInLists` | `significantNewlines` |
+|------------------------------------------------------|---------|-----------------------|-----------------------|
+| Nested blocks in list items without a blank line     | No      | **Yes**               | Yes                   |
+| Lists/blockquotes/headings interrupt top-level paragraphs | No | No                    | Yes                   |
+
+Note: `significantNewlines` implies `nestedBlocksInLists` - enabling the former turns on the latter automatically.

docs/reference/api.md

@@ -25,6 +25,7 @@ public function __construct(
     bool $roundTripMode = false,
     ?BlockParser $parser = null,
     ?RendererInterface $renderer = null,
+    bool $nestedBlocksInLists = false,
 )
 ```
 
@@ -38,6 +39,7 @@ public function __construct(
 - `$roundTripMode`: When `true`, adds round-trip metadata for Djot→HTML→Djot workflows (HTML renderer only).
 - `$parser`: Optional pre-configured parser. When provided, inline parser constructor flags such as `warnings`, `strict`, and `significantNewlines` are ignored.
 - `$renderer`: Optional pre-configured renderer. When provided, inline renderer constructor flags such as `xhtml`, `safeMode`, `softBreakMode`, and `roundTripMode` are ignored.
+- `$nestedBlocksInLists`: When `true`, indentation alone introduces nested blocks inside list items without a blank line, while top-level paragraph interruption stays spec-compliant (see [Nested Blocks in Lists Mode](/guide/parser-options#nested-blocks-in-lists-mode)). Implied by `$significantNewlines`.
 
 ### Factory Methods
 
@@ -57,6 +59,22 @@ public static function withSignificantNewlines(
 
 Creates a converter with significant newlines mode enabled. See [Significant Newlines Mode](#significant-newlines-mode).
 
+#### withNestedBlocksInLists()
+
+```php
+public static function withNestedBlocksInLists(
+    bool $xhtml = false,
+    bool $warnings = false,
+    bool $strict = false,
+    bool|SafeMode|null $safeMode = null,
+    ?Profile $profile = null,
+    ?SoftBreakMode $softBreakMode = null,
+    bool $roundTripMode = false,
+): self
+```
+
+Creates a converter that enables nested blocks in list items without requiring blank lines, while leaving top-level paragraph interruption at the spec default. See [Nested Blocks in Lists Mode](/guide/parser-options#nested-blocks-in-lists-mode).
+
 ### Methods
 
 #### convert()
@@ -500,6 +518,7 @@ $parser = new BlockParser(
     collectWarnings: false,
     strictMode: false,
     significantNewlines: false,
+    nestedBlocksInLists: false,
 );
 $document = $parser->parse($djotString);
 
@@ -510,6 +529,11 @@ $warnings = $parser->getWarnings();
 // Enable/disable significant newlines mode
 $parser->setSignificantNewlines(true);
 $isEnabled = $parser->getSignificantNewlines();
+
+// Enable/disable nested blocks in list items only
+// (significant newlines mode enables this implicitly)
+$parser->setNestedBlocksInLists(true);
+$isEnabled = $parser->getNestedBlocksInLists();
 ```
 
 #### Custom Block Patterns

src/DjotConverter.php

@@ -128,6 +128,7 @@ public static function ansi(?BlockParser $parser = null): self
      * @param bool $roundTripMode Add data attributes for Djot→HTML→Djot round-trips (HTML renderer only)
      * @param \Djot\Parser\BlockParser|null $parser Pre-configured parser (ignores warnings/strict/significantNewlines if set)
      * @param \Djot\Renderer\RendererInterface|null $renderer Pre-configured renderer (ignores xhtml/safeMode/softBreakMode/roundTripMode if set)
+     * @param bool $nestedBlocksInLists Allow nested blocks in list items without blank lines
      */
     public function __construct(
         bool $xhtml = false,
@@ -140,6 +141,7 @@ public function __construct(
         bool $roundTripMode = false,
         ?BlockParser $parser = null,
         ?RendererInterface $renderer = null,
+        bool $nestedBlocksInLists = false,
     ) {
         $this->collectWarnings = $warnings;
         $this->strictMode = $strict;
@@ -148,7 +150,7 @@ public function __construct(
         if ($parser !== null) {
             $this->parser = $parser;
         } else {
-            $this->parser = new BlockParser($warnings, $strict, $significantNewlines);
+            $this->parser = new BlockParser($warnings, $strict, $significantNewlines, $nestedBlocksInLists);
         }
 
         // Use provided renderer or create one from parameters
@@ -210,6 +212,42 @@ public static function withSignificantNewlines(
         return new self($xhtml, $warnings, $strict, $safeMode, $profile, true, $softBreakMode, $roundTripMode);
     }
 
+    /**
+     * Create a converter that only enables nested blocks in list items.
+     *
+     * Paragraph interruption remains standard djot behavior, but indentation
+     * alone can introduce nested sublists, blockquotes, and fenced blocks
+     * inside an already-open list item.
+     *
+     * @param bool $xhtml Whether to use XHTML-compatible output
+     * @param bool $warnings Whether to collect warnings during parsing
+     * @param bool $strict Whether to throw exceptions on parse errors
+     * @param \Djot\SafeMode|bool|null $safeMode Enable safe mode
+     * @param \Djot\Profile|null $profile Profile for feature restriction
+     * @param \Djot\Renderer\SoftBreakMode|null $softBreakMode How to render soft breaks (HTML renderer only)
+     * @param bool $roundTripMode Add data attributes for round-trips (HTML renderer only)
+     */
+    public static function withNestedBlocksInLists(
+        bool $xhtml = false,
+        bool $warnings = false,
+        bool $strict = false,
+        bool|SafeMode|null $safeMode = null,
+        ?Profile $profile = null,
+        ?SoftBreakMode $softBreakMode = null,
+        bool $roundTripMode = false,
+    ): self {
+        return new self(
+            xhtml: $xhtml,
+            warnings: $warnings,
+            strict: $strict,
+            safeMode: $safeMode,
+            profile: $profile,
+            softBreakMode: $softBreakMode,
+            roundTripMode: $roundTripMode,
+            nestedBlocksInLists: true,
+        );
+    }
+
     /**
      * Enable or disable safe mode (HtmlRenderer only)
      *

src/Parser/BlockParser.php

@@ -152,14 +152,22 @@ class BlockParser
      */
     protected bool $significantNewlines = false;
 
+    /**
+     * When true, indentation alone can introduce nested blocks inside list items
+     * without enabling global paragraph interruption.
+     */
+    protected bool $nestedBlocksInLists = false;
+
     public function __construct(
         bool $collectWarnings = false,
         bool $strictMode = false,
         bool $significantNewlines = false,
+        bool $nestedBlocksInLists = false,
     ) {
         $this->collectWarnings = $collectWarnings;
         $this->strictMode = $strictMode;
         $this->significantNewlines = $significantNewlines;
+        $this->nestedBlocksInLists = $nestedBlocksInLists || $significantNewlines;
         $this->inlineParser = new InlineParser($this);
         $this->listParser = new ListParser();
         $this->tableParser = new TableParser();
@@ -179,6 +187,9 @@ public function __construct(
     public function setSignificantNewlines(bool $value): self
     {
         $this->significantNewlines = $value;
+        if ($value) {
+            $this->nestedBlocksInLists = true;
+        }
 
         return $this;
     }
@@ -191,6 +202,24 @@ public function getSignificantNewlines(): bool
         return $this->significantNewlines;
     }
 
+    /**
+     * Enable or disable nested blocks in list items without blank lines.
+     */
+    public function setNestedBlocksInLists(bool $value): self
+    {
+        $this->nestedBlocksInLists = $value;
+
+        return $this;
+    }
+
+    /**
+     * Check if nested blocks in list items are enabled.
+     */
+    public function getNestedBlocksInLists(): bool
+    {
+        return $this->nestedBlocksInLists;
+    }
+
     /**
      * Register a custom block pattern
      *
@@ -1763,12 +1792,13 @@ protected function tryParseList(Node $parent, array $lines, int $start): ?int
 
                 // Content at content indent or more is continuation (even if it looks like a list marker)
                 // In djot, "  - b" after "- a" (no blank line) is literal text, not a nested list
-                // Unless significantNewlines is enabled, then indented block markers start nested blocks
+                // Unless nested blocks in lists are enabled, indented block markers
+                // are treated as plain continuation text here.
                 if ($nextIndent >= $contentIndent) {
-                    // Check if significantNewlines mode allows immediate nested blocks
-                    if ($this->significantNewlines) {
+                    // Check if list nesting mode allows immediate nested blocks
+                    if ($this->nestedBlocksInLists) {
                         // Check for any block starter (list, blockquote, code fence, div)
-                        if ($this->startsNewBlock($nextTrimmed) || $this->listParser->parseListItemMarker($nextTrimmed) !== null) {
+                        if ($this->isBlockElementStart($nextTrimmed)) {
                             // This is a nested block - break out to let normal nesting handle it
                             break;
                         }
@@ -1874,14 +1904,16 @@ protected function tryParseList(Node $parent, array $lines, int $start): ?int
                 $this->parseBlocks($listItem, $itemLines, 0);
             }
 
-            // In significantNewlines mode, check for immediate nested content (any block type)
-            if ($this->significantNewlines && $i < $count) {
+            // When nested blocks in lists are enabled, check for immediate
+            // nested content after the initial item paragraph.
+            if ($this->nestedBlocksInLists && $i < $count) {
                 $nextLine = $lines[$i];
                 $nextIndent = IndentationHelper::getLeadingSpaces($nextLine);
 
                 // If there's indented content that could be a nested block
                 if ($nextIndent >= $contentIndent) {
                     $subLines = [];
+                    $nestedIndent = $nextIndent;
                     while ($i < $count) {
                         $subLine = $lines[$i];
                         if (IndentationHelper::isBlankLine($subLine)) {
@@ -1892,15 +1924,24 @@ protected function tryParseList(Node $parent, array $lines, int $start): ?int
                             continue;
                         }
                         $lineIndent = IndentationHelper::getLeadingSpaces($subLine);
-                        if ($lineIndent >= $contentIndent) {
-                            $subLines[] = IndentationHelper::stripLeadingIndent($subLine, $contentIndent);
-                            $i++;
-                        } elseif ($lineIndent === $baseIndent) {
-                            // Back to parent level - check if it's a sibling item
-                            break;
-                        } else {
+                        // Membership is the item's content indent, not the first
+                        // nested line's (possibly deeper) indent: a line that drops
+                        // back to the content indent is still item content and must
+                        // be kept here, otherwise an over-indented first nested line
+                        // would detach it into a top-level block and end the list early.
+                        if ($lineIndent < $contentIndent) {
+                            // Back to the parent (or a shallower) level: this item's
+                            // nested content is done.
                             break;
                         }
+                        // Normalize the over-indented nested block by its own indent
+                        // so it starts at column 0 (required for the sub-parse to
+                        // recognize it as a block); lines that fall back to the item
+                        // content indent are stripped by that instead, keeping them
+                        // in the item rather than letting them escape.
+                        $strip = $lineIndent >= $nestedIndent ? $nestedIndent : $contentIndent;
+                        $subLines[] = IndentationHelper::stripLeadingIndent($subLine, $strip);
+                        $i++;
                     }
                     if ($subLines !== []) {
                         $this->parseBlocks($listItem, $subLines, 0);
@@ -3270,19 +3311,12 @@ protected function isBlockElementStart(string $line): bool
             return true;
         }
 
-        // List markers - these indicate a new list at this level
-        // Bullet lists: -, *, + followed by space
-        if (preg_match('/^[-*+] /', $line)) {
-            return true;
-        }
-
-        // Ordered lists: digit(s) or letter followed by . or ) and space
-        if (preg_match('/^(\d+|[a-zA-Z])[.)] /', $line)) {
-            return true;
-        }
-
-        // Task lists: - [ ] or - [x]
-        if (preg_match('/^- \[[xX ]\] /', $line)) {
+        // List markers (bullet, ordered, and task). Delegate to the canonical
+        // list-marker parser so nested-block detection recognizes every marker
+        // form it supports - including "(1)", "(a)", and roman numerals such as
+        // "iv." - instead of a narrower subset that silently degraded those into
+        // plain paragraph text.
+        if ($this->listParser->parseListItemMarker($line) !== null) {
             return true;
         }