\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.6991452,{"description":3154,"labels":3155,"number":3165,"owner":3146,"repository":3147,"state":3148,"title":3166,"updated_at":3167,"url":3168,"score":3169},"### Describe the bug\n\nin the collapsible navigation sidebar, group header interactive controls are nested, this is inaccessible for some accessibility tools as the nested button will not always be announced\n\n### Reproduction\n\nset a collapsible nav in the sidebar\r\ninspect the tree : the nav group header is \"tabindex = 0\" and contains a button\n\n### Expected behavior\n\neither the header should not have a tabindex, or the header button should simply be an icon (no need for two buttons doing the same thing ?)\n\n### System Info\n\n```Text\nSystem:\r\n OS: macOS 14.2.1\r\n CPU: (8) arm64 Apple M2\r\n Memory: 393.92 MB / 24.00 GB\r\n Shell: 5.9 - /bin/zsh\r\n Binaries:\r\n Node: 20.10.0 - /usr/local/bin/node\r\n Yarn: 1.22.19 - /opt/homebrew/bin/yarn\r\n npm: 10.2.5 - /usr/local/bin/npm\r\n pnpm: 8.9.2 - /opt/homebrew/bin/pnpm\r\n Browsers:\r\n Safari: 17.2.1\r\n npmPackages:\r\n vitepress: ^1.0.0-rc.31 => 1.0.0-rc.35\n```\n\n\n### Additional context\n\n\u003Cimg width=\"951\" alt=\"Screenshot 2024-01-29 at 15 55 59\" src=\"https://github.com/vuejs/vitepress/assets/58045985/98c2f5fb-ea2f-44d9-a3f9-196e9d56bbf9\">\r\n\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.",[3156,3159,3162],{"name":3157,"color":3158},"theme","0754FB",{"name":3160,"color":3161},"a11y","fbca04",{"name":3163,"color":3164},"stale","ededed",3517,"accessibility: interactive controls should not be nested","2024-03-07T11:18:56Z","https://github.com/vuejs/vitepress/issues/3517",0.7111564,{"description":3171,"labels":3172,"number":3178,"owner":3146,"repository":3147,"state":3148,"title":3179,"updated_at":3180,"url":3181,"score":3182},"### 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.",[3173,3174,3177],{"name":3157,"color":3158},{"name":3175,"color":3176},"has-workaround","1B4515",{"name":3163,"color":3164},3030,"`permalink: undefined` in `mardown` settings disables Outline","2023-11-06T14:43:56Z","https://github.com/vuejs/vitepress/issues/3030",0.712762,{"description":3184,"labels":3185,"number":3188,"owner":3146,"repository":3147,"state":3148,"title":3189,"updated_at":3190,"url":3191,"score":3192},"### 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.",[3186,3187],{"name":3160,"color":3161},{"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.72757035,{"description":3194,"labels":3195,"number":3196,"owner":3146,"repository":3147,"state":3148,"title":3197,"updated_at":3198,"url":3199,"score":3200},"### Is your feature request related to a problem? Please describe.\n\nVitePress currently outputs unobfuscated class names in the default theme via scoped styles (e.g. `.VPDocAside`). These predictable selectors are easy targets for aggressive adblock filters, which can unintentionally hide more than intended (for example, on [tsx.is](https://tsx.is), sponsor sections or even entire sidebars).\n\nAt the moment, there's no ergonomic way to customize or obfuscate these selectors at the VitePress level. While adblockers serve an important role, I believe VitePress should also empower developers with the option to defend against them if they choose. Providing this flexibility would be a unique value-add for VitePress, and can potentially be an underrated but impactful feature edge.\n\n### Describe the solution you'd like\n\nThe default theme currently uses Vue scoped styles. I recommend migrating it to CSS Modules instead.\n\nVue & Vite already has solid CSS Modules support, so the migration should be straightforward. Using the underlying Vite config, developers can customize class naming.\n\nThis approach gives developers more control without extra complexity, and also helps mitigate the issue of predictable class names being aggressively targeted (e.g. by adblock filters). Personally, I would configure a random hash on each build so that selectors differ on every deploy.\n\n### Describe alternatives you've considered\n\n_No response_\n\n### Additional context\n\nThis would be a breaking change, since the underlying mechanism for CSS scoping would change fundamentally.\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.",[],4920,"Use CSS Modules in default VitePress theme for more flexible class scoping","2025-08-22T09:32:29Z","https://github.com/vuejs/vitepress/issues/4920",0.72830516,{"description":3202,"labels":3203,"number":3206,"owner":3146,"repository":3147,"state":3148,"title":3207,"updated_at":3208,"url":3209,"score":3210},"### Describe the bug\n\nhttps://github.com/vuejs/vitepress/pull/3359 makes it so that there are two separate headers now (`VPNav` and `VPLocalNav`), which make it impossible to apply single style for header, such as blur effect. Even if I remove the divider and border, it'll look as follow:\r\n\r\n\n\n### Reproduction\n\nAdd blur filter to `VPNav` and `VPLocalNav` and remove borders.\n\n### Expected behavior\n\nBoth headers should be wrapped under single element (eg, `\u003Cheader>`).\n\n### System Info\n\n```Text\n-\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.",[3204,3205],{"name":3157,"color":3158},{"name":3163,"color":3164},3393,"New local navbar design breaks ubiquitous header styling","2024-03-07T11:19:13Z","https://github.com/vuejs/vitepress/issues/3393",0.7302684,{"description":3212,"labels":3213,"number":3217,"owner":3146,"repository":3147,"state":3218,"title":3219,"updated_at":3220,"url":3221,"score":3222},"### Describe the bug\n\n\nThe current implementation of the collapsible **sidebar** navigation uses div elements and custom JavaScript to function as an accordion. This non-semantic approach creates significant accessibility issues.\n\nAssistive technologies, like screen readers, cannot properly interpret the role or state (expanded/collapsed) of these components. This results in a poor user experience for individuals who rely on such technology.\n\nI propose replacing the current div-based implementation with the native HTML \u003Cdetails> and \u003Csummary> elements. This would:\n\nProvide full accessibility out-of-the-box for screen reader and keyboard-only users.\n\nReduce custom JavaScript and engineering complexity by leveraging native browser behavior.\n\nAlign the component with modern web standards and semantic best practices.\n\n\n\n### Reproduction\n\nNavigate to any page in the VitePress documentation that uses a collapsible container, such as the [Vitepress Docs](https://vitepress.dev/guide/what-is-vitepress).\n\n\nAttempt to navigate the **sidebar** with a screen reader (e.g., VoiceOver, NVDA, JAWS). The screen reader fails to announce it as a collapsible element or communicate its state.\n\n### Expected behavior\n\nFor sidebar to look and function exactly as it does now but with better accessibility.\n\n\n### System Info\n\n```Text\nJAWS, NVDA, VOICEOVER\n```\n",[3214],{"name":3215,"color":3216},"need more info","bdbefc",4846,"closed","Bug: Custom Container/Accordion component is not accessible and should use native \u003Cdetails>/\u003Csummary> elements","2025-07-17T06:30:42Z","https://github.com/vuejs/vitepress/issues/4846",0.67778677,{"description":3224,"labels":3225,"number":3227,"owner":3146,"repository":3147,"state":3218,"title":3228,"updated_at":3229,"url":3230,"score":3231},"### Describe the bug\r\n\r\nPage outline will display any headings that has an `id` property. However, activelink only works if a heading has an `\u003Ca>` (anchor) child element.\r\n\r\nIn addition, the offset match fails if the heading is nested in a positioned (i.e. `position: relative`) parent element.\r\n\r\n\r\n### Reproduction\r\n\r\n#### [stackblitz playground](https://stackblitz.com/edit/github-zbjrsg-tsuanj)\r\n\r\n```markdown\r\n# All of the following headings are shown in outline, and can be clicked to jump.\r\n\r\n## (A) I am skipped, thanks to (C)\r\n\r\n\u003Ch2 id=\"B\">(B) I cannot be highlighted due to lack of anchor\u003C/h2>\r\n\r\n\u003Cdiv style=\"position: relative\">\r\n\r\n## (C) ActiveLink thinks my offset is 0.\r\n\r\n\u003C/div>\r\n\r\n## The last heading always works when scrolled to bottom.\r\n\r\n```\r\n\r\n### Expected behavior\r\n\r\nEach of the heading above should get highlighted correctly.\r\n\r\n### System Info\r\n\r\n```Text\r\nNot relevant\r\n```\r\n\r\n\r\n### Additional context\r\n\r\n#### I've provided a fix here: #3368 \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.",[3226],{"name":3157,"color":3158},3378,"[default theme] activeAnchor inconsistent with outline when embedding html elements","2024-01-11T00:04:46Z","https://github.com/vuejs/vitepress/issues/3378",0.68987995,{"description":3233,"labels":3234,"number":3235,"owner":3146,"repository":3147,"state":3218,"title":3236,"updated_at":3237,"url":3238,"score":3239},"### Is your feature request related to a problem? Please describe.\n\nWe're using Custom Elements to encapsulate styles from our design system, so it'd be great to be able to tell Vitepress to ignore those tags.\r\n\r\nSuper lightweight example:\r\n\r\n```js\r\nclass ButtonExample extends HTMLElement {\r\n connectedCallback() {\r\n const designSystemCSS = '\u003Clink rel=\"stylesheet\" type=\"text/css\" href=\"designSystemURL\" />'\r\n const target = `\u003Cdiv id=\"app\">\u003C/div>`\r\n this.shadow = this.attachShadow({ mode: 'open' })\r\n this.shadow.innerHTML = designSystemCSS + target\r\n createApp(App) // App defined elsewhere ofc\r\n .mount(this.shadow.querySelector('#app'))\r\n }\r\n}\r\n```\n\n### Describe the solution you'd like\n\nProbably just being able to set `compilerOptions.isCustomElement` somewhere would be good enough?\n\n### Describe alternatives you've considered\n\n_No response_\n\n### Additional context\n\n_No response_\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.",[],735,"Custom element support","2023-01-21T14:34:18Z","https://github.com/vuejs/vitepress/issues/735",0.7069322,{"description":3241,"labels":3242,"number":3244,"owner":3146,"repository":3147,"state":3218,"title":3245,"updated_at":3246,"url":3247,"score":3248},"### Is your feature request related to a problem? Please describe.\r\n\r\nYes, when I verify my documentation site at https://agnosticui.com/ with the [IBM Equal Access Accessibility Checker](https://chrome.google.com/webstore/detail/ibm-equal-access-accessib/lkcagbfjnkomcinoddgooolagloogehp?hl=en-US) it fails hard. This is unfortunate, because one of the things I'm trying to point out is that the UI component library offered is accessible. I lose credibility if the documentation site itself is not a11y compliant.\r\n\r\nI actually get even worse results when I scan the vitepress docs themselves. So while this is a feature request, I would also call it a bug. Lighthouse which I would call more permissive also shows errors in the Accessibility category (but if the IBM checker passes Lighthouse will too).\r\n\r\n### Describe the solution you'd like\r\n\r\nEnsure the code produced by Vitepress is a11y compliant.\r\n\r\nI saw violations with the following rules which can easily be cross-referenced at:\r\nhttps://www.ibm.com/able/requirements/requirements\r\n\r\n1.3.1 Info and Relationships\r\n1.4.3 Contrast (Minimum)\r\n2.4.1 Bypass Blocks\r\n2.5.3 Label in Name\r\n4.1.2 Name, Role, Value\r\n\r\n_Note: this is only from scanning the top-level page. I saw a couple of other warnings on other pages, but this is a good start._\r\n\r\n### Describe alternatives you've considered\r\n\r\nThere are no alternatives. These issues are making Vitepress generated sites less inclusive than they could be meaning certain site users are being excluded which is a real bummer since Vitepress is otherwise producing such lovely sites.\r\n\r\n### Additional context\r\n\r\n\r\n\r\n\r\n### Validations\r\n\r\n- [X] Follow our [Code of Conduct](https://vuejs.org/coc)\r\n- [X] Read the [docs](https://vitepress.vuejs.org/).\r\n- [X] Read the [Contributing Guidelines](https://github.com/vuejs/vitepress/blob/master/.github/contributing.md).\r\n- [X] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.",[3243],{"name":3157,"color":3158},466,"Make Vitepress Accessible","2023-02-04T00:04:08Z","https://github.com/vuejs/vitepress/issues/466",0.708918,["Reactive",3250],{},["Set"],["ShallowReactive",3253],{"$fTRc1wZytZ_XrK4EfJfei_Sz-An4H4Yy6syhVxH_PVJc":-1,"$fU6rPDYLdSGjVBTIqDwQmyAsTL_zVnZPQ1ahpFn2J21Q":-1},"/vuejs/vitepress/2039"]