VitePress

https://vitepress.dev/
Admin
VitePress is a Vite & Vue powered static site generator designed to effortlessly create fast,...
Tokens:82,486
Snippets:747
Trust Score:9.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Start setup wizard

Source: https://vitepress.dev/reference/cli

Starts the Setup Wizard in the current directory.

```sh
vitepress init
```

--------------------------------

### Start VitePress setup wizard with npx, pnpm, yarn, or bun

Source: https://vitepress.dev/guide/getting-started

Run the VitePress setup wizard to scaffold a basic project. The wizard asks a few questions to configure your site. Use the command that matches your package manager.

```sh
$ npx vitepress init

```

```sh
$ pnpm vitepress init

```

```sh
$ yarn vitepress init

```

```sh
$ bun vitepress init

```

--------------------------------

### Using setup hook with extends (TypeScript)

Source: https://vitepress.dev/guide/custom-theme

Uses the `setup` hook to run Composition API calls like `watch` inside the root component's `setup()`. Extends the default theme with `extends: DefaultTheme`; `setup` runs base-first and also during SSR/SSG, so keep browser-only work inside `onMounted`.

```ts
import { watch } from 'vue'
import { useData } from 'vitepress'
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  setup() {
    const { page } = useData()
    watch(() => page.value.relativePath, (path) => {
      console.log('now viewing', path)
    })
  }
}
```

--------------------------------

### Define sidebar object for multiple sections

Source: https://vitepress.dev/reference/default-theme-sidebar

Configuration example that passes an object to `sidebar` to show different sidebars for the `guide` and `config` directories.

```js
export default {
  themeConfig: {
    sidebar: {
      // This sidebar gets displayed when a user
      // is on `guide` directory.
      '/guide/': [
        {
          text: 'Guide',
          items: [
            { text: 'Index', link: '/guide/' },
            { text: 'One', link: '/guide/one' },
            { text: 'Two', link: '/guide/two' }
          ]
        }
      ],

      // This sidebar gets displayed when a user
      // is on `config` directory.
      '/config/': [
        {
          text: 'Config',
          items: [
            { text: 'Index', link: '/config/' },
            { text: 'Three', link: '/config/three' },
            { text: 'Four', link: '/config/four' }
          ]
        }
      ]
    }
  }
}
```

--------------------------------

### Install CSS pre-processors for VitePress

Source: https://vitepress.dev/guide/using-vue

Install the required CSS pre-processors for VitePress. No Vite-specific plugins are needed, but the pre-processor itself must be installed.

```bash
# .scss and .sass
npm install -D sass

# .less
npm install -D less

# .styl and .stylus
npm install -D stylus
```

--------------------------------

### Script setup and style module in Markdown

Source: https://vitepress.dev/guide/using-vue

Root-level <script> and <style> tags work like in Vue SFCs, including <script setup> and <style module>. Place them after frontmatter. Avoid <style scoped> as it bloats page size.

```html
---
hello: world
---

<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

## Markdown Content

The count is: {{ count }}

<button :class="$style.button" @click="count++">Increment</button>

<style module>
.button {
  color: red;
  font-weight: bold;
}
</style>
```

--------------------------------

### rewrites configuration example

Source: https://vitepress.dev/reference/site-config

Defines a custom directory to URL mapping using the rewrites option. The example maps a source path pattern to a destination path pattern.

```ts
export default {
  rewrites: {
    'source/:page': 'destination/:page'
  }
}
```

--------------------------------

### Example source directory structure

Source: https://vitepress.dev/guide/routing

Shows a monorepo structure with multiple packages, each containing source markdown files.

```text
.
└─ packages
   ├─ pkg-a
   │  └─ src
   │     ├─ foo.md
   │     └─ index.md
   └─ pkg-b
      └─ src
         ├─ bar.md
         └─ index.md
```

--------------------------------

### package.json scripts for VitePress

Source: https://vitepress.dev/guide/getting-started

Shows the npm scripts added to package.json during setup. The docs:dev script starts a local dev server with hot updates, docs:build builds the site, and docs:preview previews the built site.

```json
{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}
```

--------------------------------

### Install markdown-it-mathjax3 and enable math in VitePress config

Source: https://vitepress.dev/guide/markdown

Install the markdown-it-mathjax3 plugin and enable math support in the VitePress config file. The config file is .vitepress/config.ts.

```sh
npm add -D markdown-it-mathjax3@^4
```

```ts
export default {
  markdown: {
    math: true
  }
}
```

--------------------------------

### Customize prev text only

Source: https://vitepress.dev/reference/default-theme-prev-next-links

Sets the previous page link text to 'Get Started | Markdown' in frontmatter. The link is inferred from the sidebar config.

```yaml
---
prev: 'Get Started | Markdown'
---

```

--------------------------------

### Start dev server in sub directory

Source: https://vitepress.dev/reference/cli

Starts the VitePress dev server using the specified root directory.

```sh
vitepress dev [root]
```

--------------------------------

### Directory structure for internal links

Source: https://vitepress.dev/guide/markdown

Example directory structure showing how index.md files are converted to index.html and how internal links resolve.

```text
.
├─ index.md
├─ foo
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ bar
   ├─ index.md
   ├─ three.md
   └─ four.md
```

--------------------------------

### JSON frontmatter format

Source: https://vitepress.dev/guide/frontmatter

Shows the alternative JSON frontmatter syntax, which starts and ends with curly braces instead of triple-dashed lines. The example sets the title and editLink options.

```json
---
{
  "title": "Blogging Like a Hacker",
  "editLink": true
}
---
```

--------------------------------

### Basic YAML frontmatter example

Source: https://vitepress.dev/guide/frontmatter

Shows the required format for YAML frontmatter: triple-dashed lines at the top of the Markdown file, before any elements including <script> tags. The example sets the page title and enables the edit link.

```markdown
---
title: Docs with VitePress
editLink: true
---
```

--------------------------------

### Configure preview server port with --port

Source: https://vitepress.dev/guide/deploy

Example of setting the preview server port to 8080 by passing `--port` as an argument in the `docs:preview` script.

```json
{
  "scripts": {
    "docs:preview": "vitepress preview docs --port 8080"
  }
}
```

--------------------------------

### Set base to /base/

Source: https://vitepress.dev/reference/site-config

Sets the base URL for the site, prepended to all URLs starting with /. Must start and end with a slash.

```ts
export default {
  base: '/base/'
}
```

--------------------------------

### Netlify _headers file example

Source: https://vitepress.dev/guide/deploy

Place this _headers file in the public directory (e.g., docs/public/_headers) so it is copied verbatim to the output. It sets cache-control headers for all assets.

```plaintext
/assets/*
  cache-control: max-age=31536000
  cache-control: immutable
```

--------------------------------

### Install VitePress with npm, pnpm, yarn, bun, or deno

Source: https://vitepress.dev/guide/getting-started

Install VitePress as a dev dependency using your preferred package manager. The yarn command also installs vue as a dependency. VitePress is ESM-only, so ensure your package.json has "type": "module" or use .mjs/.mts extensions.

```sh
$ npm add -D vitepress@next

```

```sh
$ pnpm add -D vitepress@next

```

```sh
$ yarn add -D vitepress@next vue

```

```sh
$ bun add -D vitepress@next

```

```sh
$ deno add -D vitepress@next

```

--------------------------------

### Rendered output of math equations example

Source: https://vitepress.dev/guide/markdown

Rendered output of the math equations example, showing how the LaTeX is displayed after processing. Note the table cells use commas instead of backslashes in the output.

```md
When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$

**Maxwell's equations:**

| equation                                                                                                                                                                  | description                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}}  = 0$                                                                                                                                      | divergence of $\vec{\mathbf{B}}$ is zero                                               |
| $\nabla \times \vec{\mathbf{E}}, +, \frac1c, \frac{\partial\vec{\mathbf{B}}}{\partial t}  = \vec{\mathbf{0}}$                                                          | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
| $\nabla \times \vec{\mathbf{B}} -, \frac1c, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | *wha?*                                                                                 |
```

--------------------------------

### Output of useData example

Source: https://vitepress.dev/guide/using-vue

The JSON output of the useData example, showing the page object with path, title, and frontmatter.

```json
{
  "path": "/using-vue.html",
  "title": "Using Vue in Markdown",
  "frontmatter": {},
  ...
}
```

--------------------------------

### Directory structure for multiple sidebars

Source: https://vitepress.dev/reference/default-theme-sidebar

Shows the recommended folder layout for organizing pages into sections like 'guide' and 'config'.

```text
.
├─ guide/
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ config/
   ├─ index.md
   ├─ three.md
   └─ four.md
```

--------------------------------

### YAML Frontmatter Example

Source: https://vitepress.dev/guide/markdown

YAML frontmatter is supported out of the box. The data is available to the rest of the page, along with all custom and theming components.

```yaml
---
title: Blogging Like a Hacker
lang: en-US
---
```

--------------------------------

### createContentLoader with options and transform

Source: https://vitepress.dev/guide/data-loading

Shows how to enable `includeSrc`, `render`, and `excerpt` options and use `transform` to sort and map the raw data. The transformed result is what gets shipped to the client.

```js
import { createContentLoader } from 'vitepress'

export default createContentLoader('posts/*.md', {
  includeSrc: true, // include raw markdown source?
  render: true,     // include rendered full page HTML?
  excerpt: true,    // include excerpt?
  transform(rawData) {
    // map, sort, or filter the raw data as you wish.
    // the final result is what will be shipped to the client.
    return rawData.sort((a, b) => {
      return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date)
    }).map((page) => {
      page.src     // raw markdown source
      page.html    // rendered full page HTML
      page.excerpt // rendered excerpt HTML (content above first `---`)
      return {/* ... */}
    })
  }
})
```

--------------------------------

### Start dev server in current directory

Source: https://vitepress.dev/reference/cli

Starts the VitePress dev server in the current directory. The 'dev' command can be omitted when running in the current directory.

```sh
vitepress
```

--------------------------------

### transformHead example: Adding og:image meta

Source: https://vitepress.dev/reference/site-config

Example of using transformHead to add an og:image meta tag. It skips the 404 page and generates a dynamic image URL. This avoids overhead during dev.

```ts
export default {
  async transformHead(context) {
    if (context.page === '404.md') {
      return
    }

    // The implementation details of `generatePageImage` would depend
    // on your requirements. Here we assume it generates a suitable
    // image for each page and returns the image URL.
    const imageUrl = await generatePageImage(context)
    
    return [[
      'meta',
      { name: 'og:image', content: imageUrl }
    ]]
  }
}
```

--------------------------------

### Syntax Highlighting Output

Source: https://vitepress.dev/guide/markdown

Output of the syntax highlighting example. The code blocks are rendered with Shiki highlighting based on the language alias.

```markdown
```js
export default {
  name: 'MyComponent'
  // ...
}
```
```

```markdown
```html
<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>
```
```

--------------------------------

### Async data loader with fetch()

Source: https://vitepress.dev/guide/data-loading

Async data loader example. The load() method can be async and return a promise. This allows fetching remote data at build time. The result is serialized as JSON in the final bundle.

```js
export default {
  async load() {
    // fetch remote data
    return (await fetch('...')).json()
  }
}
```

--------------------------------

### VitePress config file (.vitepress/config.js)

Source: https://vitepress.dev/guide/getting-started

Basic `.vitepress/config.js` example showing site-level options (`title`, `description`) and the `themeConfig` option for theme behavior. The config file allows customization of the VitePress site.

```js
export default {
  // site-level options
  title: 'VitePress',
  description: 'Just playing around.',

  themeConfig: {
    // theme-level options
  }
}
```

--------------------------------

### Line Highlighting Multiple Lines Output

Source: https://vitepress.dev/guide/markdown

Output of the multiple-line highlighting example. The specified lines and ranges are highlighted.

```markdown
```js{1,4,6-8}
export default { // Highlighted
  data () {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum',
    }
  }
}
```
```

--------------------------------

### Run dev server with package manager scripts

Source: https://vitepress.dev/guide/getting-started

Commands to start the VitePress dev server using the injected npm scripts. Choose the command for your package manager: npm, pnpm, yarn, or bun.

```sh
$ npm run docs:dev
```

```sh
$ pnpm run docs:dev
```

```sh
$ yarn docs:dev
```

```sh
$ bun run docs:dev
```

--------------------------------

### Invoke VitePress directly with npx or package manager

Source: https://vitepress.dev/guide/getting-started

Alternative commands to start the dev server without npm scripts, using npx or the package manager directly. The dev server runs at http://localhost:5173.

```sh
$ npx vitepress dev docs
```

```sh
$ pnpm vitepress dev docs
```

```sh
$ yarn vitepress dev docs
```

```sh
$ bun vitepress dev docs
```

--------------------------------

### carbonAds theme configuration

Source: https://vitepress.dev/reference/default-theme-config

Example configuration for displaying Carbon Ads in the theme. Requires a `code` and `placement`; `format` is optional and defaults to `'classic'`.

```ts
export default {
  themeConfig: {
    carbonAds: {
      code: 'your-carbon-code',
      placement: 'your-carbon-placement'
      format: 'classic'
    }
  }
}
```

--------------------------------

### Directory-level override with defineAdditionalConfig

Source: https://vitepress.dev/reference/site-config

Create a config.ts in a directory to override settings for all pages in that directory. This example sets a Spanish description for the es directory.

```ts
import { defineAdditionalConfig } from 'vitepress'

export default defineAdditionalConfig({
  description: 'Generador de Sitios Estáticos desarrollado con Vite y Vue.'
})
```

--------------------------------

### Import snippet with line highlighting and relative path

Source: https://vitepress.dev/guide/markdown

Input example that imports `snippet.js` with line 2 highlighted, and the relative-path alternative. `@` corresponds to the source root (VitePress project root unless `srcDir` is configured).

```md
<<< @/snippets/snippet.js{2}
```

```md
<<< ../snippets/snippet.js
```

--------------------------------

### Register custom components globally (theme/index.js)

Source: https://vitepress.dev/reference/default-theme-nav

Register the custom components used in the nav globally using `Theme.enhanceApp`. This example extends the default theme and imports the components from local files, then registers them with `app.component`.

```JavaScript
import DefaultTheme from 'vitepress/theme'

import MyCustomComponent from './components/MyCustomComponent.vue'
import AnotherCustomComponent from './components/AnotherCustomComponent.vue'

/** @type {import('vitepress').Theme} */
export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('MyCustomComponent', MyCustomComponent)
    app.component('AnotherCustomComponent', AnotherCustomComponent)
  }
}
```

--------------------------------

### Using useData runtime API in Markdown

Source: https://vitepress.dev/guide/using-vue

Access VitePress runtime APIs like useData to get current page metadata. The example shows a script setup block and a pre tag to display the page object.

```html
<script setup>
import { useData } from 'vitepress'

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

<pre>{{ page }}</pre>
```

--------------------------------

### Preview the built docs with npm run docs:preview

Source: https://vitepress.dev/guide/deploy

Command to preview the built site locally. The preview server serves the output directory `.vitepress/dist` at `http://localhost:4173`.

```sh
$ npm run docs:preview
```

--------------------------------

### Build the docs with npm run docs:build

Source: https://vitepress.dev/guide/deploy

Command to build the VitePress documentation site.

```sh
$ npm run docs:build
```

--------------------------------

### Control line numbers with :line-numbers and :line-numbers=2

Source: https://vitepress.dev/guide/markdown

Input examples showing how to control line numbers in fenced code blocks. The first block uses no marker (line numbers disabled by default), the second uses `:line-numbers` to enable them, and the third uses `:line-numbers=2` to start numbering from line 2. The `{1}` highlights the first line.

```markdown
```ts {1}
// line-numbers is disabled by default
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
```

```markdown
```ts:line-numbers {1}
// line-numbers is enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```
```

```markdown
```ts:line-numbers=2 {1}
// line-numbers is enabled and start from 2
const line3 = 'This is line 3'
const line4 = 'This is line 4'
```
```

--------------------------------

### package.json docs:build with git fetch --unshallow

Source: https://vitepress.dev/reference/default-theme-last-updated

Prepend a manual git fetch --unshallow to the docs:build command in package.json when CI/CD platforms don't support fetch-depth settings.

```json
"docs:build": "git fetch --unshallow && vitepress build docs"
```

--------------------------------

### Set outDir to '../public'

Source: https://vitepress.dev/reference/site-config

Specifies the build output location for the site, relative to project root. Default is './.vitepress/dist'.

```ts
export default {
  outDir: '../public'
}
```

--------------------------------

### Preview production build locally

Source: https://vitepress.dev/reference/cli

Locally previews the production build. The root directory is optional and defaults to the current directory.

```sh
vitepress preview [root]
```

--------------------------------

### Define base in Multiple Sidebars

Source: https://vitepress.dev/reference/default-theme-sidebar

Use the `base` option at the root of a sidebar section to automatically prepend a path prefix to all nested `items`, avoiding repetition. This example sets `base: '/guide/'` so links like `introduction` resolve to `/guide/introduction`.

```javascript
export default {
  themeConfig: {
    sidebar: {
      '/guide/': {
        base: '/guide/',
        items: [
          // This link is resolved to `/guide/introduction`
          { text: 'Introduction', link: 'introduction' },
          // This link is resolved to `/guide/getting-started`
          { text: 'Getting Started', link: 'getting-started' }
        ]
      }
    }
  }
}
```

--------------------------------

### transformPageData

Source: https://vitepress.dev/reference/site-config

Documentation for the transformPageData hook, including its signature, parameters, return value, and usage examples.

```APIDOC
## transformPageData

### Description
A hook to transform the `pageData` of each page. You can directly mutate `pageData` or return changed values which will be merged into the page data.

### Signature
`(pageData: PageData, context: TransformPageContext) => Awaitable<Partial<PageData> | { [key: string]: any } | void>`

### Parameters
- **pageData** (PageData) - Required - The page data object for the current page.
- **context** (TransformPageContext) - Required - An object containing the site configuration.

### Context Interface
```ts
interface TransformPageContext {
  siteConfig: SiteConfig
}
```

### Return Value
- `Partial<PageData>` or `{ [key: string]: any }` - Data to be merged into the page data, or `void` if mutating `pageData` directly.

### Usage Example
```ts
export default {
  async transformPageData(pageData, { siteConfig }) {
    pageData.contributors = await getPageContributors(pageData.relativePath)
  }

  // or return data to be merged
  async transformPageData(pageData, { siteConfig }) {
    return {
      contributors: await getPageContributors(pageData.relativePath)
    }
  }
}
```

### Example: Adding a `<meta name="og:title">`
```ts
export default {
  transformPageData(pageData) {
    const title = pageData.frontmatter.layout === 'home'
      ? 'VitePress'
      : `${pageData.title} | VitePress`

    pageData.frontmatter.head ??= []
    pageData.frontmatter.head.push([
      'meta',
      { name: 'og:title', content: title }
    ])
  }
}
```

### Example: Adding a canonical URL `<link>`
```ts
export default {
  transformPageData(pageData) {
    const canonicalUrl = `https://example.com/${pageData.relativePath}`
      .replace(/index\.md$/, '')
      .replace(/\.md$/, '.html')

    pageData.frontmatter.head ??= []
    pageData.frontmatter.head.push([
      'link',
      { rel: 'canonical', href: canonicalUrl }
    ])
  }
}
```
```

--------------------------------

### Emoji Shortcut Example

Source: https://vitepress.dev/guide/markdown

Emoji shortcuts using colon syntax. A list of all emojis is available at the provided link.

```text
:tada: :100:
```

--------------------------------

### Inline Highlight Comment Output

Source: https://vitepress.dev/guide/markdown

Output of the inline highlight example. The line containing the // [!code highlight] comment is highlighted.

```markdown
```js
export default {
  data() {
    return {
      msg: 'Highlighted!' // [!code highlight]
    }
  }
}
```
```

--------------------------------

### Import code snippets with `<<< @/filepath`

Source: https://vitepress.dev/guide/markdown

Basic syntax for importing a code snippet from an existing file, and the variant that adds line highlighting via a `{highlightLines}` suffix.

```md
<<< @/filepath
```

```md
<<< @/filepath{highlightLines}
```

--------------------------------

### Internal link examples

Source: https://vitepress.dev/guide/markdown

Shows various internal link formats in Markdown, including root, directory, heading, and extension variations.

```markdown
[Home](/) <!-- sends the user to the root index.md -->
[foo](/foo/) <!-- sends the user to index.html of directory foo -->
[foo heading](./#heading) <!-- anchors user to a heading in the foo index file -->
[bar - three](../bar/three) <!-- you can omit extension -->
[bar - three](../bar/three.md) <!-- you can append .md -->
[bar - four](../bar/four.html) <!-- or you can append .html -->
```

--------------------------------

### Customize prev text and link

Source: https://vitepress.dev/reference/default-theme-prev-next-links

Sets both the text and link for the previous page link in frontmatter.

```yaml
---
prev:
  text: 'Markdown'
  link: '/guide/markdown'
---

```

--------------------------------

### Assign onBeforeRouteChange handler

Source: https://vitepress.dev/reference/runtime-api

Example of assigning a route-change handler on the router instance. The onBeforeRouteChange hook logs the target URL before navigation.

```ts
const router = useRouter()

router.onBeforeRouteChange = (to) => {
  console.log('navigating to', to)
}
```

--------------------------------

### Theme entry file with enhanceApp (JavaScript)

Source: https://vitepress.dev/guide/custom-theme

Example theme entry file (`.vitepress/theme/index.js`) that exports the theme as default. It imports a Vue layout component and uses `enhanceApp` to register global components or integrate Vue libraries.

```js
// You can directly import Vue files in the theme entry
// VitePress is pre-configured with @vitejs/plugin-vue.
import Layout from './Layout.vue'

export default {
  Layout,
  enhanceApp({ app, router, siteData }) {
    // app.component(...)
    // app.use(...)
  }
}
```

--------------------------------

### Config intellisense with defineConfig

Source: https://vitepress.dev/reference/site-config

Use defineConfig to get TypeScript-powered intellisense for config options in both JavaScript and TypeScript, assuming IDE support.

```js
import { defineConfig } from 'vitepress'

export default defineConfig({
  // ...
})
```

--------------------------------

### Add navigation links to nav

Source: https://vitepress.dev/reference/default-theme-nav

Defines a list of navigation links. The `text` is displayed and the `link` is the target path, which should start with `/` and omit the `.md` extension.

```js
export default {
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide' },
      { text: 'Config', link: '/config' },
      { text: 'Changelog', link: 'https://github.com/...' }
    ]
  }
}
```

--------------------------------

### Default Custom Containers

Source: https://vitepress.dev/guide/markdown

Shows the default built-in custom containers: info, tip, warning, danger, and details. Each container is opened and closed with ::: markers.

```markdown
::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::
```

--------------------------------

### Algolia Ask AI Configuration

Source: https://vitepress.dev/reference/default-theme-search

Enable Ask AI by passing the askAi option inside options. Provide assistantId at minimum; optional overrides for apiKey, appId, and indexName are commented out.

```ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        // askAi: "YOUR-ASSISTANT-ID"
        // OR
        askAi: {
          // at minimum you must provide the assistantId you received from Algolia
          assistantId: 'XXXYYY',
          // optional overrides – if omitted, the top-level appId/apiKey/indexName values are reused
          // apiKey: '...',
          // appId: '...',
          // indexName: '...'
        }
      }
    }
  }
})
```

--------------------------------

### Typed theme config with defineConfig

Source: https://vitepress.dev/reference/site-config

By default, defineConfig expects the theme config type from the default theme (DefaultTheme.Config). This example shows the default behavior.

```ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    // Type is `DefaultTheme.Config`
  }
})
```

--------------------------------

### Consume external theme by re-exporting it

Source: https://vitepress.dev/guide/custom-theme

Import and re-export an external theme from the custom theme entry file. This is the minimal setup for consuming a theme that does not require extension.

```js
import Theme from 'awesome-vitepress-theme'

export default Theme
```

--------------------------------

### Configure multilingual search with locales

Source: https://vitepress.dev/reference/default-theme-search

Use the `locales` option under `search.options` to provide translations for the search UI in different languages. The example shows a Chinese translation.

```ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        locales: {
          zh: { // make this `root` if you want to translate the default locale
            translations: {
              button: {
                buttonText: '搜索',
                buttonAriaLabel: '搜索'
              },
              modal: {
                displayDetails: '显示详细列表',
                resetButtonTitle: '重置搜索',
                backButtonTitle: '关闭搜索',
                noResultsText: '没有结果',
                footer: {
                  selectText: '选择',
                  selectKeyAriaLabel: '输入',
                  navigateText: '导航',
                  navigateUpKeyAriaLabel: '上箭头',
                  navigateDownKeyAriaLabel: '下箭头',
                  closeText: '关闭',
                  closeKeyAriaLabel: 'esc'
                }
              }
            }
          }
        }
      }
    }
  }
})
```

--------------------------------

### Deploy to Surge with npx surge

Source: https://vitepress.dev/guide/deploy

Deploy the built VitePress site to Surge after running `npm run docs:build`.

```sh
npx surge docs/.vitepress/dist
```

--------------------------------

### VitePress file structure

Source: https://vitepress.dev/guide/getting-started

Shows the recommended file structure when scaffolding VitePress in a nested `./docs` directory. The `docs` directory is the project root, and `.vitepress` is reserved for config, cache, and build output.

```text
.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json
```

--------------------------------

### Table of Contents Directive

Source: https://vitepress.dev/guide/markdown

Place this directive in a Markdown file to render a table of contents. The output is a literal [[toc]] placeholder that gets replaced by the generated TOC.

```markdown
[[toc]]
```

--------------------------------

### Build VitePress site for production

Source: https://vitepress.dev/reference/cli

Builds the VitePress site for production. The root directory is optional and defaults to the current directory.

```sh
vitepress build [root]
```
Tokens:
Raw