Allow fenced comments to interrupt paragraphs (#79)

Fenced comment blocks (%%%) can now interrupt paragraphs without
requiring a preceding blank line. This makes comments truly
"invisible" from a formatting perspective.

Before this change:
```
Lorem ipsum
%%%
comment
%%%
dolor sit amet
```
Would be treated as a single paragraph with %%% as literal text.

After this change:
The above produces two separate paragraphs with the comment stripped.

This is a special case for comments since they should not affect
document formatting. Other block elements still follow the djot spec
and require blank lines to interrupt paragraphs.

Author: dereuromark

docs/syntax.md

@@ -475,6 +475,29 @@ Still inside the comment
 > **Note:** This is a djot-php extension, not part of the official Djot specification.
 > See [discussion](https://github.com/jgm/djot/issues/67) for background.
 
+Fenced comment blocks are block-level elements that break paragraph continuity.
+Unlike other block elements, fenced comments can interrupt paragraphs without
+requiring a preceding blank line - making them truly "invisible" from a formatting
+perspective:
+
+**Input:**
+```djot
+Lorem ipsum
+%%%
+comment
+%%%
+dolor sit amet
+```
+
+**Output:**
+```html
+<p>Lorem ipsum</p>
+<p>dolor sit amet</p>
+```
+
+This produces two separate paragraphs. For comments that should not interrupt
+paragraph flow (keeping text in the same paragraph), use inline comments (`{% ... %}`).
+
 ### Line Blocks
 
 Preserve line breaks using `|` at the start of each line. Useful for poetry or addresses.

src/Parser/BlockParser.php

@@ -2922,6 +2922,12 @@ protected function startsNewBlock(string $line): bool
             return true;
         }
 
+        // Fenced comments `%%%` can always interrupt paragraphs
+        // Comments should be invisible and not require extra formatting
+        if ($line[0] === '%' && isset($line[1], $line[2]) && $line[1] === '%' && $line[2] === '%') {
+            return true;
+        }
+
         // In significantNewlines mode, block elements can interrupt paragraphs
         if ($this->significantNewlines) {
             return $this->startsNewBlockSignificant($line);
@@ -2973,6 +2979,9 @@ protected function startsNewBlockSignificant(string $line): bool
             case ':':
                 // Fenced divs: :{3,}
                 return isset($line[1], $line[2]) && $line[1] === ':' && $line[2] === ':';
+            case '%':
+                // Fenced comments: %{3,}
+                return isset($line[1], $line[2]) && $line[1] === '%' && $line[2] === '%';
             default:
                 // Only 1. or 1) can interrupt paragraphs (CommonMark rule)
                 // Prevents "1985. That year..." from becoming a list

tests/TestCase/DjotConverterTest.php

@@ -683,6 +683,51 @@ public function testFencedCommentClosingNeedsMatchingLength(): void
         $this->assertStringNotContainsString('still', $result);
     }
 
+    public function testFencedCommentBreaksParagraphContinuity(): void
+    {
+        // Fenced comments are block-level elements that break paragraph continuity
+        // Text before and after becomes two separate paragraphs
+        $djot = "Lorem ipsum\n\n%%%\ncomment\n%%%\n\ndolor sit amet";
+
+        $result = $this->converter->convert($djot);
+
+        // Should produce two separate paragraphs
+        $this->assertStringContainsString('<p>Lorem ipsum</p>', $result);
+        $this->assertStringContainsString('<p>dolor sit amet</p>', $result);
+        $this->assertStringNotContainsString('comment', $result);
+
+        // Should NOT be a single paragraph
+        $this->assertStringNotContainsString('Lorem ipsum dolor', $result);
+    }
+
+    public function testFencedCommentInterruptsParagraph(): void
+    {
+        // Fenced comments can interrupt paragraphs without requiring blank lines
+        // This makes comments truly "invisible" from a formatting perspective
+        $djot = "Lorem ipsum\n%%%\ncomment\n%%%\ndolor sit amet";
+
+        $result = $this->converter->convert($djot);
+
+        // Should produce two separate paragraphs with comment stripped
+        $this->assertStringContainsString('<p>Lorem ipsum</p>', $result);
+        $this->assertStringContainsString('<p>dolor sit amet</p>', $result);
+        $this->assertStringNotContainsString('comment', $result);
+        $this->assertStringNotContainsString('%%%', $result);
+    }
+
+    public function testFencedCommentWithBlankLinesAlsoWorks(): void
+    {
+        // Also works with blank lines (traditional block element style)
+        $djot = "Lorem ipsum\n\n%%%\ncomment\n%%%\n\ndolor sit amet";
+
+        $result = $this->converter->convert($djot);
+
+        // Comment should be recognized and stripped
+        $this->assertStringContainsString('<p>Lorem ipsum</p>', $result);
+        $this->assertStringContainsString('<p>dolor sit amet</p>', $result);
+        $this->assertStringNotContainsString('comment', $result);
+    }
+
     // Edge cases from official Djot test suite
 
     public function testEmphasisIntraword(): void