fix(markdown): avoid leading number in link hash (#1644)

Author: CritasWang

e2e/docs/router/navigate-by-link.md

@@ -13,8 +13,8 @@
 <a :href="$withBase('/404.html')" class="not-found">404</a>
 <a :href="$withBase('/?home=true')" class="home-with-query">Home</a>
 <a :href="$withBase('/?home=true#home')" class="home-with-query-and-hash">Home</a>
-<a :href="$withBase('/404.html#404')" class="not-found-with-hash">404</a>
-<a :href="$withBase('/404.html#404?notFound=true')" class="not-found-with-hash-and-query">404</a>
+<a :href="$withBase('/404.html#_404')" class="not-found-with-hash">404</a>
+<a :href="$withBase('/404.html#_404?notFound=true')" class="not-found-with-hash-and-query">404</a>
 
 ## Markdown Links with html paths
 

e2e/docs/router/navigate-by-router.md

@@ -28,10 +28,10 @@ const goHomeWithQueryAndHash = () => {
 }
 
 const go404WithHash = () => {
-  router.push('/404.html#404');
+  router.push('/404.html#_404');
 }
 
 const go404WithHashAndQuery = () => {
-  router.push('/404.html#404?notFound=true');
+  router.push('/404.html#_404?notFound=true');
 }
 </script>

e2e/tests/router/navigate-by-link.spec.ts

@@ -32,13 +32,13 @@ test.describe('markdown links', () => {
 
   test('should preserve hash', async ({ page }) => {
     await page.locator('#markdown-links + ul > li > a').nth(4).click()
-    await expect(page).toHaveURL(`${BASE}404.html#404`)
+    await expect(page).toHaveURL(`${BASE}404.html#_404`)
     await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
   })
 
   test('should preserve hash and query', async ({ page }) => {
     await page.locator('#markdown-links + ul > li > a').nth(5).click()
-    await expect(page).toHaveURL(`${BASE}404.html#404?notFound=true`)
+    await expect(page).toHaveURL(`${BASE}404.html#_404?notFound=true`)
     await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
   })
 })
@@ -70,13 +70,13 @@ test.describe('html links', () => {
 
   test('should preserve hash', async ({ page }) => {
     await page.locator('#html-links + p > a').nth(4).click()
-    await expect(page).toHaveURL(`${BASE}404.html#404`)
+    await expect(page).toHaveURL(`${BASE}404.html#_404`)
     await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
   })
 
   test('should preserve hash and query', async ({ page }) => {
     await page.locator('#html-links + p > a').nth(5).click()
-    await expect(page).toHaveURL(`${BASE}404.html#404?notFound=true`)
+    await expect(page).toHaveURL(`${BASE}404.html#_404?notFound=true`)
     await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
   })
 })

e2e/tests/router/navigate-by-router.spec.ts

@@ -31,12 +31,12 @@ test('should preserve query and hash', async ({ page }) => {
 
 test('should preserve hash', async ({ page }) => {
   await page.locator('#not-found-with-hash').click()
-  await expect(page).toHaveURL(`${BASE}404.html#404`)
+  await expect(page).toHaveURL(`${BASE}404.html#_404`)
   await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
 })
 
 test('should preserve hash and query', async ({ page }) => {
   await page.locator('#not-found-with-hash-and-query').click()
-  await expect(page).toHaveURL(`${BASE}404.html#404?notFound=true`)
+  await expect(page).toHaveURL(`${BASE}404.html#_404?notFound=true`)
   await expect(page.locator('#notfound-h2')).toHaveText('NotFound H2')
 })

packages/markdown/src/plugins/linksPlugin/linksPlugin.ts

@@ -106,7 +106,14 @@ export const linksPlugin: PluginWithOptions<LinksPluginOptions> = (
 
     // notice that the path and hash are encoded by markdown-it
     const rawPath = internalLinkMatch[1]
-    const rawHashAndQueries = internalLinkMatch[2] || ''
+
+    // The default slugification function processes anchor links (hash fragments)
+    // If an anchor starts with a number (e.g., #123), it is replaced with #_number (e.g., #_123)
+    // This rule is designed to prevent potential URL conflicts, though manually written anchors like #123 are rare in Markdown—hence the special handling.
+    const rawHashAndQueries = (internalLinkMatch[2] || '').replace(
+      /^#(\d)/,
+      '#_$1',
+    )
 
     // resolve relative and absolute path
     const { relativePath, absolutePath } = resolvePaths(