VuePress

https://vuepress.vuejs.org
Admin
VuePress is a Vue-powered static site generator that helps developers build performant,...
Tokens:30,647
Snippets:427
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install VuePress and Dependencies

Source: https://vuepress.vuejs.org/guide/getting-started

Install VuePress, its bundler, and the default theme using your preferred package manager. Ensure you install the next version for RC.

```bash
# install vuepress and vue
pnpm add -D vuepress@next vue
# install bundler and theme
pnpm add -D @vuepress/bundler-vite@next @vuepress/theme-default@next
```

```bash
# install vuepress
yarn add -D vuepress@next
# install bundler and theme
yarn add -D @vuepress/bundler-vite@next @vuepress/theme-default@next
```

```bash
# install vuepress
npm install -D vuepress@next
# install bundler and theme
npm install -D @vuepress/bundler-vite@next @vuepress/theme-default@next
```

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

### Start Development Server - Node API

Source: https://vuepress.vuejs.org/reference/node-api

Starts the development server. This method is only available in `DevApp`.

```typescript
declare const dev: () => Promise<() => Promise<void>>
```

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

### Manual Project Setup Steps

Source: https://vuepress.vuejs.org/guide/getting-started

Steps to manually set up a VuePress project, including creating directories and initializing the project.

```bash
mkdir vuepress-starter
cd vuepress-starter
```

```bash
git init
pnpm init
```

```bash
git init
yarn init
```

```bash
git init
npm init
```

```bash
mkdir docs
mkdir docs/.vuepress
```

```bash
echo '# Hello VuePress' > docs/README.md
```

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

### dev

Source: https://vuepress.vuejs.org/reference/node-api

Starts the development server. This method is only available in `DevApp`.

```APIDOC
## dev

### Description
Start dev server.

### Signature
```typescript
declare const dev: () => Promise<() => Promise<void>>
```

### Details
This method is only available in `DevApp`.
```

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

### Vue SFC in Markdown Example

Source: https://vuepress.vuejs.org/advanced/cookbook/markdown-and-vue-sfc

This example demonstrates how to use Vue SFC syntax, including template, script setup, and style, within a Markdown file. Ensure only one `<script>` block is used.

```markdown
_Hello, {{ msg }}_ 

<RedDiv>

_Current count is: {{ count }}_ 

</RedDiv>

<button @click="count++">Click Me!</button>

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

const RedDiv = (_, ctx) =>
  h(
    'div',
    {
      class: 'red-div',
    },
    ctx.slots.default(),
  )
const msg = 'Vue in Markdown'
const count = ref(0)
</script>

<style>
.red-div {
  color: red;
}
</style>
```

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

### Use Composition API in Setup

Source: https://vuepress.vuejs.org/advanced/cookbook/usage-of-client-config

Utilize Vue's Composition API within the `setup` function of the client configuration. This includes accessing router instances and providing values.

```javascript
import { provide, ref } from 'vue'
import { useRoute, useRouter } from 'vue-router'
import { defineClientConfig } from 'vuepress/client'

export default defineClientConfig({
  setup() {
    // get the current route location
    const route = useRoute()
    // get the vue-router instance
    const router = useRouter()
    // provide a value that can be injected by layouts, pages and other components
    const count = ref(0)
    provide('count', count)
  },
})
```

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

### Install Webpack Bundler with npm

Source: https://vuepress.vuejs.org/guide/bundler

Use this command to install the Webpack bundler for VuePress using npm.

```bash
# install webpack bundler
npm install -D vuepress@next @vuepress/bundler-webpack@next
```

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

### Install Webpack Bundler with yarn

Source: https://vuepress.vuejs.org/guide/bundler

Use this command to install the Webpack bundler for VuePress using yarn.

```bash
# install webpack bundler
yarn add -D vuepress@next @vuepress/bundler-webpack@next
```

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

### Start VuePress Development Server

Source: https://vuepress.vuejs.org/guide/getting-started

Run the `docs:dev` script to launch a local development server with hot-reloading. The site will be available at http://localhost:8080.

```bash
pnpm docs:dev
```

```bash
yarn docs:dev
```

```bash
npm run docs:dev
```

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

### Install Vite Bundler with npm

Source: https://vuepress.vuejs.org/guide/bundler

Use this command to install the Vite bundler for VuePress using npm.

```bash
# install vite bundler
npm install -D vuepress@next @vuepress/bundler-vite@next
```

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

### Use Non-SSR-Friendly Features in Setup

Source: https://vuepress.vuejs.org/advanced/cookbook/usage-of-client-config

Use non-SSR-friendly features within the `setup` function by placing them inside the `onMounted` hook to ensure they run after the client app is mounted.

```javascript
import { onMounted } from 'vue'
import { defineClientConfig } from 'vuepress/client'

export default defineClientConfig({
  setup() {
    onMounted(() => {
      // use DOM API after mounted
      document.querySelector('#app')
    })
  },
})
```

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

### Install Vite Bundler with yarn

Source: https://vuepress.vuejs.org/guide/bundler

Use this command to install the Vite bundler for VuePress using yarn.

```bash
# install vite bundler
yarn add -D vuepress@next @vuepress/bundler-vite@next
```

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

### Install Webpack Bundler

Source: https://vuepress.vuejs.org/reference/bundler/webpack

Install the Webpack bundler package for VuePress. Use the `@next` tag for the latest version.

```bash
npm i -D @vuepress/bundler-webpack@next
```

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

### Define Basic Client Config

Source: https://vuepress.vuejs.org/advanced/cookbook/usage-of-client-config

Define the client configuration using `defineClientConfig`. This includes optional functions for `enhance`, `setup`, `layouts`, and `rootComponents`.

```javascript
import { defineClientConfig } from 'vuepress/client'

export default defineClientConfig({
  enhance({ app, router, siteData }) {},
  setup() {},
  layouts: {},
  rootComponents: [],
})
```

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

### Install Vite Bundler with pnpm

Source: https://vuepress.vuejs.org/guide/bundler

Use this command to install the Vite bundler for VuePress using pnpm.

```bash
# install vite bundler
pnpm add -D vuepress@next @vuepress/bundler-vite@next
```

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

### Install Webpack Bundler with pnpm

Source: https://vuepress.vuejs.org/guide/bundler

Use this command to install the Webpack bundler for VuePress using pnpm.

```bash
# install webpack bundler
pnpm add -D vuepress@next @vuepress/bundler-webpack@next
```

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

### Add npm Scripts for Development and Build

Source: https://vuepress.vuejs.org/guide/getting-started

Add scripts to your `package.json` to easily start the development server or build your VuePress site.

```json
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
```

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

### Install Vite Bundler for VuePress

Source: https://vuepress.vuejs.org/reference/bundler/vite

Install the Vite bundler package using npm. Ensure you are using the next version.

```bash
npm i -D @vuepress/bundler-vite@next
```

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

### VuePress v1 Sidebar Config

Source: https://vuepress.vuejs.org/guide/migration

Example of the sidebar configuration structure in VuePress v1.

```javascript
- sidebar: {
-   title: 'Foo Bar',
-   path: '/foo/bar.html',
-   collapsable: true,
-   children: [
-     ['/baz', 'Baz'],
-   ],
- }
```

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

### VuePress Theme NPM Package Configuration

Source: https://vuepress.vuejs.org/advanced/theme

Example package.json configuration for publishing a VuePress theme, including naming conventions and keywords for discoverability.

```json
{
  "name": "vuepress-theme-foo",
  "keywords": ["vuepress-theme"]
}
```

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

### Getting all routes

Source: https://vuepress.vuejs.org/advanced/cookbook/resolving-routes

You can make use of `useRoutes` to get all routes information. The return value of `useRoutes` is a Ref object containing all routes. The keys are route paths of each route, and the values are the corresponding route information.

```APIDOC
## Getting all routes

You can make use of `useRoutes` to get all routes information.
The return value of `useRoutes` is a Ref object containing all routes. The keys are route paths of each route, and the values are the corresponding route information.

```javascript
import { useRoutes } from 'vuepress/client'

const routes = useRoutes()
// {
// '/': { meta: { title: 'Home' }, loader: HomePageLoader },
// '/404.html': { meta: { title: 'Not Found' }, loader: NotFoundPageLoader },
// ...
// }

const routePaths = computed(() => Object.keys(routes.value))
// => ['/‘, '/404.html', '/foo/', '/bar/', ...]
```
```

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

### VuePress Default .gitignore Example

Source: https://vuepress.vuejs.org/guide/getting-started

Add these entries to your `.gitignore` file to prevent VuePress's temporary, cache, and build output directories from being committed to version control.

```gitignore
# VuePress default temp directory
.vuepress/.temp
# VuePress default cache directory
.vuepress/.cache
# VuePress default build output directory
.vuepress/dist
```

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

### Basic YAML Frontmatter Example

Source: https://vuepress.vuejs.org/guide/page

Define page-specific configurations like language, title, and description at the top of a markdown file using YAML frontmatter.

```yaml
---
lang: en-US
title: Title of this page
description: Description of this page
---
```

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

### Configure Plugins

Source: https://vuepress.vuejs.org/guide/migration

VuePress v2 requires plugins to be imported directly rather than referenced by string. This example shows how to configure the Google Analytics plugin.

```javascript
- module.exports = {
-   plugins: [
-     [
-       '@vuepress/plugin-google-analytics',
-       {
-         id: 'G-XXXXXXXXXX',
-       },
-     ],
-   ],
- }

+ import { googleAnalyticsPlugin } from '@vuepress/plugin-google-analytics'
+ import { defineUserConfig } from 'vuepress'
+
+ export default defineUserConfig({
+   plugins: [
+     googleAnalyticsPlugin({
+         id: 'G-XXXXXXXXXX',
+     }),
+   ],
+ })
```

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

### createDevApp

Source: https://vuepress.vuejs.org/reference/node-api

Creates a VuePress app instance for development mode, enabling a local development server. It supports initialization, preparation, and starting the dev server.

```APIDOC
## createDevApp

### Description
Create a dev mode app instance, which is used for starting a dev server.

### Signature
```typescript
const createDevApp: (config: AppConfig) => DevApp
```

### Parameters
#### Path Parameters
- **config** (AppConfig) - Required - Config to create a VuePress app.

### Example
```javascript
const dev = async () => {
  const app = createDevApp({
    // ...options
  })

  // initialize and prepare
  await app.init()
  await app.prepare()

  // start dev server
  const closeDevServer = await app.dev()

  // set up file watchers
  const watchers = []

  // restart dev server
  const restart = async () => {
    await Promise.all([
      // close all watchers
      ...watchers.map((item) => item.close()),
      // close current dev server
      closeDevServer(),
    ])
    await dev()
  }

  // process onWatched hook
  await app.pluginApi.hooks.onWatched.process(app, watchers, restart)
}
```
```

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

### clientConfigFile

Source: https://vuepress.vuejs.org/reference/plugin-api

Specify the path to a client configuration file. This hook can accept a string (absolute file path) or a function that returns the path, enabling custom client-side setups.

```APIDOC
## clientConfigFile

### Description
Path of client config file.
This hook accepts an absolute file path, or a function that returns the path.

### Type
`string | ((app: App) => string | Promise<string>)`

### Example

```javascript
import { getDirname, path } from 'vuepress/utils'

const __dirname = getDirname(import.meta.url)

export default {
  clientConfigFile: path.resolve(__dirname, './path/to/clientConfig.js'),
}
```

### See Also
* Client API > defineClientConfig
* Advanced > Cookbook > Usage of Client Config
```

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

### VuePress v2 Sidebar Config

Source: https://vuepress.vuejs.org/guide/migration

Example of the updated sidebar configuration structure in VuePress v2, using 'text', 'link', and 'collapsible' properties.

```javascript
+ sidebar: {
+   text: 'Foo Bar',
+   link: '/foo/bar.html',
+   collapsible: true,
+   children: [
+     {
+       text: 'Baz',
+       link: '/baz',
+     }
+   ],
+ }
```

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

### Basic VuePress Client Config File

Source: https://vuepress.vuejs.org/guide/configuration

A basic client configuration file for VuePress, used for adding client-side code. It exports a `defineClientConfig` object with optional `enhance`, `setup`, and `rootComponents` hooks.

```javascript
import { defineClientConfig } from 'vuepress/client'

export default defineClientConfig({
  enhance({ app, router, siteData }) {},
  setup() {},
  rootComponents: [],
})
```

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

### Reference Image from Dependency Package

Source: https://vuepress.vuejs.org/guide/assets

To reference images from installed npm packages, use an `<img>` tag with the package name as part of the path, as Markdown's relative path syntax does not support this directly.

```html
<img src="package-name/image.png" alt="Image from dependency">
```

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

### Get All Routes with useRoutes

Source: https://vuepress.vuejs.org/advanced/cookbook/resolving-routes

Use `useRoutes` to obtain a Ref object containing all route paths and their corresponding information. The keys are route paths, and values are route details like meta and loader.

```javascript
import { useRoutes } from 'vuepress/client'

const routes = useRoutes()
// {
// '/': { meta: { title: 'Home' }, loader: HomePageLoader },
// '/404.html': { meta: { title: 'Not Found' }, loader: NotFoundPageLoader },
// ...
// }

const routePaths = computed(() => Object.keys(routes.value))
// => ['/‘, '/404.html', '/foo/', '/bar/', ...]
```

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

### Add Custom Favicon with head Config

Source: https://vuepress.vuejs.org/reference/config

Use the `head` option to inject custom tags into the HTML `<head>`. This example shows how to add a custom favicon. Remember that path values in `attrValue` are not automatically prepended with the base URL.

```javascript
export default {
  head: [['link', { rel: 'icon', href: '/images/logo.png' }]],
}
```

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

### Configure Webpack Bundler in config.ts

Source: https://vuepress.vuejs.org/reference/bundler/webpack

Specify the Webpack bundler in your VuePress configuration file. This example shows basic setup with empty options for postcss and vue.

```typescript
import { webpackBundler } from '@vuepress/bundler-webpack'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  bundler: webpackBundler({
    postcss: {},
    vue: {},
  }),
})
```

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

### VuePress Build Command Help

Source: https://vuepress.vuejs.org/reference/cli

Provides help for the `build` command, detailing options for customizing the static site generation process.

```bash
Usage:
  $ vuepress build [sourceDir]

Options:
  -c, --config <config>  Set path to config file
  -d, --dest <dest>      Set the directory build output (default: .vuepress/dist)
  -t, --temp <temp>      Set the directory of the temporary files
  --cache <cache>        Set the directory of the cache files
  --clean-temp           Clean the temporary files before build
  --clean-cache          Clean the cache files before build
  --debug                Enable debug mode
  -v, --version          Display version number
  -h, --help             Display this message
```

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

### Create Build App Instance

Source: https://vuepress.vuejs.org/reference/node-api

Use `createBuildApp` to instantiate a VuePress app for static site generation. It requires an `AppConfig` object. Ensure to call `init()`, `prepare()`, and `build()` sequentially.

```javascript
const build = async () => {
  const app = createBuildApp({
    // ...options
  })

  // initialize and prepare
  await app.init()
  await app.prepare()

  // build
  await app.build()

  // process onGenerated hook
  await app.pluginApi.hooks.onGenerated.process(app)
}
```

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

### VuePress Dev Command Help

Source: https://vuepress.vuejs.org/reference/cli

Shows detailed help for the `dev` command, including options for configuring the development server.

```bash
Usage:
  $ vuepress dev [sourceDir]

Options:
  -c, --config <config>  Set path to config file
  -p, --port <port>      Use specified port (default: 8080)
  -t, --temp <temp>      Set the directory of the temporary files
  --host <host>          Use specified host (default: 0.0.0.0)
  --cache <cache>        Set the directory of the cache files
  --clean-temp           Clean the temporary files before dev
  --clean-cache          Clean the cache files before dev
  --open                 Open browser when ready
  --debug                Enable debug mode
  --no-watch             Disable watching page and config files (default: true)
  -v, --version          Display version number
  -h, --help             Display this message
```

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

### Create VuePress Project with CLI

Source: https://vuepress.vuejs.org/guide/getting-started

Use the create-vuepress command to quickly scaffold a new VuePress project. Choose your preferred package manager.

```bash
pnpm create vuepress vuepress-starter
```

```bash
yarn create vuepress vuepress-starter
```

```bash
npm init vuepress vuepress-starter
```

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

### VuePress CLI Help

Source: https://vuepress.vuejs.org/reference/cli

Displays general help information for the VuePress CLI, listing available commands and global options.

```bash
Usage:
  $ vuepress <command> [options]

Commands:
  dev [sourceDir]    Start development server
  build [sourceDir]  Build to static site
  info               Display environment information

For more info, run any command with the `--help` flag:
  $ vuepress dev --help
  $ vuepress build --help
  $ vuepress info --help

Options:
  -v, --version  Display version number
  -h, --help     Display this message
```

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

### createBuildApp

Source: https://vuepress.vuejs.org/reference/node-api

Creates a VuePress app instance for building static files. It requires configuration and allows initialization, preparation, and building of the site.

```APIDOC
## createBuildApp

### Description
Create a build mode app instance, which is used for building static files.

### Signature
```typescript
const createBuildApp: (config: AppConfig) => BuildApp
```

### Parameters
#### Path Parameters
- **config** (AppConfig) - Required - Config to create a VuePress app.

### Example
```javascript
const build = async () => {
  const app = createBuildApp({
    // ...options
  })

  // initialize and prepare
  await app.init()
  await app.prepare()

  // build
  await app.build()

  // process onGenerated hook
  await app.pluginApi.hooks.onGenerated.process(app)
}
```
```

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

### Use Local Plugin

Source: https://vuepress.vuejs.org/guide/plugin

Import and use a local plugin by specifying its path in your `config.js` file. This is useful for organizing complex configurations into separate files.

```javascript
import myPlugin from './path/to/my-plugin.js'

export default {
  plugins: [myPlugin()],
}
```

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

### Create a VuePress Plugin with Options

Source: https://vuepress.vuejs.org/advanced/plugin

Plugins often need user options. This pattern shows how to create a function that accepts options and returns either a plugin object or a plugin function.

```javascript
const fooPlugin = (options) => ({
  name: 'vuepress-plugin-foo',
  // ...
})
```

```javascript
const barPlugin = (options) => (app) => ({
  name: 'vuepress-plugin-bar',
  // ...
})
```

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

### Build VuePress Site for Production

Source: https://vuepress.vuejs.org/guide/getting-started

Execute the `docs:build` script to generate static files for your website. These files will be located in the `docs/.vuepress/dist` directory.

```bash
pnpm docs:build
```

```bash
yarn docs:build
```

```bash
npm run docs:build
```

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

### Configure Webpack Bundler

Source: https://vuepress.vuejs.org/guide/migration

To use the Webpack bundler in VuePress v2, install the `@vuepress/bundler-webpack` package and configure it in your `config.ts` file.

```bash
npm i -D @vuepress/bundler-webpack@next
```

```javascript
import { webpackBundler } from '@vuepress/bundler-webpack'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  bundler: webpackBundler(),
})
```

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

### Configure Vite Bundler

Source: https://vuepress.vuejs.org/guide/migration

To use the Vite bundler in VuePress v2, install the `@vuepress/bundler-vite` package and configure it in your `config.ts` file.

```bash
npm i -D @vuepress/bundler-vite@next
```

```javascript
import { viteBundler } from '@vuepress/bundler-vite'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  bundler: viteBundler(),
})
```

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

### App Methods

Source: https://vuepress.vuejs.org/reference/node-api

Explains the methods available on the VuePress app instance, including utilities for resolving directory paths, writing temporary files, initializing the app, and preparing client files.

```APIDOC
## App Methods

### dir
  * Utils:
    * `dir.cache()`: resolve to cache directory
    * `dir.temp()`: resolve to temp directory
    * `dir.source()`: resolve to source directory
    * `dir.dest()`: resolve to dest directory
    * `dir.client()`: resolve to `@vuepress/client` directory
    * `dir.public()`: resolve to public directory
  * Signature:
```typescript
type AppDirFunction = (...args: string[]) => string
```
  * Details:
Utils to resolve the absolute file path in corresponding directory. If you don't provide any arguments, it will return the absolute path of the directory.
  * Example:
```javascript
// resolve the absolute file path of the `${sourceDir}/README.md`
const homeSourceFile = app.dir.source('README.md')
```

### writeTemp
  * Signature:
```typescript
declare const writeTemp = (file: string, content: string) => Promise<string>
```
  * Parameters:
    * **file** (string) - Required - Filepath of the temp file that going to be written. Relative to temp directory.
    * **content** (string) - Required - Content of the temp file that going to be written.
  * Details:
A method to write temp file. The written file could be imported via `@temp` alias in client files.
  * Example:
```javascript
export default {
  // write temp file in onPrepared hook
  async onPrepared() {
    await app.writeTemp('foo.js', "export const foo = 'bar'")
  },
}
```
```javascript
// import temp file in client code
import { foo } from '@temp/foo'
```

### init
  * Signature:
```typescript
declare const init = () => Promise<void>
```
  * Details:
Initialize VuePress app.
  * Also see:
    * Advanced > Architecture > Core Process and Hooks

### prepare
  * Signature:
```typescript
declare const prepare = () => Promise<void>
```
  * Details:
Prepare client temp files.
  * Also see:
    * Advanced > Architecture > Core Process and Hooks
```

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

### Vue Theme Component Aliases

Source: https://vuepress.vuejs.org/advanced/cookbook/making-a-theme-extendable

Configure component aliases in your theme's setup to enable users to replace specific components by overriding these aliases.

```typescript
import type { Theme } from 'vuepress/core'
import { getDirname } from 'vuepress/utils'

const __dirname = getDirname(import.meta.url)

export const fooTheme = (options): Theme => ({
  name: 'vuepress-theme-foo',
  alias: {
    // set alias for replaceable components
    '@theme/Navbar.vue': path.resolve(__dirname, 'components/Navbar.vue'),
    '@theme/Sidebar.vue': path.resolve(__dirname, 'components/Sidebar.vue'),
  },
})
```

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

### build

Source: https://vuepress.vuejs.org/reference/node-api

Generates static site files. This method is only available in `BuildApp`.

```APIDOC
## build

### Description
Generate static site files.

### Signature
```typescript
declare const build: () => Promise<void>
```

### Details
This method is only available in `BuildApp`.
```

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

### Listen for Content Updates

Source: https://vuepress.vuejs.org/reference/client-api

Use the `onContentUpdated` hook to trigger a callback function when the content of a markdown file changes. This hook can only be called during the `setup` phase of a component.

```javascript
<script setup>
import { onContentUpdated } from 'vuepress/client'

onContentUpdated((reason) => {
  console.log(`content updated reason: ${reason}`)
})
</script>
```

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

### Basic VuePress Config File

Source: https://vuepress.vuejs.org/guide/configuration

A standard configuration file for a VuePress site, setting up the bundler, theme, language, title, and description.

```javascript
import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  bundler: viteBundler(),
  theme: defaultTheme(),

  lang: 'en-US',
  title: 'Hello VuePress',
  description: 'Just playing around',
})
```

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

### Customize Page Title Resolution

Source: https://vuepress.vuejs.org/reference/client-api

Customize how the page title is resolved in the client configuration file. This example shows how to prepend the site locale title to the page title.

```javascript
import { defineClientConfig, resolvers } from 'vuepress/client'

export default defineClientConfig({
  enhance({ app, router, siteData }) {
    resolvers.resolvePageHeadTitle = (page, siteLocale) =>
      `${siteLocale.title} > ${page.title}`
  },
})
```

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

### Create VuePress Theme Object and Function

Source: https://vuepress.vuejs.org/advanced/theme

Demonstrates how to define a VuePress theme using either a theme object or a theme function. Includes options for client config, build/dev templates, and plugins.

```javascript
import { getDirname, path } from 'vuepress/utils'

const __dirname = getDirname(import.meta.url)

const fooTheme = (options) =>
  // returns a theme object
  ({
    name: 'vuepress-theme-foo',

    // path to the client config of your theme
    clientConfigFile: path.resolve(__dirname, 'client.js'),

    // set custom dev / build template
    // if the template is not specified, the default template
    templateBuild: path.resolve(__dirname, 'templates/build.html'),
    templateDev: path.resolve(__dirname, 'templates/dev.html'),

    // use plugins
    plugins: [
      // ...
    ],

    // other plugin APIs are also available
  })

const barTheme =
  (options) =>
  // returns a theme function
  (app) => ({
    name: 'vuepress-theme-bar',
    // ...
  })
```

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

### Configure Default Theme

Source: https://vuepress.vuejs.org/guide/migration

In VuePress v2, themes are not automatically integrated. You need to install the desired theme (e.g., `@vuepress/theme-default`) and configure it directly in your `config.ts` file using `defaultTheme`.

```bash
npm i -D @vuepress/theme-default@next
```

```javascript
- module.exports = {
-   theme: '@vuepress/theme-default',
-   themeConfig: {
-     // default theme config
-   },
- }

+ import { defaultTheme } from '@vuepress/theme-default'
+ import { defineUserConfig } from 'vuepress'
+
+ export default defineUserConfig({
+   theme: defaultTheme({
+     // default theme config
+   }),
+ })
```

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

### onWatched

Source: https://vuepress.vuejs.org/reference/plugin-api

A lifecycle hook triggered when the VuePress app starts the dev server and begins watching for file changes. It provides access to file watchers and a method to restart the dev server.

```APIDOC
## onWatched

### Description
A lifecycle hook triggered when the VuePress app starts the dev server and begins watching for file changes. It provides access to file watchers and a method to restart the dev server.

### Type
`(app: App, watchers: Closable[], restart: () => Promise<void>) => void | Promise<void>`

### Details
The `watchers` is an array of file watchers. When changing config file, the dev command will be restarted and those watchers will be closed. If you are adding new watchers in this hook, you should push your watchers to the `watchers` array, so that they can be closed correctly when restarting. The `restart` is a method to restart the dev command. When calling this method, the `watchers` array will be closed automatically.
```

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

### Define VuePress Client Configuration

Source: https://vuepress.vuejs.org/advanced/theme

Sets up the client-side configuration for a VuePress theme, defining available layouts like 'Layout' and 'NotFound'.

```javascript
import { defineClientConfig } from 'vuepress/client'
import Layout from './layouts/Layout.vue'
import NotFound from './layouts/NotFound.vue'

export default defineClientConfig({
  layouts: {
    Layout,
    NotFound,
  },
})
```

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

### Extend Default Theme in VuePress

Source: https://vuepress.vuejs.org/reference/theme-api

Demonstrates how to extend the default VuePress theme. Ensure necessary imports are included.

```javascript
import { defaultTheme } from '@vuepress/theme-default'
import { getDirname, path } from 'vuepress/utils'

const __dirname = getDirname(import.meta.url)

export default {
  // inherit the default theme
  extends: defaultTheme(),
}
```

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

### Use `withBase` Helper for Dynamic Public File References

Source: https://vuepress.vuejs.org/guide/assets

When dealing with dynamic links or custom themes, use the `withBase` helper function from `vuepress/client` to ensure correct path resolution, especially when the site is deployed to a non-root URL.

```vue
<script setup>
import { ref } from 'vue'
import { withBase } from 'vuepress/client'

const logoPath = ref('/images/hero.png')
</script>

<template>
  <img :src="withBase(logoPath)" />
</template>
```

```vue
<img :src="$withBase('/images/hero.png')" alt="VuePress Logo">
```

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

### Update User Config to ESM Format

Source: https://vuepress.vuejs.org/guide/migration

VuePress v2 requires configuration files to be in ESM format. This example shows the transition from CommonJS `module.exports` to ESM `import` and `export default` with `defineUserConfig`.

```javascript
- module.exports = {
-   // user config
- }

+ import { defineUserConfig } from 'vuepress'
+
+ export default defineUserConfig({
+   // user config
+ })
```

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

### GitLab CI/CD Configuration for GitLab Pages

Source: https://vuepress.vuejs.org/guide/deployment

This configuration sets up a GitLab CI/CD pipeline to deploy your VuePress site to GitLab Pages. It caches dependencies and builds the site.

```yaml
# choose a docker image to use
image: node:18-buster

pages:
  # trigger deployment on every push to main branch
  only:
    - main

  # cache node_modules
  cache:
    key:
      files:
        - pnpm-lock.yaml
    paths:
      - .pnpm-store

  # Install pnpm
  before_script:
    - curl -fsSL https://get.pnpm.io/install.sh | sh -
    - pnpm config set store-dir .pnpm-store

  # install dependencies and run build script
  script:
    - pnpm i --frozen-lockfile
    - pnpm docs:build --dest public

  artifacts:
    paths:
      - public
```

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

### withBase

Source: https://vuepress.vuejs.org/reference/client-api

Prepends the site's base URL to a given path.

```APIDOC
## withBase

### Description
Prefix URL with site base.

### Also see:
* Guide > Assets > Base Helper
```

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

### Resolve File Path in App Directory

Source: https://vuepress.vuejs.org/reference/node-api

The `app.dir` utility function helps resolve absolute file paths within specific VuePress directories like source, temp, or cache. Call it without arguments to get the directory path itself.

```javascript
// resolve the absolute file path of the `${sourceDir}/README.md`
const homeSourceFile = app.dir.source('README.md')
```

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

### Add Root Components

Source: https://vuepress.vuejs.org/advanced/cookbook/usage-of-client-config

Include global UI components, such as popups, by adding them to the `rootComponents` array in the client configuration.

```javascript
import { defineClientConfig } from 'vuepress/client'
import GlobalPopup from './components/GlobalPopup.vue'

export default defineClientConfig({
  rootComponents: [GlobalPopup],
})
```

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

### VuePress Info Command

Source: https://vuepress.vuejs.org/reference/cli

Displays environment information about your system and VuePress dependencies. Useful for debugging and reporting issues.

```bash
Usage:
  $ vuepress info
```

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

### Create Development App Instance

Source: https://vuepress.vuejs.org/reference/node-api

Use `createDevApp` to instantiate a VuePress app for the development server. It requires an `AppConfig` object. This method returns a function to close the dev server. The `onWatched` hook can be used to set up file watchers and a restart mechanism.

```javascript
const dev = async () => {
  const app = createDevApp({
    // ...options
  })

  // initialize and prepare
  await app.init()
  await app.prepare()

  // start dev server
  const closeDevServer = await app.dev()

  // set up file watchers
  const watchers = []

  // restart dev server
  const restart = async () => {
    await Promise.all([
      // close all watchers
      ...watchers.map((item) => item.close()),
      // close current dev server
      closeDevServer(),
    ])
    await dev()
  }

  // process onWatched hook
  await app.pluginApi.hooks.onWatched.process(app, watchers, restart)
}
```

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

### Import and Use Client Data Composition APIs

Source: https://vuepress.vuejs.org/reference/client-api

Import and destructure various client data refs from `vuepress/client`. These refs provide access to page-specific and site-wide data.

```javascript
<script setup lang="ts">
import { useClientData } from 'vuepress/client'

const { 
  pageData, 
  pageFrontmatter, 
  pageHead, 
  pageHeadTitle, 
  pageLang, 
  routeLocale, 
  siteData, 
  siteLocaleData, 
} = useClientData()
</script>
```

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

### defineClientConfig

Source: https://vuepress.vuejs.org/reference/client-api

A helper function for creating a client configuration file.

```APIDOC
## defineClientConfig

### Description
Helper for creating clientConfigFile.

### Also see:
* Advanced > Cookbook > Usage of Client Config
```

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

### Theme API - Basic Options

Source: https://vuepress.vuejs.org/reference/theme-api

Basic configuration options for a VuePress theme, similar to the Plugin API.

```APIDOC
## Basic Options

### name
  * Type: `string`
  * Details: Name of the theme. It should follow the naming convention, and ensure consistency with the package name when publishing to NPM: Non-scoped: `vuepress-theme-foo`, Scoped: `@org/vuepress-theme-foo`.

### multiple
  * Details: A theme should never be used multiple times, so this option is not supported in theme API.
```

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

### Import and Use Default Theme - VuePress Config

Source: https://vuepress.vuejs.org/guide/theme

Import the default theme and configure it in your VuePress config file. This sets up the basic structure and navigation for your documentation site.

```javascript
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  theme: defaultTheme({
    // default theme config
    navbar: [
      {
        text: 'Home',
        link: '/',
      },
    ],
  }),
})
```

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

### onPrepared

Source: https://vuepress.vuejs.org/reference/plugin-api

A lifecycle hook that is invoked after the VuePress app has completed its preparation phase.

```APIDOC
## onPrepared

### Description
A lifecycle hook that is invoked after the VuePress app has completed its preparation phase.

### Type
`(app: App) => void | Promise<void>`
```

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

### GitHub Actions Workflow for GitHub Pages

Source: https://vuepress.vuejs.org/guide/deployment

This workflow automates the deployment of your VuePress site to GitHub Pages on every push to the main branch or manually.

```yaml
name: docs

on:
  # trigger deployment on every push to main branch
  push:
    branches: [main]
  # trigger deployment manually
  workflow_dispatch:

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          # fetch all commits to get last updated time or other git log info
          fetch-depth: 0

      - name: Setup pnpm
        uses: pnpm/action-setup@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          # choose node.js version to use
          node-version: 22
          # cache deps for pnpm
          cache: pnpm

      - name: Install deps
        run: pnpm install --frozen-lockfile

      # run build script
      - name: Build VuePress site
        run: pnpm docs:build

      # please check out the docs of the workflow for more details
      # @see https://github.com/crazy-max/ghaction-github-pages
      - name: Deploy to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v4
        with:
          # deploy to gh-pages branch
          target_branch: gh-pages
          # deploy the default output dir of VuePress
          build_dir: docs/.vuepress/dist
        env:
          # @see https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

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

### Create a VuePress Plugin Function

Source: https://vuepress.vuejs.org/advanced/plugin

A plugin can also be a function that receives the app instance and returns a plugin object.

```javascript
const barPlugin = (app) => ({
  name: 'vuepress-plugin-bar',
  // ...
})
```

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

### createPage

Source: https://vuepress.vuejs.org/reference/node-api

Creates a VuePress page object with specified options.

```APIDOC
## createPage

### Description
Create a VuePress page object.

### Signature
```typescript
const createPage: (app: App, options: PageOptions) => Promise<Page>
```

### Parameters
#### Path Parameters
- **app** (`App`) - The VuePress app instance.
- **options** (`PageOptions`) - Options to create VuePress page.

### Example
```javascript
import { createPage } from 'vuepress/core'

export default {
  // create an extra page in onInitialized hook
  async onInitialized(app) {
    app.pages.push(
      await createPage(app, {
        path: '/foo.html',
        frontmatter: {
          layout: 'Layout',
        },
        content: `\n# Foo Page\n\nHello, world.\n`,
      }),
    )
  },
}
```
```

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

### useRoutes

Source: https://vuepress.vuejs.org/reference/client-api

Provides a ref object for all available routes.

```APIDOC
## useRoutes

### Description
Returns the routes ref object.
The value is the `routes` property of the site data.

### Also see:
* Advanced > Cookbook > Resolving Routes
```

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

### VuePress Configuration File

Source: https://vuepress.vuejs.org/guide/getting-started

Define the VuePress configuration, specifying the bundler and theme. This file should be placed at `docs/.vuepress/config.js`.

```javascript
import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  bundler: viteBundler(),
  theme: defaultTheme(),
})
```

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

### Build Static Site - Node API

Source: https://vuepress.vuejs.org/reference/node-api

Generates static site files. This method is only available in `BuildApp`.

```typescript
declare const build: () => Promise<void>
```

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

### Add Default Homepage with VuePress Core

Source: https://vuepress.vuejs.org/advanced/cookbook/adding-extra-pages

Use `createPage` to programmatically add a homepage if one doesn't exist. This is useful for theme authors providing a default landing page.

```javascript
import { createPage } from 'vuepress/core'

export default {
  // all pages have been loaded after initialization
  async onInitialized(app) {
    // if the homepage does not exist
    if (app.pages.every((page) => page.path !== '/')) {
      // create a homepage
      const homepage = await createPage(app, {
        path: '/',
        // set frontmatter
        frontmatter: {
          layout: 'Layout',
        },
        // set markdown content
        content: `# Welcome to ${app.options.title}

This is the default homepage
`,
      })
      // add it to `app.pages`
      app.pages.push(homepage)
    }
  },
}
```

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

### VuePress Build Script

Source: https://vuepress.vuejs.org/guide/deployment

Add this script to your package.json to easily build your VuePress site.

```json
{
  "scripts": {
    "docs:build": "vuepress build docs"
  }
}
```

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

### Write and Load Temporary Files for Client Code

Source: https://vuepress.vuejs.org/advanced/cookbook/passing-data-to-client-code

For more complex data passing, write temporary files using `app.writeTemp()` and load them dynamically in client code using the `@temp` alias. This allows for generating dynamic code or data structures.

```javascript
export default (options) => ({
  async onPrepared(app) {
    // write temp file
    await app.writeTemp(
      'foo.js',
      `export const foo = ${JSON.stringify(options.foo)}`,
    )
  },
})
```

```javascript
import { foo } from '@temp/foo'
```

```typescript
declare module '@temp/foo' {
  export const foo: string
}
```

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

### Specify Custom Config File via CLI

Source: https://vuepress.vuejs.org/guide/configuration

Use the `--config` option with the VuePress CLI to specify a custom configuration file path.

```bash
vuepress dev docs --config my-config.ts
```

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

### Register and Use Custom Layouts

Source: https://vuepress.vuejs.org/reference/frontmatter

Register a custom layout component in `client.ts` and then specify it in the frontmatter using the `layout` key.

```typescript
import { defineClientConfig } from 'vuepress/client'
import CustomLayout from './CustomLayout.vue'

export default defineClientConfig({
  layouts: {
    CustomLayout,
  },
})
```

```yaml
---
layout: CustomLayout
---
```

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

### Specify Client Config File Path

Source: https://vuepress.vuejs.org/advanced/cookbook/usage-of-client-config

Specify the client config file path in your plugin or theme using the `clientConfigFile` hook.

```javascript
import { getDirname, path } from 'vuepress/utils'

const __dirname = getDirname(import.meta.url)

const pluginOrTheme = {
  clientConfigFile: path.resolve(__dirname, './path/to/clientConfig.ts'),
}
```

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

### onInitialized

Source: https://vuepress.vuejs.org/reference/plugin-api

A lifecycle hook that is called once the VuePress application has been fully initialized.

```APIDOC
## onInitialized

### Description
A lifecycle hook that is called once the VuePress application has been fully initialized.

### Type
`(app: App) => void | Promise<void>`
```

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

### Configure Vite Bundler

Source: https://vuepress.vuejs.org/guide/bundler

Configure VuePress to use the Vite bundler by importing and calling the `viteBundler()` function.

```javascript
import { viteBundler } from '@vuepress/bundler-vite'
// import { webpackBundler } from '@vuepress/bundler-webpack'

export default {
  bundler: viteBundler(),
  // bundler: webpackBundler(),
}
```

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

### Heroku Static Site Configuration

Source: https://vuepress.vuejs.org/guide/deployment

Configure Heroku to serve your VuePress site as a static site by specifying the root directory.

```json
{
  "root": "./docs/.vuepress/dist"
}
```

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

### __VUEPRESS_SSR__

Source: https://vuepress.vuejs.org/reference/client-api

Environment flag indicating if the application is currently in server-side rendering mode.

```APIDOC
## `__VUEPRESS_SSR__`

### Type
`boolean`

### Description
An environment flag indicating whether it is currently running in server-side-rendering (SSR) build.
```

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

### __VUEPRESS_DEV__

Source: https://vuepress.vuejs.org/reference/client-api

Environment flag indicating if the application is running in development mode.

```APIDOC
## `__VUEPRESS_DEV__`

### Type
`boolean`

### Description
An environment flag indicating whether it is currently running in `dev` mode.
```

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

### Theme API - Theme Specific Options

Source: https://vuepress.vuejs.org/reference/theme-api

Theme-specific configuration options that allow for inheritance and customization.

```APIDOC
## Theme Specific Options

### extends
  * Type: `Theme`
  * Details: The theme to inherit. All of the Theme API of the parent theme will be inherited, but the child theme will not override the parent theme directly. Theme specific options will override according to following rules: plugins: When a same plugin is used in both child and parent theme, if the plugin does not support to be used multiple times, only the one used in the child theme will take effect. templateBuild / templateDev: Child theme templates will override parent theme templates. Multi-level inheritance is supported, i.e. theme B could be extended from theme A, and then theme C could be extended from theme B. In other words, a theme could have a parent theme, a grandparent theme and so on.
  * Example:

```javascript
import { defaultTheme } from '@vuepress/theme-default'
import { getDirname, path } from 'vuepress/utils'

const __dirname = getDirname(import.meta.url)

export default {
  // inherit the default theme
  extends: defaultTheme(),
}
```

### plugins
  * Type: `(Plugin | Plugin[])[]`
  * Details: Plugins to use in the theme.
  * Also see:
    * Config > plugins

### templateBuild
  * Type: `string`
  * Details: Specify the path of the HTML template for build. It would override the default value of templateBuild, and could be overridden by user config.
  * Also see:
    * Config > templateBuild

### templateBuildRenderer
  * Type: `TemplateRenderer`
  * Details: Specify the HTML template renderer to be used for build. It would override the default value of templateBuildRenderer, and could be overridden by user config.
  * Also see:
    * Config > templateBuildRenderer

### templateDev
  * Type: `string`
  * Details: Specify the HTML template for dev. It would override the default value of templateDev, but could be overridden by user config.
  * Also see:
    * Config > templateDev
```

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

### useClientData

Source: https://vuepress.vuejs.org/reference/client-api

Returns all client data ref objects, including page data, frontmatter, head information, site data, and route locale.

```APIDOC
## useClientData

### Description
Returns all the client data ref objects. Each property can also be accessed by the following composition APIs.

### Usage
```javascript
import { useClientData } from 'vuepress/client'

const { 
  pageData,
  pageFrontmatter,
  pageHead,
  pageHeadTitle,
  pageLang,
  routeLocale,
  siteData,
  siteLocaleData,
} = useClientData()
```
```

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

### Create a VuePress Plugin Object

Source: https://vuepress.vuejs.org/advanced/plugin

A basic plugin object structure. Ensure the 'name' field follows the convention 'vuepress-plugin-xxx'.

```javascript
const fooPlugin = {
  name: 'vuepress-plugin-foo',
  // ...
}
```
Tokens:
Raw