From f7d6dde7dc0ec461abb2529f72f2446eb6b87c5d Mon Sep 17 00:00:00 2001
From: Nicholas Ruffing <nicholasruffing70@gmail.com>
Date: Tue, 12 Dec 2023 11:00:16 -0500
Subject: [PATCH] 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             |  5 ++++
 e2e/tests/markdown/anchors.cy.ts         | 26 ++++++++++++++++++++
 packages/markdown/src/markdown.ts        |  7 +++---
 packages/markdown/tests/markdown.spec.ts | 31 +++++++++++++-----------
 4 files changed, 51 insertions(+), 18 deletions(-)
 create mode 100644 e2e/docs/markdown/anchors.md
 create mode 100644 e2e/tests/markdown/anchors.cy.ts

diff --git a/e2e/docs/markdown/anchors.md b/e2e/docs/markdown/anchors.md
new file mode 100644
index 0000000000..9769c8936f
--- /dev/null
+++ b/e2e/docs/markdown/anchors.md
@@ -0,0 +1,5 @@
+# title
+
+## anchor 1
+
+### anchor 1-1
diff --git a/e2e/tests/markdown/anchors.cy.ts b/e2e/tests/markdown/anchors.cy.ts
new file mode 100644
index 0000000000..d9f7fc934a
--- /dev/null
+++ b/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')
+    })
+  })
+})
diff --git a/packages/markdown/src/markdown.ts b/packages/markdown/src/markdown.ts
index 715c30cea7..abe1235235 100644
--- a/packages/markdown/src/markdown.ts
+++ b/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,
     })
diff --git a/packages/markdown/tests/markdown.spec.ts b/packages/markdown/tests/markdown.spec.ts
index 674b47c447..ec5ddfffbe 100644
--- a/packages/markdown/tests/markdown.spec.ts
+++ b/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')
   })
 })