One Small Accessibility Fix in VitePress - My First Open-Source PR
I’ve spent most of my time building personal projects, so I wanted to try something different: contributing to a real open-source project. For my first contribution, I chose VitePress, a static site generator powered by Vue. I came across issue #5530, which reported an accessibility problem with code groups.
Understanding the Problem
VitePress code groups let users switch between alternative code snippets using tabs. For example, a documentation page might show the same configuration in JavaScript and TypeScript.
Behind the scenes, these tabs use native radio inputs and labels. The problem was that the element wrapping these controls didn’t explicitly identify itself as a radio group or provide an accessible name. This could make it harder for assistive technologies to communicate the relationship between the options.
At first, it seemed like a small markup issue, but I needed to understand how the renderer generated the HTML and how the client-side code handled tab switching before changing anything.
The Fix
I traced the code-group rendering logic in src/node/markdown/plugins/containers.ts and checked the tab-switching logic in src/client/app/composables/codeGroups.ts.
One important detail was that the existing JavaScript depended on the current DOM hierarchy. Adding unnecessary wrapper elements could have broken tab switching.
I kept the change minimal by adding role="radiogroup" and aria-label="Code group" to the existing .tabs element. I also updated the corresponding unit test and its inline snapshot to verify the new markup while preserving the existing radio inputs, labels, and code panels.
Testing and What I Learned
I ran the focused code-group tests, followed by the full unit test suite. All 517 unit tests passed across 32 test files. Type checking, formatting checks, and the Git diff integrity check also passed.
I used AI as a coding assistant to help investigate the unfamiliar codebase and explore possible approaches. However, I treated its suggestions as things to verify, not answers to trust blindly. I inspected the actual implementation and dependencies between components, reviewed the diff, and ran the project's checks.
One of the harder parts was getting the development tooling working on Windows before I could run the tests. It reminded me that contributing involves more than writing code: understanding the project, respecting its conventions, and verifying changes are equally important.
This is my first step into open source, and I'm looking forward to learning from the maintainers' feedback. The PR is awaiting review, and I haven't yet performed a live screen-reader accessibility audit.
Issue: VitePress #5530
Pull request: [Add your PR URL here]
Thanks to the VitePress maintainers and contributors for building and maintaining an open-source project that developers can learn from and contribute to.
#opensource #vitepress #accessibility #webdev
How to keep VitePress docs in sync with your code
To keep VitePress docs in sync with your code, import every code sample from your source files and leave dead-link checking on, so the build fails when a linked page goes missing and, on the VitePress 2.0 alpha line, when an imported file goes missing. Then review the sentences next to those samples on each release, because no VitePress setting checks that prose against the code.
Say a function's default value changes. The snippet you import with VitePress's code-snippet directive shows the new code on the next build. The paragraph above it still explains the old default, and the page's last-updated date looks recent because someone fixed a typo last week.
What VitePress keeps in sync for you
Its getting started guide says "Markdown files outside the .vitepress directory are considered source files." These tools act on those files, as described in the 2.0.0-alpha.20 docs. The stable release on npm is still the 1.6.x line, and missing-file handling differs between the two, as noted below.
- Code snippet imports. The Markdown guide shows how its code-snippet directive pulls a code block from a file, where "The value of @ corresponds to the source root." Import one VS Code #region instead of the whole file, and the page shows only the lines that matter.
- Markdown includes. The Markdown include directive inserts one Markdown file into another, with line ranges or a region, so shared steps live in one file.
- Missing-file errors. According to the same guide, "Importing a file or region that does not exist throws a build error," and "Including a missing file, region, heading anchor, or an out-of-range line selection throws a build error." On 2.0 alpha releases, rename a source file or delete a region marker and the build stops; setting markdown.snippet.silent or markdown.include.silent to true turns that error into a warning. The VitePress changelog for 2.0.0-alpha.17 notes that includes previously "silently ignored errors when files did not exist," so on the stable 1.6.x line, check the rendered output.
- Dead links. In the site config reference, ignoreDeadLinks defaults to false, and the description reads: "When set to true, VitePress will not fail builds due to dead links."
- Last-updated dates. lastUpdated controls "Whether to get the last updated timestamp for each page using Git," and with the default theme, "enabling this option will display each page's last updated time."
!Diagram: a docs page where the code block imported from source is current but the paragraph above it explains the old default, with a recent last-updated date; a recent date does not mean an accurate page
Where the prose falls behind
Run this check against your repository. Open the newest merged pull request that changed a default, a parameter, or a return value. Did anything flag the paragraph that explains it? The import did its job, and the build passes because every file and region it references still exists. Nothing in that pipeline compares the sentence that names the default with the code below it, so the page now contradicts itself.
| Native check | What it verifies | What it does not see | Where EkLine fits |
| --- | --- | --- | --- |
| Code-snippet imports | The code block matches a file the build can read | The sentence above the block, and code in another repository | Automatic PR review reads the code pull request and can draft the prose fix |
| ignoreDeadLinks left off | Markdown links point at pages that exist | Sidebar entries, per issue 3244, and prose that went stale | Docs Reviewer checks links and writing rules on each pull request through the GitHub Action |
| lastUpdated | When a commit last touched the page | Whether the page still matches the product | A weekly Docs Drift Review audits changes that merged without docs |
Sidebar entries are a second gap. In a VitePress issue titled "Dead links in sidebar not reported," koebi wrote in November 2023 that a sidebar link to a missing page "builds even if Bar doesn't exist." The issue was still open when we checked in October 2026, so treat sidebar entries as unchecked.
The @ alias resolves to the source root, so a snippet stays current only when the build can read the file; code in a separate repository is outside that build unless you check it out or copy it in. A sample pasted by hand from a separate SDK repository is a copy that nothing in the build compares with its original.
That sets the boundary. Imports, the dead-link check, and a same-PR rule are enough when the code sits inside the docs build and every fact the paragraph needs is in the pull request. When the facts live in tickets, Slack threads, specs, or a separate SDK repository, nothing ties them to the page; an Ask HN thread on keeping docs current collects docs-first habits and nightly scripts.
Does lastUpdated tell readers a page is current?
A fair objection: lastUpdated shows when a page last changed, so readers can judge its age for themselves. The date comes from Git, so it reflects a real commit and is honest metadata.
But it records that a commit touched the file, which is a different fact from the page matching the product. In the example, the typo fix moved the date forward while the paragraph about the default stayed wrong. Show the date to readers, and keep it out of how you decide which pages need review.
A VitePress sync checklist for this week
- Find every hand-pasted code block that has a source file in the repository, and replace it with a VitePress code-snippet import of a #region in code your tests already exercise.
- Confirm that ignoreDeadLinks is unset or false in your site config, and, on 2.0 alpha, that no one has set markdown.snippet.silent or markdown.include.silent; on 1.6.x, open the rendered pages that import code.
- Check sidebar entries on their own: after any page rename or deletion, open each sidebar link in a local build or preview.
- Turn on lastUpdated for readers, and track review status somewhere else.
- On each release, list the code changes that alter defaults, parameters, or behavior, and read the paragraphs around every imported snippet for those files.
The last item costs the most, because someone has to connect each code change to the right page.
Adding EkLine to a VitePress repository
EkLine works on that last item, and VitePress keeps building the site.
| Question | On a VitePress site |
| --- | --- |
| Where your content lives | Markdown outside .vitepress, in a GitHub or GitLab repository |
| What EkLine watches | Code repositories, which the GitHub App lists apart from documentation repositories; GitLab merge requests too, per the May 2026 changelog |
| When it reads a change | Each pull request when it opens or leaves draft, once; a weekly Docs Drift Review sweeps what already merged |
| Where its pull request lands | Your docs repository, as a pull request your team reviews |
| Which CI check runs | Docs Reviewer, which checks each docs change for style, consistency, links, and accuracy, through the GitHub Action; its framework list has no VitePress value, so it reviews the Markdown without VitePress-specific handling |
| Samples that are not imported | The Code Sample Review agent in Scheduled Agents, which "Verifies that code samples in your docs are accurate and runnable" |
| What stays in VitePress | The build, imports and includes, the dead-link check, lastUpdated, theme, and hosting |
In the example, the engineer opens the code pull request that changes the default. Docs Agent assesses it from the diff, title, and description; at high confidence it starts a docs pull request, and at medium confidence it leaves a suggestion comment. The draft rewrites the paragraph about the default and leaves the import line alone. You review and merge it, and the VitePress build runs as today. Automatic review reads the pull request alone, so for a change decided in a ticket, start a Docs Agent session from that ticket.
Do reviewers end up rewriting what it drafts? At ContextQA, whose docs are hosted on GitBook, the team reviewed EkLine's updates from April 7 to July 6, 2026, and "Two-thirds merged as a single commit," which the ContextQA case study reads as "the page was right the first time."
If your team leaves VitePress
Should you move, pick a target that keeps the docs as Markdown in Git, because that way the pull request loop you build here keeps working after the move. Potluck Docs is one such target, an open-source Astro + Starlight template under the MIT license that EkLine maintains. Its OpenAPI references render with Scalar and include a client for real requests; private docs and org-scoped docs are built in; and each build writes a sitemap and llms.txt. The project describes itself as "a template, not a hosted product."
FAQ
Does EkLine replace your docs platform?
No. VitePress still builds and serves your site, and its imports and link checks keep working. EkLine adds the prose check: Docs Agent drafts Markdown updates from code pull requests and opens them in your docs repository for your team to approve.
Does VitePress fail the build on dead links?
Yes, for links in your Markdown. ignoreDeadLinks defaults to false, and setting it to true stops VitePress from failing builds on dead links. Sidebar links are a separate case: a 2023 issue reports one to a missing page that still builds.
Can't we script this ourselves?
Partly, since the imports already keep code blocks current. For the prose, cyanydeez described "a for loop that runs nightly on any files updated the prior day," and has local AI update the Markdown file beside it. On VitePress, the paragraph that explains a default sits on a page that imports the source file, not beside it. Each nightly rewrite needs a reader, which rstagi summed up as "it's hard to fact-check everything all the time." EkLine drafts that paragraph fix as a pull request from the code change, and your team approves it.
Choose one pull request from your last release that changed a default, and bring it. To see Docs Agent draft prose fixes on your own VitePress repository, book a demo. Docs Agent is available to all plans, and access is granted on request.
Mentions
One Small Accessibility Fix in VitePress - My First Open-Source PR I’ve spent most of my time building personal projects, so I wanted to try something different: contributing to a real open-source project. For my first contribution, I chose VitePress, a static site generator powered by Vue. I came across issue #5530, which reported an accessibility problem with code groups. Understanding the Problem VitePress code groups let users switch between alternative code snippets using tabs. For example, a documentation page might show the same configuration in JavaScript and TypeScript. Behind the scenes, these tabs use native radio inputs and labels. The problem was that the element wrapping these controls didn’t explicitly identify itself as a radio group or provide an accessible name. This could make it harder for assistive technologies to communicate the relationship between the options. At first, it seemed like a small markup issue, but I needed to understand how the renderer generated the HTML and how the client-side code handled tab switching before changing anything. The Fix I traced the code-group rendering logic in src/node/markdown/plugins/containers.ts and checked the tab-switching logic in src/client/app/composables/codeGroups.ts. One important detail was that the existing JavaScript depended on the current DOM hierarchy. Adding unnecessary wrapper elements could have broken tab switching. I kept the change minimal by adding role="radiogroup" and aria-label="Code group" to the existing .tabs element. I also updated the corresponding unit test and its inline snapshot to verify the new markup while preserving the existing radio inputs, labels, and code panels. Testing and What I Learned I ran the focused code-group tests, followed by the full unit test suite. All 517 unit tests passed across 32 test files. Type checking, formatting checks, and the Git diff integrity check also passed. I used AI as a coding assistant to help investigate the unfamiliar codebase and explore possible approaches. However, I treated its suggestions as things to verify, not answers to trust blindly. I inspected the actual implementation and dependencies between components, reviewed the diff, and ran the project's checks. One of the harder parts was getting the development tooling working on Windows before I could run the tests. It reminded me that contributing involves more than writing code: understanding the project, respecting its conventions, and verifying changes are equally important. This is my first step into open source, and I'm looking forward to learning from the maintainers' feedback. The PR is awaiting review, and I haven't yet performed a live screen-reader accessibility audit. Issue: VitePress #5530 Pull request: [Add your PR URL here] Thanks to the VitePress maintainers and contributors for building and maintaining an open-source project that developers can learn from and contribute to. #opensource #vitepress #accessibility #webdev
How to keep VitePress docs in sync with your code To keep VitePress docs in sync with your code, import every code sample from your source files and leave dead-link checking on, so the build fails when a linked page goes missing and, on the VitePress 2.0 alpha line, when an imported file goes missing. Then review the sentences next to those samples on each release, because no VitePress setting checks that prose against the code. Say a function's default value changes. The snippet you import with VitePress's code-snippet directive shows the new code on the next build. The paragraph above it still explains the old default, and the page's last-updated date looks recent because someone fixed a typo last week. What VitePress keeps in sync for you Its getting started guide says "Markdown files outside the .vitepress directory are considered source files." These tools act on those files, as described in the 2.0.0-alpha.20 docs. The stable release on npm is still the 1.6.x line, and missing-file handling differs between the two, as noted below. - Code snippet imports. The Markdown guide shows how its code-snippet directive pulls a code block from a file, where "The value of @ corresponds to the source root." Import one VS Code #region instead of the whole file, and the page shows only the lines that matter. - Markdown includes. The Markdown include directive inserts one Markdown file into another, with line ranges or a region, so shared steps live in one file. - Missing-file errors. According to the same guide, "Importing a file or region that does not exist throws a build error," and "Including a missing file, region, heading anchor, or an out-of-range line selection throws a build error." On 2.0 alpha releases, rename a source file or delete a region marker and the build stops; setting markdown.snippet.silent or markdown.include.silent to true turns that error into a warning. The VitePress changelog for 2.0.0-alpha.17 notes that includes previously "silently ignored errors when files did not exist," so on the stable 1.6.x line, check the rendered output. - Dead links. In the site config reference, ignoreDeadLinks defaults to false, and the description reads: "When set to true, VitePress will not fail builds due to dead links." - Last-updated dates. lastUpdated controls "Whether to get the last updated timestamp for each page using Git," and with the default theme, "enabling this option will display each page's last updated time." !Diagram: a docs page where the code block imported from source is current but the paragraph above it explains the old default, with a recent last-updated date; a recent date does not mean an accurate page Where the prose falls behind Run this check against your repository. Open the newest merged pull request that changed a default, a parameter, or a return value. Did anything flag the paragraph that explains it? The import did its job, and the build passes because every file and region it references still exists. Nothing in that pipeline compares the sentence that names the default with the code below it, so the page now contradicts itself. | Native check | What it verifies | What it does not see | Where EkLine fits | | --- | --- | --- | --- | | Code-snippet imports | The code block matches a file the build can read | The sentence above the block, and code in another repository | Automatic PR review reads the code pull request and can draft the prose fix | | ignoreDeadLinks left off | Markdown links point at pages that exist | Sidebar entries, per issue 3244, and prose that went stale | Docs Reviewer checks links and writing rules on each pull request through the GitHub Action | | lastUpdated | When a commit last touched the page | Whether the page still matches the product | A weekly Docs Drift Review audits changes that merged without docs | Sidebar entries are a second gap. In a VitePress issue titled "Dead links in sidebar not reported," koebi wrote in November 2023 that a sidebar link to a missing page "builds even if Bar doesn't exist." The issue was still open when we checked in October 2026, so treat sidebar entries as unchecked. The @ alias resolves to the source root, so a snippet stays current only when the build can read the file; code in a separate repository is outside that build unless you check it out or copy it in. A sample pasted by hand from a separate SDK repository is a copy that nothing in the build compares with its original. That sets the boundary. Imports, the dead-link check, and a same-PR rule are enough when the code sits inside the docs build and every fact the paragraph needs is in the pull request. When the facts live in tickets, Slack threads, specs, or a separate SDK repository, nothing ties them to the page; an Ask HN thread on keeping docs current collects docs-first habits and nightly scripts. Does lastUpdated tell readers a page is current? A fair objection: lastUpdated shows when a page last changed, so readers can judge its age for themselves. The date comes from Git, so it reflects a real commit and is honest metadata. But it records that a commit touched the file, which is a different fact from the page matching the product. In the example, the typo fix moved the date forward while the paragraph about the default stayed wrong. Show the date to readers, and keep it out of how you decide which pages need review. A VitePress sync checklist for this week - Find every hand-pasted code block that has a source file in the repository, and replace it with a VitePress code-snippet import of a #region in code your tests already exercise. - Confirm that ignoreDeadLinks is unset or false in your site config, and, on 2.0 alpha, that no one has set markdown.snippet.silent or markdown.include.silent; on 1.6.x, open the rendered pages that import code. - Check sidebar entries on their own: after any page rename or deletion, open each sidebar link in a local build or preview. - Turn on lastUpdated for readers, and track review status somewhere else. - On each release, list the code changes that alter defaults, parameters, or behavior, and read the paragraphs around every imported snippet for those files. The last item costs the most, because someone has to connect each code change to the right page. Adding EkLine to a VitePress repository EkLine works on that last item, and VitePress keeps building the site. | Question | On a VitePress site | | --- | --- | | Where your content lives | Markdown outside .vitepress, in a GitHub or GitLab repository | | What EkLine watches | Code repositories, which the GitHub App lists apart from documentation repositories; GitLab merge requests too, per the May 2026 changelog | | When it reads a change | Each pull request when it opens or leaves draft, once; a weekly Docs Drift Review sweeps what already merged | | Where its pull request lands | Your docs repository, as a pull request your team reviews | | Which CI check runs | Docs Reviewer, which checks each docs change for style, consistency, links, and accuracy, through the GitHub Action; its framework list has no VitePress value, so it reviews the Markdown without VitePress-specific handling | | Samples that are not imported | The Code Sample Review agent in Scheduled Agents, which "Verifies that code samples in your docs are accurate and runnable" | | What stays in VitePress | The build, imports and includes, the dead-link check, lastUpdated, theme, and hosting | In the example, the engineer opens the code pull request that changes the default. Docs Agent assesses it from the diff, title, and description; at high confidence it starts a docs pull request, and at medium confidence it leaves a suggestion comment. The draft rewrites the paragraph about the default and leaves the import line alone. You review and merge it, and the VitePress build runs as today. Automatic review reads the pull request alone, so for a change decided in a ticket, start a Docs Agent session from that ticket. Do reviewers end up rewriting what it drafts? At ContextQA, whose docs are hosted on GitBook, the team reviewed EkLine's updates from April 7 to July 6, 2026, and "Two-thirds merged as a single commit," which the ContextQA case study reads as "the page was right the first time." If your team leaves VitePress Should you move, pick a target that keeps the docs as Markdown in Git, because that way the pull request loop you build here keeps working after the move. Potluck Docs is one such target, an open-source Astro + Starlight template under the MIT license that EkLine maintains. Its OpenAPI references render with Scalar and include a client for real requests; private docs and org-scoped docs are built in; and each build writes a sitemap and llms.txt. The project describes itself as "a template, not a hosted product." FAQ Does EkLine replace your docs platform? No. VitePress still builds and serves your site, and its imports and link checks keep working. EkLine adds the prose check: Docs Agent drafts Markdown updates from code pull requests and opens them in your docs repository for your team to approve. Does VitePress fail the build on dead links? Yes, for links in your Markdown. ignoreDeadLinks defaults to false, and setting it to true stops VitePress from failing builds on dead links. Sidebar links are a separate case: a 2023 issue reports one to a missing page that still builds. Can't we script this ourselves? Partly, since the imports already keep code blocks current. For the prose, cyanydeez described "a for loop that runs nightly on any files updated the prior day," and has local AI update the Markdown file beside it. On VitePress, the paragraph that explains a default sits on a page that imports the source file, not beside it. Each nightly rewrite needs a reader, which rstagi summed up as "it's hard to fact-check everything all the time." EkLine drafts that paragraph fix as a pull request from the code change, and your team approves it. Choose one pull request from your last release that changed a default, and bring it. To see Docs Agent draft prose fixes on your own VitePress repository, book a demo. Docs Agent is available to all plans, and access is granted on request.