• Published:

VitePress provides runtime APIs that let you read application data from within the site. APIs whose names begin with use are Vue 3 composables, so they can only be called inside setup() or <script setup>.

Reading site, theme, and page data with useData

useData returns data for the current page and exposes site-level, theme-level, and page-level information. It works in both .md and .vue files.

interface VitePressData<T = any> {
  /**
   * 站点级元数据
   */
  site: Ref<SiteData<T>>
  /**
   * .vitepress/config.js 中的 themeConfig
   */
  theme: Ref<T>
  /**
   * 页面级元数据
   */
  page: Ref<PageData>
  /**
   * 页面 frontmatter
   */
  frontmatter: Ref<PageData['frontmatter']>
  /**
   * 动态路由参数
   */
  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, page, frontmatter } = useData()
</script>

主题数据
<pre>{{ theme }}</pre>

页面数据
<pre>{{ page }}</pre>

页面格式
<pre>{{ frontmatter }}</pre>

The theme ref contains themeConfig from .vitepress/config.js; page contains page metadata; frontmatter contains the current page's frontmatter.

Navigating programmatically with useRouter

useRouter returns the VitePress router instance so you can navigate to another page in code.

interface Route {
  path: string
  data: PageData
  component: Component | null
}

interface Router {
  /**
   * 当前路由
   */
  route: Route
  /**
   * 导航到新的 URL
   */
  go: (to?: string) => Promise<void>
  /**
   * 在路由更改前调用。返回 `false` 表示取消导航
   */
  onBeforeRouteChange?: (to: string) => Awaitable<void | boolean>
  /**
   * 在页面组件加载前（history 状态更新后）调用。返回 `false` 表示取消导航
   */
  onBeforePageLoad?: (to: string) => Awaitable<void | boolean>
  /**
   * 在页面组件加载后（页面组件实际更新前）调用
   */
  onAfterPageLoad?: (to: string) => Awaitable<void>
  /**
   * 在路由更改后调用
   */
  onAfterRouteChanged?: (to: string) => Awaitable<void>
}

<a @click="goUseRouter">点我去 userouter</a>

<script setup>
import { useRouter } from 'vitepress'

const routeData = useRouter()

const goUseRouter = () => {
  routeData.go(routeData.route.path + '#userouter')
}
</script>

In the example, the click handler takes the current route path and appends #userouter, then calls go to navigate to that anchor.

Resolving URLs with withBase

withBase appends the configured URL path—the base URL—to the path you pass in. The path may be under the root. For background, see the Base URL concept.

withBase(path: string) => string

<img width="100" :src="withBase('../../logo.png')" alt="head-avatar" />
<img width="100" :src="withBase(theme.logoPath)" alt="head-avatar" />

<script setup lang="ts">
import { withBase } from 'vitepress'

const { theme } = useData()
</script>

../../logo.png is the logo's path relative to the document, while theme.logoPath is the logo location from site data. Both resolve to the same image.

Logo rendered from a relative path Logo rendered from theme configuration

Accessing $frontmatter directly

Inside Vue expressions, $frontmatter gives you the current page's frontmatter without calling useData. It is equivalent to the frontmatter ref returned by useData().

<pre>{{ $frontmatter }}</pre>

More

The official VitePress runtime API documentation lists the complete API surface.

Related Posts