feat: make generated heading ids optional

src/Rules/HeadingRule.php

@@ -12,6 +12,14 @@ final class HeadingRule implements Rule, ProvidesFirstChar
 {
     public string $firstChar = '#';
 
+    public function __construct(
+        /**
+         * Whether a heading without an explicit id gets one slugged from its
+         * content. An id written as `## Title ## id` is kept either way.
+         */
+        public bool $generateIds = true,
+    ) {}
+
     public function shouldParse(Parser $parser): bool
     {
         return $parser->comesNext('#', 1);
@@ -37,14 +45,16 @@ public function parse(Parser $parser): Token
                 |> trim(...);
             $buffer = substr(string: $buffer, offset: 0, length: $idSeparator)
                 |> trim(...);
-        } else {
+        } elseif ($this->generateIds) {
             // No id is specified, we'll slug the heading
             $id = $buffer
                 |> mb_strtolower(...)
                 |> (fn (string $x) => trim(
                     preg_replace('/[^\p{L}\p{N}]+/u', '-', $x) ?? '',
                     '-',
                 ));
+        } else {
+            $id = null;
         }
 
         return new HeadingToken(

tests/Rules/HeadingRuleTest.php

@@ -80,4 +80,35 @@ public function test_slug_cannot_break_out_of_the_id_attribute(): void
             $html,
         );
     }
+
+    #[Test]
+    public function lex_generates_an_id_by_default(): void
+    {
+        $html =
+            (string) new Parser(highlighter: null, rules: [new HeadingRule()])->parse(
+                '## A heading',
+            );
+
+        $this->assertSame('<h2 id="a-heading">A heading</h2>', $html);
+    }
+
+    #[Test]
+    public function lex_without_generated_ids(): void
+    {
+        $html = (string) new Parser(highlighter: null, rules: [
+            new HeadingRule(generateIds: false),
+        ])->parse('## A heading');
+
+        $this->assertSame('<h2>A heading</h2>', $html);
+    }
+
+    #[Test]
+    public function lex_keeps_an_explicit_id_without_generated_ids(): void
+    {
+        $html = (string) new Parser(highlighter: null, rules: [
+            new HeadingRule(generateIds: false),
+        ])->parse('## A heading ## custom-id');
+
+        $this->assertSame('<h2 id="custom-id">A heading</h2>', $html);
+    }
 }