\n\n\u003Cimg width=\"308\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/0e1beb6b-d06b-436c-b106-c924fead87ab\" />\n\n\u003Cimg width=\"931\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/aef6f71a-fa28-4b7c-b512-e6386e18159a\" />\n\n### Describe the solution you'd like\n\nIn my [pull request](https://github.com/vuejs/vitepress/pull/4630), I've introduced custom components that can be overridden in the `enhanceApp` function. In these custom components, I can add custom logic for rendering text, such as using the Vue compile function. \n\nAdditionally, I added a flag to skip the title update, allowing for custom logic implementation. \n\nPlease also see my PR: [https://github.com/vuejs/vitepress/pull/4630](https://github.com/vuejs/vitepress/pull/4630).\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.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.",[],4637,"vuejs","vitepress","open","Sidenav Components / Skip title update","2025-03-20T12:17:14Z","https://github.com/vuejs/vitepress/issues/4637",0.68738645,{"description":3032,"labels":3033,"number":3037,"owner":3024,"repository":3025,"state":3026,"title":3038,"updated_at":3039,"url":3040,"score":3041},"### Is your feature request related to a problem? Please describe.\r\n\r\nvitepress is currently not capable enough for developing component libraries. While it is fast, it lacks something. We may be able to incorporate support for component capabilities similar to `dumi` to help developers quickly develop Vue component libraries docs.\r\n\r\n```html\r\n\u003Cdemo src=\"../demo.vue\" title=\"Demo block\" desc=\"use demo\" />\r\n```\r\n\r\nAlternatively, use the `desc` defined in the `container` to write Markdown syntax.\r\n\r\n```md\r\n::: demo src=\"../demo.vue\" title=\"Demo block\"\r\n\r\nThis is a `description` that can be written using Markdown.\r\n\r\n:::\r\n```\r\n\r\n### Describe the solution you'd like\r\n\r\nTo address this, I have created the [markdown-it-vitepress-demo](https://github.com/hairyf/markdown-it-vitepress-demo) plugin. I'm not sure if it can be helpful.\r\n\r\n### Describe alternatives you've considered\r\n\r\n_No response_\r\n\r\n### Additional context\r\n\r\n- https://github.com/vuejs/vitepress/issues/987\r\n- https://github.com/vuejs/vitepress/issues/1349\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] Read the [Contributing Guidelines](https://github.com/vuejs/vitepress/blob/main/.github/contributing.md).\r\n- [X] Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.",[3034],{"name":3035,"color":3036},"stale","ededed",2432,"feat(demo): built-in markdown plugin provides support for showcasing demo capabilities.","2024-07-17T14:37:26Z","https://github.com/vuejs/vitepress/issues/2432",0.7223872,{"description":3043,"labels":3044,"number":3049,"owner":3024,"repository":3025,"state":3026,"title":3050,"updated_at":3051,"url":3052,"score":3053},"### 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.",[3045,3048],{"name":3046,"color":3047},"a11y","fbca04",{"name":3035,"color":3036},2980,"a11y: Headings are read verbosely by VoiceOver","2023-10-19T13:04:19Z","https://github.com/vuejs/vitepress/issues/2980",0.7311062,{"description":3055,"labels":3056,"number":3057,"owner":3024,"repository":3025,"state":3058,"title":3059,"updated_at":3060,"url":3061,"score":3062},"### Is your feature request related to a problem? Please describe.\n\nI'm using Vue components that generate headers dynamically, and (of course) the headers I create in Vue components don't appear in the outline.\n\n### Describe the solution you'd like\n\nI'd like to be able to add headers to `page.headers` in my component.\n\n### Describe alternatives you've considered\n\nI tried manipulating `page.headers` in my component from `useData()`, but the headers are read-only at that point.\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.",[],1145,"closed","Dynamic Outline","2023-01-21T14:26:54Z","https://github.com/vuejs/vitepress/issues/1145",0.66761106,{"description":3064,"labels":3065,"number":3066,"owner":3024,"repository":3025,"state":3058,"title":3067,"updated_at":3068,"url":3069,"score":3070},"### Is your feature request related to a problem? Please describe.\n\nH2, H3 headings currently written in vue cannot be shown in outline,\n\n### Describe the solution you'd like\n\nor can we get a useData add header provided\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.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.",[],3103,"Can you identify the H tag in the outline display using vue file in md?","2023-10-27T00:04:15Z","https://github.com/vuejs/vitepress/issues/3103",0.6719204,{"description":3072,"labels":3073,"number":3077,"owner":3024,"repository":3025,"state":3058,"title":3078,"updated_at":3079,"url":3080,"score":3081},"### Describe the bug\n\nIf you use Vue-style interpolation in a markdown title (# in markdown), the aside curtain \"On this page\" will show the Vue syntax and not the final text. It will also not take into account the fact that multiple secondary title exists from a loop.\n\n### Reproduction\n\nIf you have a markdown file like this with a vfor loop and a interpolation of text for the heading:\r\n\r\n```md\r\n# My great page\r\n## {{element.subtitle}}\r\n```\r\n\r\nThe output will show `{{element.subtitle}}` as text in the aside curtain \"On this page\".\r\n\r\n\n\n### Expected behavior\n\nThe output in the aside curtain \"On this page\" should be the string returned by Vue-style interpolation and take into account the multiple instance of the loop.\r\n\r\n\n\n### System Info\n\n```shell\nSystem:\r\n OS: Windows 10 10.0.19044\r\n CPU: (16) x64 11th Gen Intel(R) Core(TM) i7-11850H @ 2.50GHz\r\n Memory: 18.71 GB / 31.73 GB\r\n Binaries:\r\n Node: 18.2.0 - C:\\Program Files\\nodejs\\node.EXE\r\n npm: 8.9.0 - C:\\Program Files\\nodejs\\npm.CMD\r\n Browsers:\r\n Edge: Spartan (44.19041.1266.0), Chromium (102.0.1245.39)\r\n Internet Explorer: 11.0.19041.1566\r\n npmPackages:\r\n vitepress: ^1.0.0-alpha.1 => 1.0.0-alpha.1\n```\n\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] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.",[3074],{"name":3075,"color":3076},"theme","0754FB",785,"Show dynamic headers in aside outline","2023-01-21T14:26:39Z","https://github.com/vuejs/vitepress/issues/785",0.6804104,{"description":3083,"labels":3084,"number":3088,"owner":3024,"repository":3025,"state":3058,"title":3089,"updated_at":3090,"url":3091,"score":3092},"I am looking into porting the using vue in Markdown from vuepress: \r\nhttps://vuepress.vuejs.org/guide/using-vue.html\r\n\r\nIf I understand correctly, vitepress doesn't want to auto register components by convention as Vuepress does. Is this the case? I actually liked this feature, but I understand that vitepress wants to keep the moving parts as small as possible.\r\n\r\nWhat is the recommended way to register the components? I see that in vue-router-next docs they are registered globally inside `enhanceApp`: https://github.com/vuejs/vue-router-next/search?q=HomeSponsors.\r\nSame as with this comment: https://github.com/vuejs/vitepress/issues/92#issuecomment-724645482\r\n\r\nShould we document this way in the docs?\r\n\r\nSome thoughts about this. It would be great that users that want to use the default theme as is, do not need to learn straight away about enhanceApp to be able to use a vue component in their markdown.\r\n\r\nIf auto registering by convention in a folder like `.vitepress/components` is not an option, could we import them directly in the markdown?\r\n\r\n```markdown\r\n# Docs\r\n\r\nThis is a .md using a custom component\r\n\r\n\u003CCustomComponent />\r\n\r\n## More docs\r\n\r\n...\r\n\r\n\u003Cscript setup>\r\n import CustomComponent from '../components/CustomComponent.vue'\r\n\u003C/script>\r\n```\r\n\r\nScript & style hoisting is working in vitepress: https://vuepress.vuejs.org/guide/using-vue.html#script-style-hoisting, but I tried this example to import a Component and it is not at this point.\r\n",[3085],{"name":3086,"color":3087},"docs","0075ca",157,"Recommended way to use Custom Vue components in .md","2023-01-21T16:04:10Z","https://github.com/vuejs/vitepress/issues/157",0.6859754,{"description":3094,"labels":3095,"number":3097,"owner":3024,"repository":3025,"state":3058,"title":3098,"updated_at":3099,"url":3100,"score":3101},"### 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.",[3096],{"name":3075,"color":3076},3378,"[default theme] activeAnchor inconsistent with outline when embedding html elements","2024-01-11T00:04:46Z","https://github.com/vuejs/vitepress/issues/3378",0.68847036,{"description":3103,"labels":3104,"number":3108,"owner":3024,"repository":3025,"state":3058,"title":3109,"updated_at":3110,"url":3111,"score":3112},"### Is your feature request related to a problem? Please describe.\n\nImagine the use case:\r\n\r\nThere are some settings on the left side (just like `vuejs.org`'s API style switch), but I want it to show/hide some `h2` or `h3`, or say, those heading elements which will be in the aside.\r\n\r\nBy wrapping entire `h2` or `h3` parts by a `\u003Cdiv>` and using classes on the root element to control their visibility based on the value of settings. However, currently, the aside content won't update in this case.\r\n\r\n---\r\n\r\nIf you don't want this to be part of the default theme, please inform me and close this issue, Thanks.\n\n### Describe the solution you'd like\n\nI'm here to gather whether you want this to be a feature in the default theme, as I already implemented it by overriding internal files (that's a bit frustrating honestly) and it's working well for me, so I can raise the MR if you would like to accept this feature as part of the default theme.\r\n\r\nMy implementation in high-level:\r\n1. In those aside components (i.e. `VPDocAsideOutline.vue`, `VPDocOutlineDropdown.vue` and `VPLocalNav.vue`\r\n2. Using `IntersectionObserver` to observe the visibility against root (`\u003Chtml>`)\r\n3. Once change is detected, regenerate the headers and cleanup + apply step 2 again.\r\n\r\nPlease feel free to advise if you have a better approach.\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.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.",[3105],{"name":3106,"color":3107},"need more info","bdbefc",2686,"✨Feature: Re-generate aside content when visbility of anchor headings change","2023-08-11T00:04:06Z","https://github.com/vuejs/vitepress/issues/2686",0.6937009,{"description":3114,"labels":3115,"number":3117,"owner":3024,"repository":3025,"state":3058,"title":3118,"updated_at":3119,"url":3120,"score":3121},"### 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.",[3116],{"name":3075,"color":3076},2039,"Header anchors not accessible to screen reader users.","2023-03-22T00:03:24Z","https://github.com/vuejs/vitepress/issues/2039",0.69510293,["Reactive",3123],{},["Set"],["ShallowReactive",3126],{"$fTRc1wZytZ_XrK4EfJfei_Sz-An4H4Yy6syhVxH_PVJc":-1,"$fcFfufQdCv_aP1UFIGYvRoC6wo9btynZ6_KTVQUYWhuU":-1},"/vuejs/vitepress/4867"]