Runtime API
VitePress offers several built-in APIs to let you access app data. VitePress also comes with a few built-in components that can be used globally.
The helper methods are globally importable from vitepress and are typically used in custom theme Vue components. However, they are also usable inside .md pages because markdown files are compiled into Vue Single-File Components.
Methods that start with use* indicates that it is a Vue 3 Composition API function ("Composable") that can only be used inside setup() or <script setup>.
useData composable
Returns page-specific data. The returned object has the following type:
interface VitePressData<T = any> {
/**
* Site-level metadata
*/
site: Ref<SiteData<T>>
/**
* themeConfig from .vitepress/config.js
*/
theme: Ref<T>
/**
* Page-level metadata
*/
page: Ref<PageData>
/**
* Page frontmatter
*/
frontmatter: Ref<PageData['frontmatter']>
/**
* Dynamic route params
*/
params: Ref<PageData['params']>
title: Ref<string>
description: Ref<string>
lang: Ref<string>
isDark: Ref<boolean>
dir: Ref<string>
localeIndex: Ref<string>
}
interface PageData {
title: string
titleTemplate?: string | boolean
description: string
relativePath: string
filePath: string,
headers: Header[]
frontmatter: Record<string, any>
params?: Record<string, any>
isNotFound?: boolean
lastUpdated?: number
}interface VitePressData<T = any> {
/**
* Site-level metadata
*/
site: Ref<SiteData<T>>
/**
* themeConfig from .vitepress/config.js
*/
theme: Ref<T>
/**
* Page-level metadata
*/
page: Ref<PageData>
/**
* Page frontmatter
*/
frontmatter: Ref<PageData['frontmatter']>
/**
* Dynamic route params
*/
params: Ref<PageData['params']>
title: Ref<string>
description: Ref<string>
lang: Ref<string>
isDark: Ref<boolean>
dir: Ref<string>
localeIndex: Ref<string>
}
interface PageData {
title: string
titleTemplate?: string | boolean
description: string
relativePath: string
filePath: string,
headers: Header[]
frontmatter: Record<string, any>
params?: Record<string, any>
isNotFound?: boolean
lastUpdated?: number
}Example:
<script setup>
import { useData } from 'vitepress'
const { theme } = useData()
</script>
<template>
<h1>{{ theme.footer.copyright }}</h1>
</template><script setup>
import { useData } from 'vitepress'
const { theme } = useData()
</script>
<template>
<h1>{{ theme.footer.copyright }}</h1>
</template>useRoute composable
Returns the current route object with the following type:
interface Route {
path: string
data: PageData
component: Component | null
}interface Route {
path: string
data: PageData
component: Component | null
}useRouter composable
Returns the VitePress router instance so you can programmatically navigate to another page.
interface Router {
/**
* Current route.
*/
route: Route
/**
* Navigate to a new URL.
*/
go: (to?: string) => Promise<void>
/**
* Called before the route changes. Return `false` to cancel the navigation.
*/
onBeforeRouteChange?: (to: string) => Awaitable<void | boolean>
/**
* Called before the page component is loaded (after the history state is
* updated). Return `false` to cancel the navigation.
*/
onBeforePageLoad?: (to: string) => Awaitable<void | boolean>
/**
* Called after the route changes.
*/
onAfterRouteChanged?: (to: string) => Awaitable<void>
}interface Router {
/**
* Current route.
*/
route: Route
/**
* Navigate to a new URL.
*/
go: (to?: string) => Promise<void>
/**
* Called before the route changes. Return `false` to cancel the navigation.
*/
onBeforeRouteChange?: (to: string) => Awaitable<void | boolean>
/**
* Called before the page component is loaded (after the history state is
* updated). Return `false` to cancel the navigation.
*/
onBeforePageLoad?: (to: string) => Awaitable<void | boolean>
/**
* Called after the route changes.
*/
onAfterRouteChanged?: (to: string) => Awaitable<void>
}withBase helper
- Type:
(path: string) => string
Appends the configured base to a given URL path. Also see Base URL.
<Content /> component
The <Content /> component displays the rendered markdown contents. Useful when creating your own theme.
<template>
<h1>Custom Layout!</h1>
<Content />
</template><template>
<h1>Custom Layout!</h1>
<Content />
</template><ClientOnly /> component
The <ClientOnly /> component renders its slot only at client side.
Because VitePress applications are server-rendered in Node.js when generating static builds, any Vue usage must conform to the universal code requirements. In short, make sure to only access Browser / DOM APIs in beforeMount or mounted hooks.
If you are using or demoing components that are not SSR-friendly (for example, contain custom directives), you can wrap them inside the ClientOnly component.
<ClientOnly>
<NonSSRFriendlyComponent />
</ClientOnly><ClientOnly>
<NonSSRFriendlyComponent />
</ClientOnly>- Related: SSR Compatibility
$frontmatter template global
Directly access current page's frontmatter data in Vue expressions.
---
title: Hello
---
# {{ $frontmatter.title }}---
title: Hello
---
# {{ $frontmatter.title }}$params template global
Directly access current page's dynamic route params in Vue expressions.
- package name: {{ $params.pkg }}
- version: {{ $params.version }}- package name: {{ $params.pkg }}
- version: {{ $params.version }}