fix types, update docs, format, merge useLocalNav to useLayout too, fix typo in leftAside,

docs/en/reference/default-theme-config.md

@@ -457,3 +457,38 @@ Can be used to customize the label of the skip to content link. This link is sho
 - Default: `false`
 
 Whether to show an external link icon next to external links in markdown.
+
+## `useLayout` <Badge type="info" text="composable" />
+
+Returns layout-related data. The returned object has the following type:
+
+```ts
+interface {
+  isHome: ComputedRef<boolean>
+
+  sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
+  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
+  hasSidebar: ComputedRef<boolean>
+  isSidebarEnabled: ComputedRef<boolean>
+
+  hasAside: ComputedRef<boolean>
+  leftAside: ComputedRef<boolean>
+
+  headers: ShallowRef<MenuItem>
+  hasLocalNav: ComputedRef<boolean>
+}
+```
+
+**Example:**
+
+```vue
+<script setup>
+import { useLayout } from 'vitepress/theme'
+
+const { hasSidebar } = useLayout()
+</script>
+
+<template>
+  <div v-if="hasSidebar">Only show when sidebar exists</div>
+</template>
+```

docs/en/reference/default-theme-sidebar.md

@@ -180,36 +180,3 @@ export default {
   }
 }
 ```
-
-## `useSidebar` <Badge type="info" text="composable" />
-
-Returns sidebar-related data. The returned object has the following type:
-
-```ts
-export interface DocSidebar {
-  isOpen: Ref<boolean>
-  sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
-  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
-  hasSidebar: ComputedRef<boolean>
-  hasAside: ComputedRef<boolean>
-  leftAside: ComputedRef<boolean>
-  isSidebarEnabled: ComputedRef<boolean>
-  open: () => void
-  close: () => void
-  toggle: () => void
-}
-```
-
-**Example:**
-
-```vue
-<script setup>
-import { useSidebar } from 'vitepress/theme'
-
-const { hasSidebar } = useSidebar()
-</script>
-
-<template>
-  <div v-if="hasSidebar">Only show when sidebar exists</div>
-</template>
-```

docs/en/reference/frontmatter-config.md

@@ -225,3 +225,16 @@ Then you can customize styles of this specific page in `.vitepress/theme/custom.
   /* page-specific styles */
 }
 ```
+
+### isHome
+
+- Type: `boolean`
+
+The default theme relies on checks like `frontmatter.layout === 'home'` to determine if the current page is the home page.\
+This is useful when you want to force show the home page elements in a custom layout.
+
+```yaml
+---
+isHome: true
+---
+```

docs/es/reference/default-theme-sidebar.md

@@ -181,36 +181,3 @@ export default {
   }
 }
 ```
-
-## `useSidebar` <Badge type="info" text="composable" />
-
-Devuelve datos relacionados con la barra lateral. El objeto devuelto tiene el siguiente tipo:
-
-```ts
-export interface DocSidebar {
-  isOpen: Ref<boolean>
-  sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
-  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
-  hasSidebar: ComputedRef<boolean>
-  hasAside: ComputedRef<boolean>
-  leftAside: ComputedRef<boolean>
-  isSidebarEnabled: ComputedRef<boolean>
-  open: () => void
-  close: () => void
-  toggle: () => void
-}
-```
-
-**Exemplo:**
-
-```vue
-<script setup>
-import { useSidebar } from 'vitepress/theme'
-
-const { hasSidebar } = useSidebar()
-</script>
-
-<template>
-  <div v-if="hasSidebar">Sólo visible cuando existe la barra lateral</div>
-</template>
-```

docs/fa/reference/default-theme-sidebar.md

@@ -178,38 +178,3 @@ export default {
   }
 }
 ```
-
-## `useSidebar` <Badge type="info" text="composable" /> {#usesidebar}
-
-داده‌های مربوط به نوار کناری را برمی‌گرداند. شیء برگردانده شده دارای نوع‌های زیر است:
-
-```ts
-export interface DocSidebar {
-  isOpen: Ref<boolean>
-  sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
-  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
-  hasSidebar: ComputedRef<boolean>
-  hasAside: ComputedRef<boolean>
-  leftAside: ComputedRef<boolean>
-  isSidebarEnabled: ComputedRef<boolean>
-  open: () => void
-  close: () => void
-  toggle: () => void
-}
-```
-
-**مثال:**
-
-```vue
-<script setup>
-import { useSidebar } from 'vitepress/theme'
-
-const { hasSidebar } = useSidebar()
-</script>
-
-<template>
-  <div v-if="hasSidebar">فقط ن
-
-مایش داده شود زمانی که نوار کناری وجود دارد</div>
-</template>
-```

docs/ko/reference/default-theme-sidebar.md

@@ -180,36 +180,3 @@ export default {
   }
 }
 ```
-
-## `useSidebar` <Badge type="info" text="composable" />
-
-사이드바 관련 데이터를 반환합니다. 반환된 객체는 다음과 같은 타입을 가집니다:
-
-```ts
-export interface DocSidebar {
-  isOpen: Ref<boolean>
-  sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
-  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
-  hasSidebar: ComputedRef<boolean>
-  hasAside: ComputedRef<boolean>
-  leftAside: ComputedRef<boolean>
-  isSidebarEnabled: ComputedRef<boolean>
-  open: () => void
-  close: () => void
-  toggle: () => void
-}
-```
-
-**예제:**
-
-```vue
-<script setup>
-import { useSidebar } from 'vitepress/theme'
-
-const { hasSidebar } = useSidebar()
-</script>
-
-<template>
-  <div v-if="hasSidebar">사이드바가 있을 때만 보여줍니다</div>
-</template>
-```

docs/pt/reference/default-theme-sidebar.md

@@ -180,36 +180,3 @@ export default {
   }
 }
 ```
-
-## `useSidebar` <Badge type="info" text="composable" />
-
-Retorna dados relacionados à barra lateral. O objeto retornado tem o seguinte tipo:
-
-```ts
-export interface DocSidebar {
-  isOpen: Ref<boolean>
-  sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
-  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
-  hasSidebar: ComputedRef<boolean>
-  hasAside: ComputedRef<boolean>
-  leftAside: ComputedRef<boolean>
-  isSidebarEnabled: ComputedRef<boolean>
-  open: () => void
-  close: () => void
-  toggle: () => void
-}
-```
-
-**Exemplo:**
-
-```vue
-<script setup>
-import { useSidebar } from 'vitepress/theme'
-
-const { hasSidebar } = useSidebar()
-</script>
-
-<template>
-  <div v-if="hasSidebar">Visível apenas quando a barra lateral existe</div>
-</template>
-```

docs/ru/reference/default-theme-sidebar.md

@@ -178,36 +178,3 @@ export default {
   }
 }
 ```
-
-## `useSidebar` <Badge type="info" text="композабл" /> {#usesidebar}
-
-Возвращает данные, связанные с сайдбаром. Возвращаемый объект имеет следующий тип:
-
-```ts
-export interface DocSidebar {
-  isOpen: Ref<boolean>
-  sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
-  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
-  hasSidebar: ComputedRef<boolean>
-  hasAside: ComputedRef<boolean>
-  leftAside: ComputedRef<boolean>
-  isSidebarEnabled: ComputedRef<boolean>
-  open: () => void
-  close: () => void
-  toggle: () => void
-}
-```
-
-**Пример:**
-
-```vue
-<script setup>
-import { useSidebar } from 'vitepress/theme'
-
-const { hasSidebar } = useSidebar()
-</script>
-
-<template>
-  <div v-if="hasSidebar">Показывать только при наличии сайдбара</div>
-</template>
-```

docs/zh/reference/default-theme-sidebar.md

@@ -178,36 +178,3 @@ export default {
   }
 }
 ```
-
-## `useSidebar` <Badge type="info" text="composable" />
-
-返回侧边栏相关数据。返回的对象具有以下类型：
-
-```ts
-export interface DocSidebar {
-  isOpen: Ref<boolean>
-  sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
-  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
-  hasSidebar: ComputedRef<boolean>
-  hasAside: ComputedRef<boolean>
-  leftAside: ComputedRef<boolean>
-  isSidebarEnabled: ComputedRef<boolean>
-  open: () => void
-  close: () => void
-  toggle: () => void
-}
-```
-
-**示例：**
-
-```vue
-<script setup>
-import { useSidebar } from 'vitepress/theme'
-
-const { hasSidebar } = useSidebar()
-</script>
-
-<template>
-  <div v-if="hasSidebar">Only show when sidebar exists</div>
-</template>
-```

src/client/theme-default/components/VPContent.vue

@@ -14,10 +14,7 @@ const { isHome, hasSidebar } = useLayout()
   <div
     class="VPContent"
     id="VPContent"
-    :class="{
-      'has-sidebar': hasSidebar,
-      'is-home': isHome
-    }"
+    :class="{ 'has-sidebar': hasSidebar, 'is-home': isHome }"
   >
     <slot name="not-found" v-if="page.isNotFound"><NotFound /></slot>
 

src/client/theme-default/components/VPDocAsideOutline.vue

@@ -1,12 +1,12 @@
 <script setup lang="ts">
 import { onContentUpdated } from 'vitepress'
 import { ref, shallowRef } from 'vue'
+import type { MenuItem } from '../../shared'
 import { useData } from '../composables/data'
 import {
   getHeaders,
   resolveTitle,
-  useActiveAnchor,
-  type MenuItem
+  useActiveAnchor
 } from '../composables/outline'
 import VPDocOutlineItem from './VPDocOutlineItem.vue'
 

src/client/theme-default/components/VPDocOutlineItem.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { MenuItem } from '../composables/outline'
+import type { MenuItem } from '../../shared'
 
 defineProps<{
   headers: MenuItem[]
@@ -16,7 +16,9 @@ function onClick({ target: el }: Event) {
 <template>
   <ul class="VPDocOutlineItem" :class="root ? 'root' : 'nested'">
     <li v-for="{ children, link, title } in headers">
-      <a class="outline-link" :href="link" @click="onClick" :title="title">{{ title }}</a>
+      <a class="outline-link" :href="link" @click="onClick" :title="title">
+        {{ title }}
+      </a>
       <template v-if="children?.length">
         <VPDocOutlineItem :headers="children" />
       </template>

src/client/theme-default/components/VPLocalNav.vue

@@ -3,9 +3,8 @@ import { useWindowScroll } from '@vueuse/core'
 import { onContentUpdated } from 'vitepress'
 import { computed, onMounted, ref } from 'vue'
 import { useData } from '../composables/data'
-import { useLocalNav } from '../composables/local-nav'
-import { getHeaders } from '../composables/outline'
 import { useLayout } from '../composables/layout'
+import { getHeaders } from '../composables/outline'
 import VPLocalNavOutlineDropdown from './VPLocalNavOutlineDropdown.vue'
 
 defineProps<{
@@ -17,8 +16,7 @@ defineEmits<{
 }>()
 
 const { theme, frontmatter } = useData()
-const { hasSidebar } = useLayout()
-const { headers } = useLocalNav()
+const { hasSidebar, headers } = useLayout()
 const { y } = useWindowScroll()
 
 const navHeight = ref(0)

src/client/theme-default/components/VPLocalNavOutlineDropdown.vue

@@ -2,8 +2,9 @@
 import { onKeyStroke } from '@vueuse/core'
 import { onContentUpdated } from 'vitepress'
 import { nextTick, ref, watch } from 'vue'
+import type { MenuItem } from '../../shared'
 import { useData } from '../composables/data'
-import { resolveTitle, type MenuItem } from '../composables/outline'
+import { resolveTitle } from '../composables/outline'
 import VPDocOutlineItem from './VPDocOutlineItem.vue'
 
 const props = defineProps<{
@@ -125,7 +126,7 @@ function scrollToTop() {
   vertical-align: middle;
   margin-left: 2px;
   font-size: 14px;
-  transform: rotate(0)/*rtl:rotate(180deg)*/;
+  transform: rotate(0) /*rtl:rotate(180deg)*/;
   transition: transform 0.25s;
 }
 

src/client/theme-default/composables/layout.ts

@@ -1,16 +1,17 @@
 import { useMediaQuery } from '@vueuse/core'
-import { computed, ref, watch } from 'vue'
+import { onContentUpdated } from 'vitepress'
+import { computed, ref, shallowRef, watch } from 'vue'
+import type { MenuItem } from '../../shared'
 import { getSidebar, getSidebarGroups } from '../support/sidebar'
 import { useData } from './data'
+import { getHeaders } from './outline'
 
 export function useLayout() {
   const { frontmatter, page, theme } = useData()
   const is960 = useMediaQuery('(min-width: 960px)')
 
   const isHome = computed(() => {
-    if (frontmatter.value.isHome !== undefined)
-      return Boolean(frontmatter.value.isHome)
-    else return frontmatter.value.layout === 'home'
+    return !!(frontmatter.value.isHome ?? frontmatter.value.layout === 'home')
   })
 
   const _sidebar = computed(() => {
@@ -35,11 +36,10 @@ export function useLayout() {
   })
 
   const leftAside = computed(() => {
-    if (hasAside)
-      return frontmatter.value.aside == null
-        ? theme.value.aside === 'left'
-        : frontmatter.value.aside === 'left'
-    return false
+    if (!hasAside.value) return false
+    return frontmatter.value.aside == null
+      ? theme.value.aside === 'left'
+      : frontmatter.value.aside === 'left'
   })
 
   const hasAside = computed(() => {
@@ -54,6 +54,16 @@ export function useLayout() {
     return hasSidebar.value ? getSidebarGroups(sidebar.value) : []
   })
 
+  const headers = shallowRef<MenuItem[]>([])
+
+  const hasLocalNav = computed(() => {
+    return headers.value.length > 0
+  })
+
+  onContentUpdated(() => {
+    headers.value = getHeaders(frontmatter.value.outline ?? theme.value.outline)
+  })
+
   return {
     isHome,
     sidebar,
@@ -61,6 +71,8 @@ export function useLayout() {
     hasSidebar,
     hasAside,
     leftAside,
-    isSidebarEnabled
+    isSidebarEnabled,
+    headers,
+    hasLocalNav
   }
 }

src/client/theme-default/composables/local-nav.ts

@@ -1,24 +0,0 @@
-import { onContentUpdated } from 'vitepress'
-import type { DefaultTheme } from 'vitepress/theme'
-import { computed, shallowRef } from 'vue'
-import { getHeaders, type MenuItem } from '../composables/outline'
-import { useData } from './data'
-
-export function useLocalNav(): DefaultTheme.DocLocalNav {
-  const { theme, frontmatter } = useData()
-
-  const headers = shallowRef<MenuItem[]>([])
-
-  const hasLocalNav = computed(() => {
-    return headers.value.length > 0
-  })
-
-  onContentUpdated(() => {
-    headers.value = getHeaders(frontmatter.value.outline ?? theme.value.outline)
-  })
-
-  return {
-    headers,
-    hasLocalNav
-  }
-}

src/client/theme-default/composables/outline.ts

@@ -1,7 +1,7 @@
 import { getScrollOffset } from 'vitepress'
 import type { DefaultTheme } from 'vitepress/theme'
 import { onMounted, onUnmounted, onUpdated, type Ref } from 'vue'
-import type { Header } from '../../shared'
+import type { MenuItem } from '../../shared'
 import { throttleAndDebounce } from '../support/utils'
 import { useAside } from './aside'
 
@@ -10,11 +10,6 @@ const ignoreRE = /\b(?:VPBadge|header-anchor|footnote-ref|ignore-header)\b/
 // cached list of anchor elements from resolveHeaders
 const resolvedHeaders: { element: HTMLHeadElement; link: string }[] = []
 
-export type MenuItem = Omit<Header, 'slug' | 'children'> & {
-  element: HTMLHeadElement
-  children?: MenuItem[]
-}
-
 export function resolveTitle(theme: DefaultTheme.Config): string {
   return (
     (typeof theme.outline === 'object' &&

src/client/theme-default/without-fonts.ts

@@ -31,7 +31,6 @@ export { default as VPTeamPage } from './components/VPTeamPage.vue'
 export { default as VPTeamPageSection } from './components/VPTeamPageSection.vue'
 export { default as VPTeamPageTitle } from './components/VPTeamPageTitle.vue'
 
-export { useLocalNav } from './composables/local-nav'
 export { useLayout } from './composables/layout'
 
 const theme: Theme = {

src/shared/shared.ts

@@ -8,6 +8,7 @@ export type {
   LocaleConfig,
   LocaleSpecificConfig,
   MarkdownEnv,
+  MenuItem,
   PageData,
   PageDataPayload,
   SiteData,

theme.d.ts

@@ -1,8 +1,9 @@
 // so that users can do `import DefaultTheme from 'vitepress/theme'`
 
-import type { DefineComponent } from 'vue'
+import type { ComputedRef, DefineComponent, ShallowRef } from 'vue'
 import type { EnhanceAppContext } from './dist/client/index.js'
 import type { DefaultTheme } from './types/default-theme.js'
+import type { MenuItem } from './types/shared.js'
 
 export type { DefaultTheme } from './types/default-theme.js'
 
@@ -12,8 +13,29 @@ declare const theme: {
 }
 
 export default theme
-export declare const useSidebar: () => DefaultTheme.DocSidebar
-export declare const useLocalNav: () => DefaultTheme.DocLocalNav
+
+export declare const useLayout: () => {
+  isHome: ComputedRef<boolean>
+
+  sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
+  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
+  hasSidebar: ComputedRef<boolean>
+  isSidebarEnabled: ComputedRef<boolean>
+
+  hasAside: ComputedRef<boolean>
+  leftAside: ComputedRef<boolean>
+
+  /**
+   * The outline headers of the current page.
+   */
+  headers: ShallowRef<MenuItem>
+  /**
+   * Whether the current page has a local nav. Local nav is shown when the
+   * "outline" is present in the page. However, note that the actual
+   * local nav visibility depends on the screen width as well.
+   */
+  hasLocalNav: ComputedRef<boolean>
+}
 
 // TODO: add props for these
 export declare const VPBadge: DefineComponent

types/default-theme.d.ts

@@ -273,22 +273,6 @@ export namespace DefaultTheme {
     target?: string
   }
 
-  /**
-   * ReturnType of `useSidebar`
-   */
-  export interface DocSidebar {
-    isOpen: Ref<boolean>
-    sidebar: ComputedRef<SidebarItem[]>
-    sidebarGroups: ComputedRef<SidebarItem[]>
-    hasSidebar: ComputedRef<boolean>
-    hasAside: ComputedRef<boolean>
-    leftAside: ComputedRef<boolean>
-    isSidebarEnabled: ComputedRef<boolean>
-    open: () => void
-    close: () => void
-    toggle: () => void
-  }
-
   // edit link -----------------------------------------------------------------
 
   export interface EditLink {
@@ -357,25 +341,6 @@ export namespace DefaultTheme {
     actionText?: string
   }
 
-  // local nav -----------------------------------------------------------------
-
-  /**
-   * ReturnType of `useLocalNav`.
-   */
-  export interface DocLocalNav {
-    /**
-     * The outline headers of the current page.
-     */
-    headers: ShallowRef<any>
-
-    /**
-     * Whether the current page has a local nav. Local nav is shown when the
-     * "outline" is present in the page. However, note that the actual
-     * local nav visibility depends on the screen width as well.
-     */
-    hasLocalNav: ComputedRef<boolean>
-  }
-
   // outline -------------------------------------------------------------------
 
   export interface Outline {

types/shared.d.ts

@@ -205,3 +205,8 @@ export interface MarkdownEnv {
   realPath?: string
   localeIndex?: string
 }
+
+export type MenuItem = Omit<Header, 'slug' | 'children'> & {
+  element: HTMLHeadElement
+  children?: MenuItem[]
+}