From 10e1780dcc023e44f2edffe39618c6dda3473280 Mon Sep 17 00:00:00 2001
From: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>
Date: Thu, 3 Sep 2026 00:30:11 +0530
Subject: [PATCH] feat(theme): render the not-found page through the layout

The default theme exports `NotFound.vue` as its `NotFound` component and
renders the not-found page like any page: an authored `404.md` as a doc
page without sidebar, aside or edit link unless frontmatter says otherwise,
the synthesized one bare. `useLayout()` gains `layout`, the resolved layout
name. Pages outside the sidebar no longer get the first sidebar entry as
their next link. The home link of the not-found page has no `aria-label`
anymore: it differed from the visible text, which fails WCAG 2.5.3.

BREAKING CHANGE: the `not-found` layout slot is removed, write a `404.md`
instead; `themeConfig.notFound.linkLabel` is removed, the visible
`linkText` is the accessible name.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/es/config.ts                             |  1 -
 docs/fa/config.ts                             |  1 -
 docs/ko/config.ts                             |  1 -
 docs/pt/config.ts                             |  1 -
 docs/ru/config.ts                             |  1 -
 docs/zh/config.ts                             |  1 -
 src/client/theme-default/Layout.vue           |  1 -
 src/client/theme-default/NotFound.vue         |  6 +----
 .../theme-default/components/VPContent.vue    | 15 ++++-------
 .../theme-default/components/VPDocFooter.vue  |  4 ++-
 .../theme-default/composables/layout.ts       | 21 +++++++++++++---
 .../theme-default/composables/prev-next.ts    | 25 +++++++++++--------
 src/client/theme-default/without-fonts.ts     |  2 ++
 types/default-theme.d.ts                      | 13 +++++-----
 14 files changed, 49 insertions(+), 44 deletions(-)

diff --git a/docs/es/config.ts b/docs/es/config.ts
index 43b2dfb7..2cc660cd 100644
--- a/docs/es/config.ts
+++ b/docs/es/config.ts
@@ -62,7 +62,6 @@ export default defineAdditionalConfig({
       title: 'PÁGINA NO ENCONTRADA',
       quote:
         'Pero si no cambias de dirección y sigues buscando, podrías terminar donde te diriges.',
-      linkLabel: 'ir a inicio',
       linkText: 'Llévame a inicio'
     },
 
diff --git a/docs/fa/config.ts b/docs/fa/config.ts
index 2b7dcc1c..3e438c82 100644
--- a/docs/fa/config.ts
+++ b/docs/fa/config.ts
@@ -70,7 +70,6 @@ export default defineAdditionalConfig({
       title: 'صفحه پیدا نشد',
       quote:
         'اما اگر جهت خود را تغییر ندهید و همچنان به جستجو ادامه دهید، ممکن است در نهایت به جایی برسید که در حال رفتن به آن هستید.',
-      linkLabel: 'برو به خانه',
       linkText: 'من را به خانه ببر'
     },
 
diff --git a/docs/ko/config.ts b/docs/ko/config.ts
index 2226254d..2768ca14 100644
--- a/docs/ko/config.ts
+++ b/docs/ko/config.ts
@@ -62,7 +62,6 @@ export default defineAdditionalConfig({
       title: '페이지를 찾을 수 없습니다',
       quote:
         '방향을 바꾸지 않고 계속 찾다 보면 결국 당신이 가고 있는 곳에 도달할 수도 있습니다.',
-      linkLabel: '홈으로 가기',
       linkText: '집으로 데려가줘'
     },
 
diff --git a/docs/pt/config.ts b/docs/pt/config.ts
index 9b99bef3..6bf1fbcb 100644
--- a/docs/pt/config.ts
+++ b/docs/pt/config.ts
@@ -62,7 +62,6 @@ export default defineAdditionalConfig({
       title: 'PÁGINA NÃO ENCONTRADA',
       quote:
         'Mas se você não mudar de direção e continuar procurando, pode acabar onde está indo.',
-      linkLabel: 'ir para a página inicial',
       linkText: 'Me leve para casa'
     },
 
diff --git a/docs/ru/config.ts b/docs/ru/config.ts
index 4a4fa3d7..d12ff093 100644
--- a/docs/ru/config.ts
+++ b/docs/ru/config.ts
@@ -60,7 +60,6 @@ export default defineAdditionalConfig({
       title: 'СТРАНИЦА НЕ НАЙДЕНА',
       quote:
         'Но если ты не изменишь направление и продолжишь искать, ты можешь оказаться там, куда направляешься.',
-      linkLabel: 'перейти на главную',
       linkText: 'Отведи меня домой'
     },
 
diff --git a/docs/zh/config.ts b/docs/zh/config.ts
index 41a557a5..fc52c087 100644
--- a/docs/zh/config.ts
+++ b/docs/zh/config.ts
@@ -62,7 +62,6 @@ export default defineAdditionalConfig({
       title: '页面未找到',
       quote:
         '但如果你不改变方向，并且继续寻找，你可能最终会到达你所前往的地方。',
-      linkLabel: '前往首页',
       linkText: '带我回首页'
     },
 
diff --git a/src/client/theme-default/Layout.vue b/src/client/theme-default/Layout.vue
index c9a4af67..f0e7ef51 100644
--- a/src/client/theme-default/Layout.vue
+++ b/src/client/theme-default/Layout.vue
@@ -64,7 +64,6 @@ provide(layoutInfoInjectionKey, { heroImageSlotExists })
       <template #page-top><slot name="page-top" /></template>
       <template #page-bottom><slot name="page-bottom" /></template>
 
-      <template #not-found><slot name="not-found" /></template>
       <template #home-hero-before><slot name="home-hero-before" /></template>
       <template #home-hero-info-before><slot name="home-hero-info-before" /></template>
       <template #home-hero-info><slot name="home-hero-info" /></template>
diff --git a/src/client/theme-default/NotFound.vue b/src/client/theme-default/NotFound.vue
index 5805ac80..1cf11cbe 100644
--- a/src/client/theme-default/NotFound.vue
+++ b/src/client/theme-default/NotFound.vue
@@ -21,11 +21,7 @@ const { currentLang } = useLangs()
     </blockquote>
 
     <div class="action">
-      <a
-        class="link"
-        :href="withBase(theme.notFound?.link ?? currentLang.link)"
-        :aria-label="theme.notFound?.linkLabel ?? 'go to home'"
-      >
+      <a class="link" :href="withBase(theme.notFound?.link ?? currentLang.link)">
         {{ theme.notFound?.linkText ?? 'Take me home' }}
       </a>
     </div>
diff --git a/src/client/theme-default/components/VPContent.vue b/src/client/theme-default/components/VPContent.vue
index ef58f217..6bfdd845 100644
--- a/src/client/theme-default/components/VPContent.vue
+++ b/src/client/theme-default/components/VPContent.vue
@@ -1,15 +1,12 @@
 <script setup lang="ts">
 import { resolveDynamicComponent } from 'vue'
 
-import { useData } from '../composables/data'
 import { useLayout } from '../composables/layout'
-import NotFound from '../NotFound.vue'
 import VPDoc from './VPDoc.vue'
 import VPHome from './VPHome.vue'
 import VPPage from './VPPage.vue'
 
-const { page, frontmatter } = useData()
-const { isHome, hasSidebar } = useLayout()
+const { isHome, hasSidebar, layout } = useLayout()
 
 function isRegistered(component: string): boolean {
   return typeof resolveDynamicComponent(component) !== 'string'
@@ -22,14 +19,12 @@ function isRegistered(component: string): boolean {
     id="VPContent"
     :class="{ 'has-sidebar': hasSidebar, 'is-home': isHome }"
   >
-    <slot name="not-found" v-if="page.isNotFound"><NotFound /></slot>
-
-    <VPPage v-else-if="frontmatter.layout === 'page' && !isRegistered('page')">
+    <VPPage v-if="layout === 'page' && !isRegistered('page')">
       <template #page-top><slot name="page-top" /></template>
       <template #page-bottom><slot name="page-bottom" /></template>
     </VPPage>
 
-    <VPHome v-else-if="frontmatter.layout === 'home' && !isRegistered('home')">
+    <VPHome v-else-if="layout === 'home' && !isRegistered('home')">
       <template #home-hero-before><slot name="home-hero-before" /></template>
       <template #home-hero-info-before><slot name="home-hero-info-before" /></template>
       <template #home-hero-info><slot name="home-hero-info" /></template>
@@ -42,7 +37,7 @@ function isRegistered(component: string): boolean {
       <template #home-features-after><slot name="home-features-after" /></template>
     </VPHome>
 
-    <VPDoc v-else-if="(!frontmatter.layout || frontmatter.layout === 'doc') && !isRegistered('doc')">
+    <VPDoc v-else-if="layout === 'doc' && !isRegistered('doc')">
       <template #doc-top><slot name="doc-top" /></template>
       <template #doc-bottom><slot name="doc-bottom" /></template>
 
@@ -58,7 +53,7 @@ function isRegistered(component: string): boolean {
       <template #aside-bottom><slot name="aside-bottom" /></template>
     </VPDoc>
 
-    <component v-else :is="frontmatter.layout || 'doc'" />
+    <component v-else :is="layout" />
   </div>
 </template>
 
diff --git a/src/client/theme-default/components/VPDocFooter.vue b/src/client/theme-default/components/VPDocFooter.vue
index 405e9815..c1d90a34 100644
--- a/src/client/theme-default/components/VPDocFooter.vue
+++ b/src/client/theme-default/components/VPDocFooter.vue
@@ -13,7 +13,9 @@ const editLink = useEditLink()
 const control = usePrevNext()
 
 const hasEditLink = computed(
-  () => theme.value.editLink && frontmatter.value.editLink !== false
+  () =>
+    theme.value.editLink &&
+    (frontmatter.value.editLink ?? !page.value.isNotFound) !== false
 )
 const hasLastUpdated = computed(() => page.value.lastUpdated)
 const showFooter = computed(
diff --git a/src/client/theme-default/composables/layout.ts b/src/client/theme-default/composables/layout.ts
index 542bbc2a..802f7041 100644
--- a/src/client/theme-default/composables/layout.ts
+++ b/src/client/theme-default/composables/layout.ts
@@ -21,15 +21,26 @@ const sidebar = shallowRef<DefaultTheme.SidebarItem[]>([])
 const isDesktop = useMediaQuery('(min-width: 60rem)')
 
 export function useLayout(): DefaultTheme.Layout {
-  const { frontmatter, theme } = useData()
+  const { frontmatter, page, theme } = useData()
+
+  // a not-found page reads like a doc page without the doc chrome; the one
+  // synthesized from the theme's `NotFound` component has no prose to style
+  const isNotFound = computed(() => !!page.value.isNotFound)
+
+  const layout = computed<string>(() => {
+    return (
+      frontmatter.value.layout ||
+      (isNotFound.value && !page.value.filePath ? 'page' : 'doc')
+    )
+  })
 
   const isHome = computed(() => {
-    return !!(frontmatter.value.isHome ?? frontmatter.value.layout === 'home')
+    return !!(frontmatter.value.isHome ?? layout.value === 'home')
   })
 
   const hasSidebar = computed(() => {
     return (
-      frontmatter.value.sidebar !== false &&
+      (frontmatter.value.sidebar ?? !isNotFound.value) !== false &&
       sidebar.value.length > 0 &&
       !isHome.value
     )
@@ -43,7 +54,8 @@ export function useLayout(): DefaultTheme.Layout {
 
   const hasAside = computed(() => {
     if (isHome.value) return false
-    if (frontmatter.value.aside != null) return !!frontmatter.value.aside
+    const aside = frontmatter.value.aside ?? (isNotFound.value ? false : null)
+    if (aside != null) return !!aside
     return theme.value.aside !== false
   })
 
@@ -59,6 +71,7 @@ export function useLayout(): DefaultTheme.Layout {
   })
 
   return {
+    layout,
     isHome,
     sidebar: shallowReadonly(sidebar),
     sidebarGroups,
diff --git a/src/client/theme-default/composables/prev-next.ts b/src/client/theme-default/composables/prev-next.ts
index 52a0d791..ef6f0af6 100644
--- a/src/client/theme-default/composables/prev-next.ts
+++ b/src/client/theme-default/composables/prev-next.ts
@@ -22,6 +22,11 @@ export function usePrevNext() {
       return isActive(page.value.relativePath, '', link.link, false, true)
     })
 
+    // a page outside the sidebar (the not-found page, for one) has no
+    // neighbours; `candidates[-1 + 1]` would otherwise elect the first entry
+    const prevCandidate = index === -1 ? undefined : candidates[index - 1]
+    const nextCandidate = index === -1 ? undefined : candidates[index + 1]
+
     const hidePrev =
       (theme.value.docFooter?.prev === false && !frontmatter.value.prev) ||
       frontmatter.value.prev === false
@@ -40,20 +45,20 @@ export function usePrevNext() {
                 : typeof frontmatter.value.prev === 'object'
                   ? frontmatter.value.prev.text
                   : undefined) ??
-              candidates[index - 1]?.docFooterText ??
-              candidates[index - 1]?.text,
+              prevCandidate?.docFooterText ??
+              prevCandidate?.text,
             link:
               (typeof frontmatter.value.prev === 'object'
                 ? frontmatter.value.prev.link
-                : undefined) ?? candidates[index - 1]?.link,
+                : undefined) ?? prevCandidate?.link,
             target:
               (typeof frontmatter.value.prev === 'object'
                 ? frontmatter.value.prev.target
-                : undefined) ?? candidates[index - 1]?.target,
+                : undefined) ?? prevCandidate?.target,
             rel:
               (typeof frontmatter.value.prev === 'object'
                 ? frontmatter.value.prev.rel
-                : undefined) ?? candidates[index - 1]?.rel
+                : undefined) ?? prevCandidate?.rel
           },
       next: hideNext
         ? undefined
@@ -64,20 +69,20 @@ export function usePrevNext() {
                 : typeof frontmatter.value.next === 'object'
                   ? frontmatter.value.next.text
                   : undefined) ??
-              candidates[index + 1]?.docFooterText ??
-              candidates[index + 1]?.text,
+              nextCandidate?.docFooterText ??
+              nextCandidate?.text,
             link:
               (typeof frontmatter.value.next === 'object'
                 ? frontmatter.value.next.link
-                : undefined) ?? candidates[index + 1]?.link,
+                : undefined) ?? nextCandidate?.link,
             target:
               (typeof frontmatter.value.next === 'object'
                 ? frontmatter.value.next.target
-                : undefined) ?? candidates[index + 1]?.target,
+                : undefined) ?? nextCandidate?.target,
             rel:
               (typeof frontmatter.value.next === 'object'
                 ? frontmatter.value.next.rel
-                : undefined) ?? candidates[index + 1]?.rel
+                : undefined) ?? nextCandidate?.rel
           }
     }
   })
diff --git a/src/client/theme-default/without-fonts.ts b/src/client/theme-default/without-fonts.ts
index 91ae2a46..b19aca87 100644
--- a/src/client/theme-default/without-fonts.ts
+++ b/src/client/theme-default/without-fonts.ts
@@ -12,6 +12,7 @@ import type { Theme } from 'vitepress'
 
 import VPBadge from './components/VPBadge.vue'
 import Layout from './Layout.vue'
+import NotFound from './NotFound.vue'
 
 export { default as VPBadge } from './components/VPBadge.vue'
 export { default as VPButton } from './components/VPButton.vue'
@@ -37,6 +38,7 @@ export { useLayout } from './composables/layout'
 
 const theme: Theme = {
   Layout,
+  NotFound,
   enhanceApp: ({ app }) => {
     app.component('Badge', VPBadge)
   }
diff --git a/types/default-theme.d.ts b/types/default-theme.d.ts
index 8120fead..2313120e 100644
--- a/types/default-theme.d.ts
+++ b/types/default-theme.d.ts
@@ -10,6 +10,12 @@ export namespace DefaultTheme {
    * The layout state returned by `useLayout` from `vitepress/theme`.
    */
   export interface Layout {
+    /**
+     * The layout the current page renders with: its `layout` frontmatter,
+     * or the default (`doc`, and `page` for the not-found page synthesized
+     * from the theme).
+     */
+    layout: ComputedRef<string>
     isHome: ComputedRef<boolean>
 
     sidebar: Readonly<ShallowRef<SidebarItem[]>>
@@ -505,13 +511,6 @@ export namespace DefaultTheme {
      */
     link?: string
 
-    /**
-     * Set aria label for home link.
-     *
-     * @default 'go to home'
-     */
-    linkLabel?: string
-
     /**
      * Set custom home link text.
      *