[2.x] Normalize Markdown heading identifiers

packages/framework/src/Framework/Actions/GeneratesTableOfContents.php

@@ -6,7 +6,7 @@
 
 use Hyde\Facades\Config;
 use Hyde\Markdown\Models\Markdown;
-use Illuminate\Support\Str;
+use Hyde\Markdown\Processing\HeadingRenderer;
 
 /**
  * Generates a nested table of contents from Markdown headings.
@@ -117,7 +117,7 @@ protected function createHeadingEntry(array $headingData): array
         return [
             'level' => $headingData['level'],
             'title' => $headingData['title'],
-            'slug' => Str::slug($headingData['title']),
+            'slug' => HeadingRenderer::makeIdentifier($headingData['title']),
         ];
     }
 

packages/framework/src/Markdown/Processing/HeadingRenderer.php

@@ -71,7 +71,7 @@ public function postProcess(string $html): string
 
     protected function makeHeadingId(string $contents): string
     {
-        $identifier = $this->ensureIdentifierIsUnique(Str::slug($contents));
+        $identifier = $this->ensureIdentifierIsUnique(static::makeIdentifier($contents));
 
         $this->headingRegistry[] = $identifier;
 
@@ -89,4 +89,10 @@ protected function ensureIdentifierIsUnique(string $slug): string
 
         return $identifier;
     }
+
+    /** @internal */
+    public static function makeIdentifier(string $title): string
+    {
+        return e(Str::slug(Str::transliterate(html_entity_decode($title)), dictionary: ['@' => 'at', '&' => 'and', '<' => '', '>' => '']));
+    }
 }

packages/framework/tests/Feature/MarkdownHeadingRendererTest.php

@@ -183,9 +183,8 @@ public function testHeadingsWithSpecialCharacters()
         $this->assertStringContainsString('Heading with & special < > "characters"', $html);
         $this->assertStringContainsString('Heading with émojis 🎉', $html);
 
-        // Todo: Try to normalize to heading-with-special-characters?
         $this->assertSame(<<<'HTML'
-        <h2 id="heading-with-amp-special-lt-gt-quotcharactersquot" class="group w-fit scroll-mt-2">Heading with &amp; special &lt; &gt; &quot;characters&quot;<a href="#heading-with-amp-special-lt-gt-quotcharactersquot" class="heading-permalink opacity-0 ml-1 transition-opacity duration-300 ease-linear px-1 group-hover:opacity-100 focus:opacity-100 group-hover:grayscale-0 focus:grayscale-0" title="Permalink">#</a></h2>
+        <h2 id="heading-with-and-special-characters" class="group w-fit scroll-mt-2">Heading with &amp; special &lt; &gt; &quot;characters&quot;<a href="#heading-with-and-special-characters" class="heading-permalink opacity-0 ml-1 transition-opacity duration-300 ease-linear px-1 group-hover:opacity-100 focus:opacity-100 group-hover:grayscale-0 focus:grayscale-0" title="Permalink">#</a></h2>
         <h3 id="heading-with-emojis" class="group w-fit scroll-mt-2">Heading with émojis 🎉<a href="#heading-with-emojis" class="heading-permalink opacity-0 ml-1 transition-opacity duration-300 ease-linear px-1 group-hover:opacity-100 focus:opacity-100 group-hover:grayscale-0 focus:grayscale-0" title="Permalink">#</a></h3>
 
         HTML, $html);

packages/framework/tests/Unit/HeadingRendererUnitTest.php

@@ -25,6 +25,7 @@ class HeadingRendererUnitTest extends UnitTestCase
     use UsesRealBladeInUnitTests;
 
     protected static bool $needsConfig = true;
+    protected static bool $needsKernel = true;
     protected static ?array $cachedConfig = null;
 
     protected function setUp(): void
@@ -233,6 +234,23 @@ public function testPostProcessHandlesNoHeadingTags()
         $this->assertSame('<p>Paragraph</p>', (new HeadingRenderer())->postProcess($html));
     }
 
+    /**
+     * @dataProvider headingIdentifierProvider
+     */
+    public function testHeadingIdentifierGeneration($input, $expected)
+    {
+        $this->assertSame($expected, HeadingRenderer::makeIdentifier($input));
+    }
+
+    /**
+     * @dataProvider headingIdentifierProvider
+     */
+    public function testHeadingIdentifierGenerationWithEscapedInput($input, $expected)
+    {
+        $this->assertSame(HeadingRenderer::makeIdentifier($input), HeadingRenderer::makeIdentifier(e($input)));
+        $this->assertSame($expected, HeadingRenderer::makeIdentifier(e($input)));
+    }
+
     protected function mockChildNodeRenderer(string $contents = 'Test Heading'): ChildNodeRendererInterface
     {
         $childRenderer = Mockery::mock(ChildNodeRendererInterface::class);
@@ -255,4 +273,44 @@ protected function validateHeadingPermalinkStates(HeadingRenderer $renderer, Chi
             }
         }
     }
+
+    public static function headingIdentifierProvider(): array
+    {
+        return [
+            // Basic cases
+            ['Hello World', 'hello-world'],
+            ['Simple Heading', 'simple-heading'],
+            ['Heading With Numbers 123', 'heading-with-numbers-123'],
+
+            // Special characters
+            ['Heading with & symbol', 'heading-with-and-symbol'],
+            ['Heading with < > symbols', 'heading-with-symbols'],
+            ['Heading with "quotes"', 'heading-with-quotes'],
+            ['Heading with / and \\', 'heading-with-and'],
+            ['Heading with punctuation!?!', 'heading-with-punctuation'],
+            ['Hyphenated-heading-name', 'hyphenated-heading-name'],
+
+            // Emojis
+            ['Heading with emoji 🎉', 'heading-with-emoji'],
+            ['Another emoji 🤔 test', 'another-emoji-test'],
+            ['Multiple emojis 🎉🤔✨', 'multiple-emojis'],
+
+            // Accented and non-ASCII characters
+            ['Accented é character', 'accented-e-character'],
+            ['Café Crème', 'cafe-creme'],
+            ['Łódź and święto', 'lodz-and-swieto'],
+            ['中文标题', 'zhong-wen-biao-ti'],
+            ['日本語の見出し', 'ri-ben-yu-nojian-chu-shi'],
+            ['한국어 제목', 'hangugeo-jemog'],
+
+            // Edge cases
+            ['    Leading spaces', 'leading-spaces'],
+            ['Trailing spaces    ', 'trailing-spaces'],
+            ['  Surrounded by spaces  ', 'surrounded-by-spaces'],
+            ['----', ''],
+            ['%%%%%%%', ''],
+            ['    ', ''],
+            ['1234567890', '1234567890'],
+        ];
+    }
 }