\n```\n\ndocs/AComponent.vue\n\n```vue\n\u003Ctemplate>\n \u003Ch2 id=\"bar\">bar\u003C/h2>\n \u003Ch2 id=\"baz\">baz\u003C/h2>\n\u003C/template>\n```\n\nResult: `## bar` and `## baz` appear in the outline and are linkable, but they have no header‑anchor element, so users cannot easily copy a permalink, and the UI feels a bit inconsistent when hovering the mouse over headings added by the component and the ones written in Markdown.\n\n\n### Describe the solution you'd like\n\nDuring the same client‑side pass that builds the outline, scan for any `\u003Ch1‑h6>` with an `id` but lacking `.header-anchor`, and inject an anchor with the same markup VitePress generates for Markdown headings.\n\n\n### Describe alternatives you've considered\n\nManually adding the anchor works...\n\n```html\n\u003Ch2 id=\"qux\">\n qux\n \u003Ca class=\"header-anchor\" href=\"#qux\" aria-label='Permalink to \"qux {#qux}\"'>​\u003C/a>\n\u003C/h2>\n```\n\n...but is somewhat boilerplate and is brittle. It must be manually added to each place where `\u003Ch1‑h6>` is used and will break if the theme changes.\n\n### Additional context\n\nScreencast of how the repro example looks:\n\n\nhttps://github.com/user-attachments/assets/28deb3dc-47d4-4c16-9d30-f491cfb58fda\n\n\n### Validations\n\n- [x] Follow our [Code of Conduct](https://vuejs.org/about/coc.html)\n- [x] Read the [docs](https://vitepress.dev).\n- [x] Read the [Contributing Guidelines](https://github.com/vuejs/vitepress/blob/main/.github/contributing.md).\n- [x] Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.",[],4867,"vuejs","vitepress","open","Auto‑insert `\u003Ca.header‑anchor>` for headings rendered by Vue components","2025-07-30T19:09:15Z","https://github.com/vuejs/vitepress/issues/4867",0.69704413,{"description":3154,"labels":3155,"number":3165,"owner":3146,"repository":3147,"state":3148,"title":3166,"updated_at":3167,"url":3168,"score":3169},"### Describe the bug\r\n\r\nWhen setting:\r\n\r\n```ts\r\n markdown: {\r\n anchor: {\r\n permalink: undefined\r\n }\r\n },\r\n```\r\n\r\nThe permalinks on header elements are successfully hidden, but that also disables the scroll-tracking for the \"On This Page\" outline sidebar as well.\r\n\r\n### Reproduction\r\n\r\nI was able to reproduce this on the boilerplate project by applying the setting above to the config.\r\n\r\n### Expected behavior\r\n\r\nPermalink symbols correctly hidden, outline continues to function.\r\n\r\n### System Info\r\n\r\n```Text\r\nMacOS Ventura\r\nVitepress@latest\r\nNode v18\r\n\r\n(envinfo hangs on an M2)\r\n```\r\n\r\n\r\n### Additional context\r\n\r\n_No response_\r\n\r\n### Validations\r\n\r\n- [X] Check if you're on the [latest VitePress version](https://github.com/vuejs/vitepress/releases/latest).\r\n- [X] Follow our [Code of Conduct](https://vuejs.org/about/coc.html)\r\n- [X] Read the [docs](https://vitepress.dev).\r\n- [X] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.",[3156,3159,3162],{"name":3157,"color":3158},"theme","0754FB",{"name":3160,"color":3161},"has-workaround","1B4515",{"name":3163,"color":3164},"stale","ededed",3030,"`permalink: undefined` in `mardown` settings disables Outline","2023-11-06T14:43:56Z","https://github.com/vuejs/vitepress/issues/3030",0.71300095,{"description":3171,"labels":3172,"number":3175,"owner":3146,"repository":3147,"state":3148,"title":3176,"updated_at":3177,"url":3178,"score":3179},"### Describe the bug\r\n\r\nWhen navigating the page with the outline, the outline marker does not move to the correct item when the target header is close to the end of the page but not the last item.\r\n\r\n### Reproduction\r\n\r\nVisit https://vitepress.dev/reference/runtime-api and try to click on \"$frontmatter\" in the right-side outline.\r\n\r\n### Expected behavior\r\n\r\nThe outline marker moves next to \"$frontmatter\" instead of \"$params\".\r\n\r\n### System Info\r\n\r\n```Text\r\nA browser with a minimum size of 1280px x 974px (width x height)\r\n```\r\n\r\n\r\n### Additional context\r\n\r\n_No response_\r\n\r\n### Validations\r\n\r\n- [X] Check if you're on the [latest VitePress version](https://github.com/vuejs/vitepress/releases/latest).\r\n- [X] Follow our [Code of Conduct](https://vuejs.org/about/coc.html)\r\n- [X] Read the [docs](https://vitepress.dev).\r\n- [X] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.",[3173,3174],{"name":3157,"color":3158},{"name":3163,"color":3164},3878,"Outline marker does not move to correct item","2024-09-01T14:03:31Z","https://github.com/vuejs/vitepress/issues/3878",0.72027826,{"description":3181,"labels":3182,"number":3187,"owner":3146,"repository":3147,"state":3148,"title":3188,"updated_at":3189,"url":3190,"score":3191},"### Describe the bug\r\n\r\nNavbar representation is inconsistent between components, hovering them, they produce three different reactions\r\n\r\n\r\n\r\nHovering a nav menu link, produces fade to brand color (with no underline for accessibility)\r\n\r\n\r\n\r\nHovering socialLinks components produces more contrast, but it's an outgoing link. \r\n\r\n\r\n\r\nHovering the title, produce a less contrast. Again, here it's a link should have brand color and underline for accessibility. Lower contrast is not WCAG Level 2 compliant. It happens also for dropdown menu anchors.\r\n\r\n### Reproduction\r\n\r\nBuild basic website having this attributes\r\n\r\n```typescript\r\n socialLinks: [\r\n { icon: 'github', link: 'https://github.com/'},\r\n ],\r\n nav: [\r\n {\r\n text: 'dropdown menu',\r\n items: [\r\n {\r\n text: 'one', \r\n link: 'https://bing.it/',\r\n target: '_blank',\r\n },{ \r\n text: 'two',\r\n link: 'https://google.it/',\r\n },\r\n ]\r\n },\r\n { \r\n text: 'internal link', \r\n link: 'mypage',\r\n },\r\n ],\r\n```\r\n\r\n### Expected behavior\r\n\r\nI expect every link turning into brand color, with no accessibility issues, no matter the component is.\r\n\r\n### System Info\r\n\r\n```shell\r\nSystem:\r\n OS: Linux 5.10 Ubuntu 22.04.2 LTS 22.04.2 LTS (Jammy Jellyfish)\r\n CPU: (8) x64 Intel(R) Core(TM) i5-10210U CPU @ 1.60GHz\r\n Memory: 11.40 GB / 12.31 GB\r\n Container: Yes\r\n Shell: 5.1.16 - /bin/bash\r\n Binaries:\r\n Node: 16.15.1 - ~/.nvm/versions/node/v16.15.1/bin/node\r\n Yarn: 1.22.19 - ~/.nvm/versions/node/v16.15.1/bin/yarn\r\n npm: 8.19.2 - ~/.nvm/versions/node/v16.15.1/bin/npm\r\n npmPackages:\r\n vitepress: ^1.0.0-alpha.56 => 1.0.0-alpha.56\r\n```\r\n\r\n\r\n### Additional context\r\n\r\n_No response_\r\n\r\n### Validations\r\n\r\n- [X] Follow our [Code of Conduct](https://vuejs.org/about/coc.html)\r\n- [X] Read the [docs](https://vitepress.dev).\r\n- [X] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.",[3183,3186],{"name":3184,"color":3185},"a11y","fbca04",{"name":3163,"color":3164},2085,"navbar inconsistent behaviour ","2023-08-03T10:18:01Z","https://github.com/vuejs/vitepress/issues/2085",0.724023,{"description":3193,"labels":3194,"number":3197,"owner":3146,"repository":3147,"state":3148,"title":3198,"updated_at":3199,"url":3200,"score":3201},"### Describe the bug\n\nWe should add an aria-label to the headings. Currently with aria-label not specified, VoiceOver returns `heading level 1, 2 items What is VitePress, visited, link, Permalink to \"What is VitePress?\"`, which is very unclear and verbose.\n\n### Reproduction\n\nJust head to https://vitepress.dev/guide/what-is-vitepress on Mac, open VoiceOver and click on any heading.\n\n### Expected behavior\n\nAn aria-label should be added to heading elements. Take the `# What is VitePress?` as an example, it should be rendered as:\r\n```\r\n\u003Ch1 id=\"what-is-vitepress\" tabindex=\"-1\" aria-label=\"What is VitePress?\">\r\n \u003Ca class=\"header-anchor\" href=\"#what-is-vitepress\" aria-hidden=\"true\">\r\n ​\r\n \u003C/a>\r\n What is VitePress? \r\n\u003C/h1>\r\n```\r\n Then VoiceOver returns `Heading level 1, What is VitePress?`.\n\n### System Info\n\n```Text\nSystem:\r\n OS: macOS 14.0\r\n CPU: (10) arm64 Apple M1 Pro\r\n Memory: 98.42 MB / 16.00 GB\r\n Shell: 5.9 - /bin/zsh\r\n Binaries:\r\n Node: 19.7.0 - ~/.nvm/versions/node/v19.7.0/bin/node\r\n Yarn: 1.22.19 - ~/.nvm/versions/node/v19.7.0/bin/yarn\r\n npm: 9.5.0 - ~/.nvm/versions/node/v19.7.0/bin/npm\r\n pnpm: 8.6.0 - ~/.nvm/versions/node/v19.7.0/bin/pnpm\r\n Browsers:\r\n Chrome: 116.0.5845.187\r\n Safari: 17.0\n```\n\n\n### Additional context\n\nI am willing to fix this bug by myself. However as I'm not familiar with MarkdownIt, I think I need some help on where to customize the rendering rules of headers.\n\n### Validations\n\n- [X] Check if you're on the [latest VitePress version](https://github.com/vuejs/vitepress/releases/latest).\n- [X] Follow our [Code of Conduct](https://vuejs.org/about/coc.html)\n- [X] Read the [docs](https://vitepress.dev).\n- [X] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.",[3195,3196],{"name":3184,"color":3185},{"name":3163,"color":3164},2980,"a11y: Headings are read verbosely by VoiceOver","2023-10-19T13:04:19Z","https://github.com/vuejs/vitepress/issues/2980",0.7356236,{"description":3203,"labels":3204,"number":3206,"owner":3146,"repository":3147,"state":3207,"title":3208,"updated_at":3209,"url":3210,"score":3211},"### Describe the bug\r\n\r\nThe header anchors are not accessible to screen reader users.\r\n\r\n```html\r\n\u003Ch1 id=\"what-is-vitepress\" tabindex=\"-1\">\r\n What is VitePress?\r\n \u003Ca class=\"header-anchor\" href=\"#what-is-vitepress\" aria-hidden=\"true\">#\u003C/a>\r\n\u003C/h1>\r\n```\r\n\r\nSetting `aria-hidden` on focusable elements (that are not hidden from **all** users) fails test \"[aria-hidden elements do not contain focusable elements](https://dequeuniversity.com/rules/axe/4.4/aria-hidden-focus?utm_source=lighthouse&utm_medium=devtools)\".\r\n\r\nI'm preparing a PR to fix this issue.\r\n\r\n### Reproduction\r\n\r\nNo special configuration necessary. Header anchors are enabled by default.\r\n\r\nThis issue can be tested on the official [VitePress](https://vitepress.vuejs.org/guide/what-is-vitepress) site or any other basic vitepress deployment using the default-theme.\r\n\r\n### Expected behavior\r\n\r\nProvide an accessible default configuration for `markdown-it-anchor` and update styling of header-anchors accordingly.\r\n\r\nA possible solution could look like this:\r\n\r\n```html\r\n\u003Cdiv class=\"header-wrapper\">\r\n \u003Ch1 id=\"what-is-vitepress\" tabindex=\"-1\">What is VitePress?\u003C/h1>\r\n \u003Ca class=\"header-anchor\" href=\"#what-is-vitepress\" aria-label=\"Permalink to \"What is VitePress?\"\">#\u003C/a>\r\n\u003C/div>\r\n```\r\n\r\nA viable `markdown-it-anchor` configuration could look like this.\r\n```js\r\n{\r\n anchor: {\r\n permalink: MdItAnchor.permalink.linkAfterHeader({\r\n style: \"aria-label\",\r\n assistiveText: (title) => `Permalink to \"${title}\"`,\r\n visuallyHiddenClass: \"visually-hidden\",\r\n wrapper: ['\u003Cdiv class=\"header-wrapper\">', \"\u003C/div>\"],\r\n }),\r\n },\r\n}\r\n```\r\n\r\nAdditionally, some updates for anchor styling are necessary too.\r\n```css\r\n.vp-doc .header-wrapper {\r\n position: relative;\r\n}\r\n\r\n.vp-doc .header-wrapper .header-anchor {\r\n line-height: 32px;\r\n position: absolute;\r\n top: 0;\r\n}\r\n\r\n.vp-doc .header-wrapper h1 + .header-anchor {\r\n line-height: 40px;\r\n font-size: 32px;\r\n}\r\n\r\n.vp-doc .header-wrapper h2 + .header-anchor {\r\n padding-top: 25px;\r\n line-height: 32px;\r\n font-size: 24px;\r\n}\r\n\r\n.vp-doc .header-wrapper h3 + .header-anchor {\r\n line-height: 28px;\r\n font-size: 20px;\r\n}\r\n\r\n.vp-doc .header-anchor:hover,\r\n.vp-doc .header-anchor:focus,\r\n.vp-doc h1:hover + .header-anchor,\r\n.vp-doc h2:hover + .header-anchor,\r\n.vp-doc h3:hover + .header-anchor,\r\n.vp-doc h4:hover + .header-anchor,\r\n.vp-doc h5:hover + .header-anchor,\r\n.vp-doc h6:hover + .header-anchor {\r\n opacity: 1;\r\n}\r\n```\r\n\r\n### System Info\r\n\r\n```shell\r\nSystem:\r\n OS: Linux 5.15 Ubuntu 20.04.5 LTS (Focal Fossa)\r\n CPU: (8) x64 Intel(R) Xeon(R) CPU E3-1505M v5 @ 2.80GHz\r\n Memory: 19.26 GB / 31.13 GB\r\n Container: Yes\r\n Shell: 5.0.17 - /bin/bash\r\nBinaries:\r\n Node: 18.14.0 - ~/.nvm/versions/node/v18.14.0/bin/node\r\n Yarn: 1.22.19 - ~/.nvm/versions/node/v18.14.0/bin/yarn\r\n npm: 9.3.1 - ~/.nvm/versions/node/v18.14.0/bin/npm\r\nBrowsers:\r\n Chrome: 110.0.5481.177\r\n Chromium: 110.0.5481.100\r\n Firefox: 110.0.1\r\n```\r\n\r\n\r\n### Additional context\r\n\r\nMore details about test \"aria-hidden elements do not contain focusable elements\" can be found at [https://dequeuniversity.com/rules/axe/4.4/aria-hidden-focus](https://dequeuniversity.com/rules/axe/4.4/aria-hidden-focus).\r\n\r\n### Validations\r\n\r\n- [X] Follow our [Code of Conduct](https://vuejs.org/about/coc.html)\r\n- [X] Read the [docs](https://vitepress.vuejs.org).\r\n- [X] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.",[3205],{"name":3157,"color":3158},2039,"closed","Header anchors not accessible to screen reader users.","2023-03-22T00:03:24Z","https://github.com/vuejs/vitepress/issues/2039",0.68828833,{"description":3213,"labels":3214,"number":3218,"owner":3146,"repository":3147,"state":3207,"title":3219,"updated_at":3220,"url":3221,"score":3222},"### Describe the bug\n\nWhen I click on an item above the currently active item in the outline, the marker first appears above the target item, and then appears in the correct place. Is this intentional?\r\n\r\nhttps://github.com/vuejs/vitepress/assets/84114146/77ad4b5a-dc13-4acd-8704-f261124594f9\n\n### Reproduction\n\nThe VitePress official website exhibits the same phenomenon. \r\n\n\n### Expected behavior\n\nThe marker appears in the correct place at the first time\n\n### System Info\n\n```sh\nSystem:\r\n OS: Windows 10 10.0.22621\r\n CPU: (16) x64 AMD Ryzen 7 5800H with Radeon Graphics\r\n Memory: 3.84 GB / 14.85 GB\r\n Binaries:\r\n Node: 16.19.1 - D:\\Environment\\nodejs\\node.EXE\r\n Yarn: 1.22.19 - D:\\Environment\\nodejs\\yarn.CMD\r\n npm: 8.19.3 - D:\\Environment\\nodejs\\npm.CMD\r\n pnpm: 8.6.5 - D:\\Environment\\nodejs\\pnpm.CMD\r\n Browsers:\r\n Edge: Spartan (44.22621.1992.0), Chromium (115.0.1901.183)\r\n Internet Explorer: 11.0.22621.1\r\n npmPackages:\r\n vitepress: 1.0.0-beta.7 => 1.0.0-beta.7\n```\n\n\n### Additional context\n\nChanging \"throttleAndDebounce\" in the [outline.js](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/composables/outline.ts) to a simple debounce function can solve this issue.\n\n### Validations\n\n- [X] Check if you're on the [latest VitePress version](https://github.com/vuejs/vitepress/releases/latest).\n- [X] Follow our [Code of Conduct](https://vuejs.org/about/coc.html)\n- [X] Read the [docs](https://vitepress.dev).\n- [X] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.",[3215],{"name":3216,"color":3217},"bug: pending triage","e99695",2725,"Unexpected outline behavior","2023-08-11T00:04:32Z","https://github.com/vuejs/vitepress/issues/2725",0.69869787,{"description":3224,"labels":3225,"number":3227,"owner":3146,"repository":3147,"state":3207,"title":3228,"updated_at":3229,"url":3230,"score":3231},"### Is your feature request related to a problem? Please describe.\n\nWhen creating a sidebar structure from anchor points in a single document (think a list of commands on a single page), Vitepress does not highlight the active anchor, and instead highlights the sidebar item clicked to navigate to the page (e.g. clicking on `help` navigates to `/commands/#help`)\r\n\r\n```\r\nhelp -> /commands/#help\r\n```\n\n### Describe the solution you'd like\n\n- support URL hash for sidebar active match\r\n- expose `activeMatch` with behavior similar to `DefaultTheme.NavItem`\n\n### Describe alternatives you've considered\n\nn/a\n\n### Additional context\n\nI may be able to implement this feature\n\n### Validations\n\n- [X] Follow our [Code of Conduct](https://vuejs.org/about/coc.html)\n- [X] Read the [docs](https://vitepress.vuejs.org).\n- [X] Read the [Contributing Guidelines](https://github.com/vuejs/vitepress/blob/main/.github/contributing.md).\n- [X] Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.",[3226],{"name":3157,"color":3158},1565,"support `activeMatch` for sidebar items, or match on URL hash","2023-08-13T00:04:23Z","https://github.com/vuejs/vitepress/issues/1565",0.70308435,{"description":3233,"labels":3234,"number":3236,"owner":3146,"repository":3147,"state":3207,"title":3237,"updated_at":3238,"url":3239,"score":3240},"### Describe the bug\n\nThe aside's outline marker will have an annoying flick when navigating towards above. All `vitepress` sites seems have this problem.\r\n\r\nThe video should be enough to demo the issue. (Sorry for the bad quality)\n\n### Reproduction\n\nhttps://github.com/vuejs/vitepress/assets/45784210/d21095b6-a769-45c5-9119-0fc88f041c3f\n\n### Expected behavior\n\nNo flick\n\n### System Info\n\n```sh\nChrome 114\n```\n\n\n### Additional context\n\n_No response_\n\n### Validations\n\n- [X] Check if you're on the [latest VitePress version](https://github.com/vuejs/vitepress/releases/latest).\n- [X] Follow our [Code of Conduct](https://vuejs.org/about/coc.html)\n- [X] Read the [docs](https://vitepress.dev).\n- [X] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.",[3235],{"name":3157,"color":3158},2665,"🐞Bug: `aside`'s outline marker is flicking when navigating towards above","2023-08-15T00:04:22Z","https://github.com/vuejs/vitepress/issues/2665",0.7045686,{"description":3242,"labels":3243,"number":3248,"owner":3146,"repository":3147,"state":3207,"title":3249,"updated_at":3250,"url":3251,"score":3252},"### Describe the bug\n\nThe anchor doesn't work if there's an “й” in it.\n\n### Reproduction\n\nPlease test. \"Движок авто\" works fine, but \"Настройки сессии\" will not scroll down\n\n\n\n\n```\n[Движок авто](#движок-авто)\n[Настройки сессии](#настройки-сессии)\n\u003Cbr>\n\u003Cbr>\n\u003Cbr>\n\u003Cbr> 300 times...\n\n## Настройки сессии\n## Движок авто\n```\n\n### Expected behavior\n\nworks as other words\n\n### System Info\n\n```Text\nviteress 1.6.3\n```\n\n### Additional context\n\n_No response_\n\n### Validations\n\n- [x] Check if you're on the [latest VitePress version](https://github.com/vuejs/vitepress/releases/latest).\n- [x] Follow our [Code of Conduct](https://vuejs.org/about/coc.html)\n- [x] Read the [docs](https://vitepress.dev).\n- [x] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.",[3244,3245],{"name":3160,"color":3161},{"name":3246,"color":3247},"needs more discussion","C2E0C6",4605,"The anchor doesn't work if there's an “й” in it.","2025-03-18T04:01:15Z","https://github.com/vuejs/vitepress/issues/4605",0.7106173,["Reactive",3254],{},["Set"],["ShallowReactive",3257],{"$fTRc1wZytZ_XrK4EfJfei_Sz-An4H4Yy6syhVxH_PVJc":-1,"$fOENwPIA2hB0v6b4agHJF403Qc2RCPc3XSAIu1EDmFIw":-1},"/vuejs/vitepress/3378"]