mirror of https://github.com/vuejs/vitepress
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>unmerged-prs-triage
Divyansh Singh
2 days ago
parent
0adb886745
commit
044d60f10a
@ -0,0 +1,35 @@
|
||||
[← Index](../README.md)
|
||||
|
||||
# Accessibility
|
||||
|
||||
Priority: P1 · 2 actionable · last reviewed 2026-08-03
|
||||
|
||||
VitePress's default theme has a couple of longstanding accessibility gaps around keyboard interaction and text sizing. On narrow viewports, the mobile navigation menu does not contain keyboard focus, so tabbing can still reach a hidden, off-screen menu — a gap [#2329](https://github.com/vuejs/vitepress/pull/2329) closes, and one that is now much cheaper to fix thanks to widespread `inert` support. The theme's typography is also hardcoded in pixels rather than rem units, so raising the browser's default font size has no effect on VitePress text; [#703](https://github.com/vuejs/vitepress/pull/703) addressed this but needs a narrower redo scoped to font-related units rather than its original 45-file sweep. Separately, VitePress has no ARIA live-region announcement for client-side route changes — a 2022 PR proposing one, [#1357](https://github.com/vuejs/vitepress/pull/1357), was rejected on the mistaken premise that the loading progress bar already serves that purpose.
|
||||
|
||||
## Worth acting on
|
||||
|
||||
### [#2329](https://github.com/vuejs/vitepress/pull/2329) feat(theme): use inert to avoid traverse menus and content with keyboard
|
||||
|
||||
- **Verdict:** salvage · **Value:** 3 · **Effort:** M
|
||||
- **Author:** userquin · **Closed:** 2023-09-10
|
||||
|
||||
**What it did.** Applied the `inert` attribute to the mobile nav and content regions so hidden menus and off-screen content cannot receive keyboard focus on narrow viewports.
|
||||
|
||||
**Why it was closed.** Never reviewed — no maintainer feedback in ~4 months, only the author's own review comments, then stale.
|
||||
|
||||
**Why it still matters.** `composables/nav.ts` and `Layout.vue` still have no `inert` or focus-containment handling for the mobile menu; the only `inert` usage in the theme is in `VPLocalSearchBox` for an unrelated purpose. Keyboard users on narrow screens can still tab into a hidden menu.
|
||||
|
||||
**Recommendation.** This and [#1448](https://github.com/vuejs/vitepress/pull/1448) are two attempts at the same problem; fix it once, using this PR's `inert` approach rather than [#1448](https://github.com/vuejs/vitepress/pull/1448)'s `tabindex=-1`. Browser support for `inert` has matured since 2023, so the Vue-rendering workaround the original PR needed is almost certainly unnecessary now — expect a much smaller diff. Model the accompanying focus/Escape behavior on the already-merged `useFocusTrap` (search box) and `useCloseSidebarOnEscape` patterns, which is exactly what reviewers asked for on [#1448](https://github.com/vuejs/vitepress/pull/1448).
|
||||
|
||||
### [#703](https://github.com/vuejs/vitepress/pull/703) perf(a11y): make font size follow user brower settings
|
||||
|
||||
- **Verdict:** redo · **Value:** 3 · **Effort:** L
|
||||
- **Author:** kecrily · **Closed:** 2022-06-06
|
||||
|
||||
**What it did.** Converted hardcoded px `font-size`/`line-height`/`width`/`height` values to rem across roughly 45 default-theme component and style files so browser text-zoom settings are respected.
|
||||
|
||||
**Why it was closed.** kiaking asked to hold off, wanting to redo it himself more carefully — concerned about incidental changes (e.g. border widths) and that content-width media queries would need rem conversion too for consistency.
|
||||
|
||||
**Why it still matters.** `vars.css` and `base.css` still hardcode px today (16px root font size, fixed custom-block sizes, and so on), so users who raise their browser's default font size still get unchanged VitePress text.
|
||||
|
||||
**Recommendation.** Do not resurrect the original sweep. Scope a new PR to font-related units only — `font-size` and `line-height` — leaving layout dimensions, borders, and media queries in px. That sidesteps kiaking's specific objections and is reviewable; layout/media-query rem conversion can be a separate decision later if wanted.
|
||||
@ -0,0 +1,18 @@
|
||||
[← Index](../README.md)
|
||||
|
||||
# Build pipeline, dev server & routing
|
||||
|
||||
Priority: P2 · 1 actionable · last reviewed 2026-08-03
|
||||
|
||||
VitePress's build pipeline, dev server, and client-side router govern how pages compile, get served, and resolve to routes — including how URLs map to files on disk. That mapping is case-sensitive throughout, with no accommodation for case-insensitive URLs ([#116](https://github.com/vuejs/vitepress/pull/116)): internal links whose case doesn't match the file on disk work in local dev but can 404 once deployed to a case-sensitive host.
|
||||
|
||||
## Worth acting on
|
||||
|
||||
### [#116](https://github.com/vuejs/vitepress/pull/116) feat: support lowercase url (#115)
|
||||
|
||||
**redo** · value 2/5 · effort L · yuxino · closed 2021-09-01
|
||||
|
||||
- **What it did:** lowercased build output paths and URLs to stop 404s caused by case-mismatched links.
|
||||
- **Why it was closed:** stalled, not rejected. kiaking, posva and the author agreed the problem was real but never converged on a design — hosting behaviour and HMR implications were the open questions — and it was closed after a year of inactivity.
|
||||
- **Why it still matters:** there is still no case-insensitive URL handling anywhere in the build/render pipeline (the only `toLowerCase()` uses are unrelated — hash maps and Windows drive letters), so [#115](https://github.com/vuejs/vitepress/issues/115) is unaddressed. Case-mismatched internal links keep working in dev on macOS/Windows and 404 on Linux hosts.
|
||||
- **Recommendation:** treat as a design question before any code. A real fix spans build output naming, dev-server resolution and static-host behaviour (some hosts are case-sensitive, some aren't), so the blanket-lowercase approach in this PR is not the shape to revive. Two viable outcomes: a documented "won't do" plus a build-time warning for internal links whose case doesn't match the file on disk (cheap, catches the actual failure mode), or a proper opt-in option designed across all three layers. The dead-link checker is the natural place for the warning.
|
||||
@ -0,0 +1,37 @@
|
||||
[← Index](../README.md)
|
||||
|
||||
# Config, CLI, types & public API
|
||||
|
||||
Priority: P1 · 3 actionable · last reviewed 2026-08-03
|
||||
|
||||
VitePress's CLI drives the `vitepress init` scaffolding wizard, the dev server's interactive keyboard shortcuts, and the console output of the build command. Three small ergonomics fixes are worth reviving: a Ctrl-C shortcut that still exits the dev server with a non-zero code for what is a normal, user-initiated stop ([#3419](https://github.com/vuejs/vitepress/pull/3419)); a directory-escape check for the `init` wizard that the code still flags with an unresolved TODO ([#4876](https://github.com/vuejs/vitepress/pull/4876)); and a build-time spinner that keeps animating in non-TTY environments, which can hide real errors and make builds look hung ([#5002](https://github.com/vuejs/vitepress/pull/5002)). Each is a small, self-contained fix confirmed against current source, not an open design question.
|
||||
|
||||
## Worth acting on
|
||||
|
||||
### [#3419](https://github.com/vuejs/vitepress/pull/3419) fix(cli/shortcuts): CTRL-C should be considered normal exit
|
||||
|
||||
`salvage` · value 3/5 · effort S · @zhangyx1998 · closed 2024-01-05
|
||||
|
||||
- **Did** — Made Ctrl-C / Ctrl-D stop the dev server with exit code 0 instead of 1, since a user-initiated stop is not an error. Fixes [issue #3418](https://github.com/vuejs/vitepress/issues/3418).
|
||||
- **Closed because** — Closed roughly six hours after opening with zero discussion and no recorded maintainer comment; no reason documented.
|
||||
- **Still matters** — Confirmed on main: `src/node/shortcuts.ts:77` still runs `await server.close().finally(() => process.exit(1))` for `\x03`/`\x04`, while the `q` (quit) shortcut 25 lines above at `:52` exits via a bare `process.exit()`. Identical user intent, two different exit codes. Non-zero on a normal stop trips CI wrappers, `&&` chains and process supervisors.
|
||||
- **Do** — Reopen or rebase. It is a one-token change at `shortcuts.ts:77` to match the existing `q` path, and the internal inconsistency makes it self-justifying without further discussion.
|
||||
|
||||
### [#4876](https://github.com/vuejs/vitepress/pull/4876) feat(init): validation to make sure config directory is inside cwd
|
||||
|
||||
`redo` · value 3/5 · effort S · @hyperz111 · closed 2025-08-12
|
||||
|
||||
- **Did** — Added validation to the `vitepress init` wizard's directory prompt rejecting paths that escape the current working directory.
|
||||
- **Closed because** — No comments and no reviews; closed 10 days after opening. Consistent with staleness, not a decision on the merits.
|
||||
- **Still matters** — Confirmed on main: the comment `// TODO make sure directory is inside` is still present verbatim at `src/node/init/init.ts:55`, so the gap is acknowledged in-tree.
|
||||
- **Do** — Redo rather than reopen. This branch's file list is polluted with dozens of unrelated files (`Layout.vue`, `VPNav.vue`, …) from an out-of-date base, so it is not rebaseable in practice. Open a clean single-purpose PR touching only `init.ts`: resolve the prompt value against `cwd`, reject escapes, and delete the TODO in the same commit.
|
||||
- **Not a duplicate of the earlier attempts** — [#2286](https://github.com/vuejs/vitepress/pull/2286) and [#2267](https://github.com/vuejs/vitepress/pull/2267) were declined because `init` auto-creates a missing target directory. Those asked "does this path exist?"; this asks "is this path contained in cwd?" — which is what the TODO is about, so the earlier rejection does not cover it.
|
||||
|
||||
### [#5002](https://github.com/vuejs/vitepress/pull/5002) fix(cli): gate ora spinner behind tty check
|
||||
|
||||
`salvage` · value 2/5 · effort S · @nicolas-goudry · closed 2026-05-23
|
||||
|
||||
- **Did** — Gated the `ora` spinner behind an explicit TTY check so build errors are not hidden and builds do not look hung in non-interactive environments such as Nix builds.
|
||||
- **Closed because** — Labeled "needs more discussion". brc-dd was open in principle to adjusting the spinner's `isEnabled` default but wanted the Nix-specific root cause understood first; the thread trailed off unresolved.
|
||||
- **Still matters** — Confirmed on main: `src/node/utils/task.ts:10` still constructs `ora({ discardStdin: false })` with no `isEnabled` or TTY gating, so every build task spins regardless of whether stdout is a TTY.
|
||||
- **Do** — Reopen conditional on the contributor supplying what was asked for: why ora's own TTY detection fails under Nix, plus an upstream ora issue link. If that does not materialize, an `isEnabled: process.stdout.isTTY && !process.env.CI` default is defensible on its own merits and mirrors the guard `bindShortcuts` already applies at `shortcuts.ts:61` (`!process.stdin.isTTY || process.env.CI`).
|
||||
@ -0,0 +1,27 @@
|
||||
[← Index](../README.md)
|
||||
|
||||
# Default theme configuration & extensibility
|
||||
|
||||
Priority: P2 · 2 actionable · last reviewed 2026-08-03
|
||||
|
||||
Everything people reach for when bending the default theme without forking it: `themeConfig` options, frontmatter switches, `Layout` slots, and component exports. Two gaps here are worth closing, both traceable to pull requests that never merged: a nav item with a dropdown that can also carry its own link ([#2990](https://github.com/vuejs/vitepress/pull/2990)), and a slot for custom fallback content when an ad blocker hides Carbon Ads ([#348](https://github.com/vuejs/vitepress/pull/348)). Neither PR was closed over disagreement with the idea — one was deferred pending an interaction-design decision, the other went stale as the theme was rewritten around it — and both gaps still exist today, so the path forward is a fresh implementation rather than a revived branch.
|
||||
|
||||
## Worth acting on
|
||||
|
||||
### [#2990](https://github.com/vuejs/vitepress/pull/2990) feat(theme): allow link on nav item with children
|
||||
|
||||
**redo** · value 3 · effort M · brc-dd · closed 2023-09-19
|
||||
|
||||
- **What it did** — Let a top-level nav item that has a dropdown also carry its own `link`, so clicking the label navigates instead of only opening the flyout.
|
||||
- **Why it was closed** — Self-closed by the author (brc-dd) with the note that it "will be a bit more complex". Deferred on design complexity, never rejected in principle.
|
||||
- **Why it still matters** — In the current codebase, `NavItemWithChildren` in `types/default-theme.d.ts` declares only `text`, `items` and `activeMatch` — no `link` field — and `VPNavBarMenuGroup` renders only a `VPFlyout` trigger. There is still no way to express this.
|
||||
- **Recommendation** — The blocker was never the code, it was the interaction design: one control cannot both navigate and open a menu without a rule for which wins. Settle that before writing any diff — desktop can hover-to-open and click-to-navigate, but touch has no hover, so the first tap has to do something unambiguous (common resolutions: tap opens and a duplicated "Overview" child carries the link, or tap navigates and a separate chevron opens). Pick one, document it, then implement. This is the author's own deferred PR, so the design call is in-house and unblocked.
|
||||
|
||||
### [#348](https://github.com/vuejs/vitepress/pull/348) feat: allow displaying fallback when ads are blocked
|
||||
|
||||
**redo** · value 2 · effort S · posva · closed 2022-06-06
|
||||
|
||||
- **What it did** — Added a `carbon-ads-blocked` slot on the default theme `Layout` so sites could render a custom message when an ad blocker suppressed Carbon Ads.
|
||||
- **Why it was closed** — kiaking closed it in 2022 because the theme code had changed substantially since the PR was opened in 2021 and it would need a fresh start. The idea itself was not rejected.
|
||||
- **Why it still matters** — `VPCarbonAds.vue` and `VPDocAsideCarbonAds.vue` are still present with no ad-blocked detection or fallback. `.VPCarbonAds` sets `min-height: 256px` and a background color, so a blocked ad leaves a visibly empty tinted block in the aside rather than collapsing.
|
||||
- **Recommendation** — Smallest and most self-contained of the two: detect the blocked state in `VPCarbonAds.vue` and expose a slot for the fallback. Two constraints worth honoring — ad-blocker detection is heuristic, so keep the fallback opt-in (render nothing unless the site supplies slot content) rather than shipping default copy; and collapsing the `min-height` when blocked is arguably the better default even for sites that supply no fallback, which makes a useful standalone first commit.
|
||||
@ -0,0 +1,56 @@
|
||||
[← Index](../README.md)
|
||||
|
||||
# Default theme navigation, outline & reading UX
|
||||
|
||||
Priority: P1 · 7 actionable · last reviewed 2026-08-03
|
||||
|
||||
Everything in the default theme between the content and the reader: navbar and mobile nav screen, sidebar, outline/TOC and its scroll marker, doc footer (prev/next, last-updated, edit link), plus scroll behaviour. Five items below are worth picking up. Two are chronic: **smooth scrolling has been filed six times** ([#978](https://github.com/vuejs/vitepress/pull/978), [#981](https://github.com/vuejs/vitepress/pull/981), [#1002](https://github.com/vuejs/vitepress/pull/1002), [#1449](https://github.com/vuejs/vitepress/pull/1449), [#1544](https://github.com/vuejs/vitepress/pull/1544), [#2133](https://github.com/vuejs/vitepress/pull/2133)) and has always failed on the same two objections, while **outline scroll tracking on long pages** has been attempted three times ([#3387](https://github.com/vuejs/vitepress/pull/3387), [#4457](https://github.com/vuejs/vitepress/pull/4457), plus still-open [#3654](https://github.com/vuejs/vitepress/pull/3654)) with nothing merged — each deserves one maintainer decision recorded on an issue rather than a seventh drive-by PR. The other three are smaller, self-contained fixes: hiding the nav on a per-page basis, letting an overflowing top nav scroll instead of silently clipping, and a more accurate `.has-aside` check.
|
||||
|
||||
## Worth acting on
|
||||
|
||||
7 PRs, grouped into 5 items of work.
|
||||
|
||||
### [#3387](https://github.com/vuejs/vitepress/pull/3387) Fix: Make the outline follow the page scroll — with [#4457](https://github.com/vuejs/vitepress/pull/4457) feat(theme): add doc aside scroll spy
|
||||
|
||||
`redo` · value 3 · effort M · @huyikai, @userquin · closed 2024-01-26 / 2025-01-01
|
||||
|
||||
- **Did** — both make the aside outline scroll itself so the active-heading marker stays visible on long pages; [#4457](https://github.com/vuejs/vitepress/pull/4457) via `VPDoc.vue`/`outline.ts`.
|
||||
- **Closed** — [#3387](https://github.com/vuejs/vitepress/pull/3387)'s review was dismissed after testing showed the fix "doesn't seem to be working on the deploy preview," and the discrepancy was never resolved. [#4457](https://github.com/vuejs/vitepress/pull/4457) was self-closed as a duplicate of [#3654](https://github.com/vuejs/vitepress/pull/3654) — which is still open and unmerged today.
|
||||
- **Still matters** — `.aside-container` is `position: fixed; height: 100vh; overflow-y: auto` with only a CSS marker for the active link and no scroll-into-view logic. Three attempts, zero landed.
|
||||
- **Do** — one implementation, verified live on a deploy preview with a genuinely long page (not just code review — that is exactly how [#3387](https://github.com/vuejs/vitepress/pull/3387) died). Check whether [#3654](https://github.com/vuejs/vitepress/pull/3654) is close enough to finish before starting over; if so, close this thread by reviewing that PR.
|
||||
|
||||
### [#1449](https://github.com/vuejs/vitepress/pull/1449) feat: Smooth Scrolling behavior — with [#1544](https://github.com/vuejs/vitepress/pull/1544) Added smooth scrolling
|
||||
|
||||
`redo` · value 3 · effort M · @g4rry420, @jessekelly881 · closed 2023-01-20 / 2022-10-27
|
||||
|
||||
- **Did** — both add smooth scrolling for anchor/outline navigation; [#1544](https://github.com/vuejs/vitepress/pull/1544) as a bare `scroll-behavior: smooth`.
|
||||
- **Closed** — kiaking wanted more discussion on [#1449](https://github.com/vuejs/vitepress/pull/1449), citing a user report of broken header-anchor jump positions, and asked that it be configurable rather than global. [#1544](https://github.com/vuejs/vitepress/pull/1544) was self-closed as a duplicate.
|
||||
- **Still matters** — this is the same request filed **six times**: [#978](https://github.com/vuejs/vitepress/pull/978), [#981](https://github.com/vuejs/vitepress/pull/981), [#1002](https://github.com/vuejs/vitepress/pull/1002), [#1449](https://github.com/vuejs/vitepress/pull/1449), [#1544](https://github.com/vuejs/vitepress/pull/1544), [#2133](https://github.com/vuejs/vitepress/pull/2133). Only the "back to top" button scrolls smoothly today; router and outline navigation jump. The four other filings failed on approach, never on the desire itself.
|
||||
- **Do** — decide once, publicly, and link every future filing to that decision. The objections across all six are consistent and narrow: (a) CSS-only `scroll-behavior: smooth` breaks outline-link scroll targeting and desyncs the active-heading highlight and URL hash, because scroll handlers are throttled ([#978](https://github.com/vuejs/vitepress/pull/978), demonstrated on video in [#981](https://github.com/vuejs/vitepress/pull/981)); (b) a user-facing nav toggle is unwanted — kiaking on [#2133](https://github.com/vuejs/vitepress/pull/2133): "Never seen this in any site." That leaves exactly one viable shape: opt-in `themeConfig` flag, JS-driven scroll that keeps outline highlighting and hash in sync, honouring `prefers-reduced-motion` automatically, no new UI. Anything else has already been rejected.
|
||||
|
||||
### [#1236](https://github.com/vuejs/vitepress/pull/1236) feat(theme): add ability to hide nav per-page
|
||||
|
||||
`redo` · value 3 · effort M · @szsascha · closed 2022-09-01
|
||||
|
||||
- **Did** — a `hideNav` option removing the navbar by toggling a class on `VPNavBar`.
|
||||
- **Closed** — brc-dd requested changes: the logic targeted the wrong component (`VPNavBar` rather than `VPNav`/`VPLocalNav`) and ignored sidebar/footer spacing; he suggested a broader `layout: blank`-style fix per [#1091](https://github.com/vuejs/vitepress/issues/1091) instead.
|
||||
- **Still matters** — no blank/bare layout exists in the theme today, and [#1091](https://github.com/vuejs/vitepress/issues/1091) is closed with no matching implementation found.
|
||||
- **Do** — implement the shape brc-dd asked for (a bare layout, or frontmatter that suppresses nav *and* reclaims its spacing) rather than the per-component class toggle.
|
||||
|
||||
### [#5097](https://github.com/vuejs/vitepress/pull/5097) Allow overflow-x with horizontal scrolling in VPNav
|
||||
|
||||
`redo` · value 2 · effort M · @mohdibntarek · closed 2026-05-15
|
||||
|
||||
- **Did** — let the top nav scroll horizontally instead of silently clipping when nav items exceed the viewport width, prompted by two downstream Documenter.jl bug reports.
|
||||
- **Closed** — author self-closed after their own follow-up regressed dropdown positioning (menus stopped floating) and they could not fix it. No maintainer ever weighed in.
|
||||
- **Still matters** — `VPNavBar.vue`/`VPNavBarMenu.vue` still have no overflow handling; items clip silently.
|
||||
- **Do** — worth a maintainer opinion *before* anyone codes it, because kiaking rejected the adjacent [#1273](https://github.com/vuejs/vitepress/pull/1273) on [#1271](https://github.com/vuejs/vitepress/issues/1271) with the position that overflowing sites should restructure their menus. Scrolling is a different remedy from wrapping, so it is not automatically covered by that ruling — but confirm the philosophy first. If green-lit: scroll only the menu row, and keep flyouts positioned against the viewport so dropdowns still float.
|
||||
|
||||
### [#2297](https://github.com/vuejs/vitepress/pull/2297) fix: better `.has-aside` condition
|
||||
|
||||
`salvage` · value 2 · effort M · @bojanrajh · closed 2026-07-08
|
||||
|
||||
- **Did** — reworked how `.has-aside` is computed on `VPDoc`/`VPContent` to account for rendered slots, `theme.carbonAds` and `getHeaders()`, not just frontmatter/theme aside settings. Ships with slot tests.
|
||||
- **Closed** — no comments ever left; closed roughly three years after opening in the recent bulk stale cleanup.
|
||||
- **Still matters** — `composables/layout.ts` `hasAside` still ignores the carbonAds/slots/`getHeaders` edge cases, and `theme.carbonAds` config still exists in `VPDocAside.vue`, so the correctness gap is unaddressed.
|
||||
- **Do** — rebase against today's component structure and re-verify the included slot tests; it's the cheapest correctness fix here if the rebase goes cleanly.
|
||||
@ -0,0 +1,61 @@
|
||||
[← Index](../README.md)
|
||||
|
||||
# Docs content, website & repo chores
|
||||
|
||||
Priority: P3 · 4 actionable · last reviewed 2026-08-03
|
||||
|
||||
This area covers VitePress's documentation content, deployment guides, and the docs site's own configuration, branding, and release tooling. The deployment guide covers well over a dozen hosting platforms but still has no DigitalOcean App Platform section, a gap [#2010](https://github.com/vuejs/vitepress/pull/2010) fills with a short new subsection matching the format of its neighbours. The `publicDir` option is undocumented anywhere in the docs, which [#3885](https://github.com/vuejs/vitepress/pull/3885) addresses with a paragraph for `asset-handling.md`. Import order across the codebase is still inconsistent for lack of an ESLint config or prettier plugin; [#2384](https://github.com/vuejs/vitepress/pull/2384) reordered things by hand, but the fix worth landing is the tooling itself, with a mechanical reformat to follow. And roughly sixteen English guide pages have grammar corrections waiting in [#4575](https://github.com/vuejs/vitepress/pull/4575), which still applies cleanly and mainly needs review rather than fresh authoring. Separately, the getting-started guide's package-manager command table is worth a preventive fix: it draws roughly two duplicate "fix" PRs a year from contributors assuming `vitepress init` installs vitepress itself, and a one-line inline note ("`vitepress init` does not install vitepress — install it first; `pnpm`/`bun` then run the local binary directly") would head them off.
|
||||
|
||||
## Worth acting on
|
||||
|
||||
### [#2010](https://github.com/vuejs/vitepress/pull/2010) docs: Add deployment steps for DigitalOcean App Platform
|
||||
|
||||
- **Verdict:** salvage · **Value:** 3 · **Effort:** S
|
||||
- **Author:** pilotmoon · **Closed:** 2023-02-28
|
||||
|
||||
**What it did.** Added a DigitalOcean App Platform subsection to the deployment guide.
|
||||
|
||||
**Why it was closed.** Closed about an hour after opening with zero comments or review; no reason recorded.
|
||||
|
||||
**Why it still matters.** `docs/en/guide/deploy.md` "Platform Guides" today lists the generic Netlify/Vercel/Cloudflare/Amplify/Render block plus GitHub Pages, GitLab Pages, Azure, CloudRay, Firebase, Heroku, Hostinger, Kinsta, Stormkit, Surge and Nginx — but still no DigitalOcean, despite several smaller platforms being added since 2023. The section is demonstrably open to additions.
|
||||
|
||||
**Recommendation.** Land a fresh `### DigitalOcean App Platform` entry under Platform Guides, matching the terse three-to-five-line format of its Kinsta/Stormkit/Hostinger neighbours. Do not replay the 2023 diff verbatim — App Platform's dashboard field names have changed; re-verify the build command / output directory settings first.
|
||||
|
||||
### [#3885](https://github.com/vuejs/vitepress/pull/3885) docs: add documentation for `publicDir`
|
||||
|
||||
- **Verdict:** salvage · **Value:** 2 · **Effort:** S
|
||||
- **Author:** dmohns · **Closed:** 2024-05-22
|
||||
|
||||
**What it did.** Added guidance on `publicDir` behaviour and customization, citing two issues ([#3203](https://github.com/vuejs/vitepress/issues/3203), [#3884](https://github.com/vuejs/vitepress/issues/3884)) where users were confused by it.
|
||||
|
||||
**Why it was closed.** Author self-closed after reflection ("don't think it provides much benefit"). brc-dd's only comment was a placement correction, which the author had already applied — no maintainer rejection on record.
|
||||
|
||||
**Why it still matters.** `publicDir` appears nowhere in `docs/en/` today; `asset-handling.md` never names it.
|
||||
|
||||
**Recommendation.** One concise paragraph in `docs/en/guide/asset-handling.md`. Merge with [#4600](https://github.com/vuejs/vitepress/pull/4600), which attacked the neighbouring gap: its frontmatter-`description` half already landed via a separate bulk pass, but its clarification that `public/` must live under a custom `srcDir` did not. Both belong in the same paragraph, so a single PR closes both threads.
|
||||
|
||||
### [#2384](https://github.com/vuejs/vitepress/pull/2384) refactor: standardize import sort
|
||||
|
||||
- **Verdict:** redo · **Value:** 2 · **Effort:** S
|
||||
- **Author:** zonemeen · **Closed:** 2023-05-21
|
||||
|
||||
**What it did.** Manually reordered import statements across ~14 files for consistency.
|
||||
|
||||
**Why it was closed.** brc-dd preferred an automated solution (a prettier plugin) over a one-off manual reordering, noting ESLint was too much overhead for the team at the time.
|
||||
|
||||
**Why it still matters.** There is still no import-sort prettier plugin and no ESLint config in the repo, so the inconsistency the PR targeted persists.
|
||||
|
||||
**Recommendation.** Only worth doing as tooling: add a prettier import-order plugin and land the reformat as one mechanical commit. Never revive the hand-ordered diff — three years of changes guarantee conflicts, and a manual pass reintroduces the exact drift brc-dd objected to. Purely cosmetic; lowest priority in this list.
|
||||
|
||||
### [#4575](https://github.com/vuejs/vitepress/pull/4575) fix: grammar
|
||||
|
||||
- **Verdict:** salvage · **Value:** 2 · **Effort:** M
|
||||
- **Author:** streakwind · **Closed:** 2025-09-06
|
||||
|
||||
**What it did.** Line-by-line grammar and wording corrections, one commit per page, across ~16 English guide and reference docs.
|
||||
|
||||
**Why it was closed.** No maintainer verdict on record. The only post-open activity was the author's own `/publish`; closed roughly seven months later without comment, i.e. went stale.
|
||||
|
||||
**Why it still matters.** All touched files still exist largely intact, so most of the diff still applies.
|
||||
|
||||
**Recommendation.** Viable to rebase, but the cost here is review, not authoring — budget for reading copy-edits across 16 files before reopening. Two constraints worth setting upfront: (1) keep only actual grammar errors and drop tone/style preferences, since maintainers rejected exactly that kind of subjective rewording in [#5181](https://github.com/vuejs/vitepress/pull/5181) and [#4910](https://github.com/vuejs/vitepress/pull/4910); (2) decide whether the translated locales get follow-ups, or accept that they drift further from the English source.
|
||||
@ -0,0 +1,21 @@
|
||||
[← Index](../README.md)
|
||||
|
||||
# i18n & locale handling
|
||||
|
||||
Priority: P2 · 1 actionable · last reviewed 2026-08-03
|
||||
|
||||
VitePress serves multi-language documentation by keying routing, theme strings, and search indexing off a URL's locale prefix, such as `/zh/` or `/ja/`. That matching has one live gap: it requires a trailing slash, so a bare `/zh` fails to match and silently falls back to the root locale — wrong config, wrong UI strings, and the wrong search bucket, with nothing to signal the mismatch. [#2002](https://github.com/vuejs/vitepress/pull/2002) closes exactly that gap and is the one item worth picking up below.
|
||||
|
||||
## Worth acting on
|
||||
|
||||
### [#2002](https://github.com/vuejs/vitepress/pull/2002) fix: allow to use language page without ending slash
|
||||
|
||||
**salvage** · value 3 · effort S · azat-io · closed 2023-02-28
|
||||
|
||||
**What it did.** Relaxed locale path matching so a bare `/zh` (no trailing slash) resolves to the `zh` locale rather than falling back to root, closing [#2001](https://github.com/vuejs/vitepress/issues/2001).
|
||||
|
||||
**Why it was closed.** Closed the day after opening with no recorded discussion — no stated objection.
|
||||
|
||||
**Why it still matters.** Verified against current main: `getLocaleForPath` in `src/shared/shared.ts:101` still matches with `` `^/${key}/` ``, and `isActive` normalises `/zh` to `/zh` before testing that regex, so a bare `/zh` misses every locale key and returns `'root'`. The bug is live. It affects more than the page render — the same function backs `resolveSiteDataByRoute`, `markdownToVue`, and locale bucketing in `localSearchPlugin`, so a bare-locale URL gets root-locale config, root-locale theme strings and the wrong search index bucket.
|
||||
|
||||
**Recommendation.** Reimplement directly rather than rebasing a three-year-old branch; the change is a single regex in a single tracked file (`src/client/shared.ts` and `src/node/shared.ts` are generated copies and are gitignored). Match `` `^/${key}(/|$)` `` or equivalent. Worth a unit test covering `/zh`, `/zh/`, `/zh/guide/` and a non-match like `/zhuang/` — that last case is the one a careless fix breaks.
|
||||
@ -0,0 +1,23 @@
|
||||
[← Index](../README.md)
|
||||
|
||||
# Markdown & content authoring
|
||||
|
||||
Priority: P1 · 1 actionable · last reviewed 2026-08-03
|
||||
|
||||
VitePress turns source markdown into rendered pages through custom containers and GitHub-style alerts, code groups, snippets and includes with region markers, Shiki syntax highlighting with copy-code, link rewriting and dead-link reporting, and the `markdown.config` plugin surface. One gap remains in the container set: VitePress has no `::: success` block ([#4228](https://github.com/vuejs/vitepress/pull/4228)), even though the theme already defines the `--vp-c-success-*` colors it would use — they currently go unused outside diff styling.
|
||||
|
||||
Also unfinished nearby: dead-link checks still can't ignore non-HTML files under `publicDir` automatically, so docs teams reach for `VITE_EXTRA_EXTENSIONS` per extension instead ([#4283](https://github.com/vuejs/vitepress/pull/4283)). The `{ minRows: 6 }` / attrs-delimiter collision noted in [#2641](https://github.com/vuejs/vitepress/pull/2641) still isn't documented anywhere.
|
||||
|
||||
## Worth acting on
|
||||
|
||||
### [#4228](https://github.com/vuejs/vitepress/pull/4228) feat(theme): containers: add the success custom block
|
||||
|
||||
`salvage` · value 2 · effort S · lifehackerhansol · closed 2026-07-25
|
||||
|
||||
**What it did.** Adds a `::: success` container (green) reusing the already-defined `--vp-c-success-*` CSS variables.
|
||||
|
||||
**Why it was closed.** Stale-bot auto-close in July 2026, with zero maintainer engagement and no explicit rejection.
|
||||
|
||||
**Why it still matters.** Still absent: the label table in `src/node/markdown/plugins/containers.ts` covers only tip/info/warning/danger/details, and `custom-block.css` styles info/note/tip/important/warning/danger/caution/details with no `success` rule. The `--vp-c-success-*` variables exist in `vars.css` but are consumed only by the diff-add line colour, so the palette is already there and unused.
|
||||
|
||||
**Recommendation.** Low effort, but it is a maintainer call on whether the fixed container set grows. Note the decision has shifted since the PR was written: `customContainers` now lets a user register `::: success` themselves (it renders `<div class="success custom-block">`), so the only missing piece is the default green styling plus a label — a CSS block mirroring `.custom-block.note` and one entry in `containerLabels`/locale titles. If you take it, the Chinese label translation in the PR needs a native check; if you decline, close the loop by documenting the `customContainers` route rather than leaving it to a stale-bot.
|
||||
Loading…
Reference in new issue