feat(markdown): update default anchor permalink function (close #1363) (

#1452)

 BREAKING CHANGE: the default permalink function of markdown-it-anchor has been changed from `ariaHidden` to `headerLink` for better accessibility, which would be a potential breaking change for theme authors

---------

Co-authored-by: Xinyu Liu <meteor.lxy@foxmail.com>

e2e/docs/markdown/anchors.md

@@ -0,0 +1,5 @@
+# title
+
+## anchor 1
+
+### anchor 1-1

e2e/tests/markdown/anchors.cy.ts

@@ -0,0 +1,26 @@
+describe('markdown > anchors', () => {
+  it('should render anchors and navigate correctly', () => {
+    cy.visit('/markdown/anchors.html')
+
+    cy.get('.e2e-theme-content h1')
+      .should('have.attr', 'id', 'title')
+      .should('have.attr', 'tabindex', '-1')
+
+    cy.get('.e2e-theme-content h1 > a')
+      .should('have.attr', 'class', 'header-anchor')
+      .should('have.attr', 'href', '#title')
+      .click()
+
+    cy.location().should((location) => {
+      expect(location.hash).to.eq('#title')
+    })
+
+    cy.get('#anchor-1-1 > a')
+      .should('have.attr', 'class', 'header-anchor')
+      .click()
+
+    cy.location().should((location) => {
+      expect(location.hash).to.eq('#anchor-1-1')
+    })
+  })
+})

packages/markdown/src/markdown.ts

@@ -63,11 +63,10 @@ export const createMarkdown = ({
     md.use<AnchorPluginOptions>(anchorPlugin, {
       level: [1, 2, 3, 4, 5, 6],
       slugify,
-      permalink: anchorPlugin.permalink.ariaHidden({
+      permalink: anchorPlugin.permalink.headerLink({
         class: 'header-anchor',
-        symbol: '#',
-        space: true,
-        placement: 'before',
+        // Add a span inside the link so Safari shows headings in reader view.
+        safariReaderFix: true,
       }),
       ...anchor,
     })

packages/markdown/tests/markdown.spec.ts

@@ -2,22 +2,25 @@ import { describe, expect, it } from 'vitest'
 import { createMarkdown } from '../src/index.js'
 
 describe('@vuepress/markdown > markdown', () => {
-  describe('options', () => {
-    it.todo('anchor')
+  const md = createMarkdown()
 
-    it.todo('emoji')
-
-    it.todo('links')
+  it('should render anchors', () => {
+    const rendered = md.render(`\
+# h1
+## h2
+### h3
+`)
+    expect(rendered).toEqual(
+      [
+        '<h1 id="h1" tabindex="-1"><a class="header-anchor" href="#h1"><span>h1</span></a></h1>',
+        '<h2 id="h2" tabindex="-1"><a class="header-anchor" href="#h2"><span>h2</span></a></h2>',
+        '<h3 id="h3" tabindex="-1"><a class="header-anchor" href="#h3"><span>h3</span></a></h3>',
+      ].join('\n') + '\n',
+    )
   })
 
-  describe('e2e', () => {
-    const md = createMarkdown()
-
-    it.todo('anchor')
-
-    it('should parse emoji', () => {
-      const rendered = md.render(':smile:')
-      expect(rendered).toBe('<p>😄</p>\n')
-    })
+  it('should parse emoji', () => {
+    const rendered = md.render(':smile:')
+    expect(rendered).toBe('<p>😄</p>\n')
   })
 })