---
url: /plugins/index.md
---
# Plugins

---

---
url: /plugins/ai/index.md
---
# AI Plugins

---

---
url: /plugins/ai/llms.md
---
# plugin-llms

Add [llms.txt](https://llmstxt.org/) to your site to provide LLM-friendly content.

## Usage

```bash
npm i -D @vuepress/plugin-llms@next
```

```ts title=".vuepress/config.ts"
import { llmsPlugin } from '@vuepress/plugin-llms'

export default {
  plugins: [
    llmsPlugin({
      // options
    }),
  ],
}
```

## Why llms.txt?

Large Language Models (LLMs) increasingly rely on web-based documentation to answer user queries and write code. However, standard websites present significant challenges: context windows are limited, and raw HTML—cluttered with navigation, scripts, and styling—is token-expensive and difficult to parse.

**llms.txt** bridges this gap. It creates a standardized entry point for AI agents, providing a concise summary of your project and direct links to clean, expert-level documentation. This is particularly critical for development tools, ensuring LLMs have accurate, low-noise access to your APIs and guides.

### Plugin Overview

This plugin automatically converts your VuePress documentation into a structured dataset optimized for machine reading.

During the build process, it generates the following assets in your output directory:

```txt
📂 .vuepress/dist
├── ...
├── llms.txt                # The entry point / map of your documentation
├── llms-full.txt           # A single file containing your entire documentation
├── markdown-examples.html  # Your standard web page
└── markdown-examples.md    # The clean Markdown version of that page
```

::: tip
These files are generated **only during the production build** (i.e., when running `vuepress build`). They will appear in the `.vuepress/dist` directory alongside your HTML files.
:::

## Output Files

### 1. `llms.txt`

The `llms.txt` file acts as the primary index for AI agents. It contains the **Title**, **Description**, **Details (Optional)**, and a **Table of Contents (TOC)** for your site.

You can view the generated file for this documentation site here: llms.txt.

**Default Format:**

```md title="llms.txt"
# Title

> Description

Details (Optional)

## Table of Contents

- [Title](url): Description
- [Title](url): Description
- ...
```

**Content Resolution Logic:**

The plugin determines the content for these fields based on the following priority order (highest priority first):

* **Site Title:**
  1. `llmsTxtTemplateGetter.title`
  2. `heroText` in the homepage frontmatter
  3. The current locale's [title](https://v2.vuepress.vuejs.org/reference/config.html#locales) in the VuePress config
  4. The main [title](https://v2.vuepress.vuejs.org/reference/config.html#title) in the VuePress config
  5. The page title of the locale homepage (`README.md`)

* **Site Description:**
  1. `llmsTxtTemplateGetter.description`
  2. `tagline` in the locale homepage frontmatter
  3. The current locale's [description](https://v2.vuepress.vuejs.org/reference/config.html#locales) in the VuePress config
  4. The main [description](https://v2.vuepress.vuejs.org/reference/config.html#description) in the VuePress config
  5. `frontmatter.description` in the locale homepage (`README.md`)

* **Site Details (Optional):**
  1. `llmsTxtTemplateGetter.details`
  2. `frontmatter.details` in the locale homepage (`README.md`)

* **Table of Contents (TOC):**
  Formatted as `- [title](url): description`. The `description` is pulled from the page's `frontmatter.description`.

  By default, a flat, first-level TOC is generated. You can customize this behavior (e.g., to support multi-level nesting) by defining a custom getter in the [`llmsTxtTemplateGetter`](#llmstxttemplategetter) option.

### 2. `llms-full.txt`

The `llms-full.txt` file is a concatenated version of your documentation. It merges the content of all Markdown files into a single text stream, allowing LLMs to ingest your entire knowledge base in one request.

You can view the full file for this site here: llms-full.txt.

**Format:**

```txt title="llms-full.txt"
---
url: /path/to/page
description: A brief summary of the page
---

# Page Title

Full Markdown content of the page...

---

---
url: /path/to/next-page
description: ...
---

...
```

### 3. Individual Page Content

In addition to the summary files, the plugin generates a clean Markdown file for every HTML page in your site.

For example, if your site has a page at `/guide/quick-start.html`, the plugin generates a corresponding `/guide/quick-start.md` file. This allows LLMs to fetch specific pages with zero HTML noise.

## Options

### llmsTxt

* Type: `boolean`

* Default: `true`

* Details: Specifies whether to generate the `llms.txt` file (the index file containing links to section summaries).

### llmsFullTxt

* Type: `boolean`

* Default: `true`

* Details: Specifies whether to generate the `llms-full.txt` file (a consolidated text file containing the entire documentation).

### llmsPageTxt

* Type: `boolean`

* Default: `true`

* Details: Specifies whether to generate individual LLM-friendly Markdown files for each page of the website.

### stripHTML

* Type: `boolean`

* Default: `true`

* Details: Determines whether HTML tags should be stripped from the generated Markdown files to ensure cleaner input for LLMs.

### filter

* Type: `(page: Page) => boolean`

* Default: `() => true`

* Details:

  A function to filter which pages are included. If the function returns `true`, the page is included in `llms.txt`.

  Note that pages explicitly disabled via `frontmatter.llmstxt` or pages not generated from Markdown sources will always be excluded, regardless of this setting.

### domain

* Type: `string`

* Default: `''`

* Details:

  An optional domain to prepend to all URLs in `llms.txt` and other generated files.

  While standard relative paths are often sufficient, some AI agents may handle absolute URLs better. Use this option if you need to enforce fully qualified URLs (e.g., `https://example.com/foo/bar.md`).

  ```md title="llms.txt"
  - [title](/foo/bar.md) <!-- [!code --] -->
  - [title](https://example.com/foo/bar.md) <!-- [!code ++] -->
  ```

### locale

* Types: `string | 'all'`

* Default: `'/'`

* Details:

  Controls which locale to generate content for.

  * If unset, it defaults to the site's root locale.
  * If set to a specific locale key (e.g., `'/zh/'`), it generates files only for that language.
  * If set to `'all'`, the plugin generates `llms.txt` resources for every configured locale.

  ：：： tip Why use `'all'`?

  If your documentation contains specialized terminology or concepts that LLMs struggle to translate accurately, generating dedicated `llms.txt` files for each language ensures that international users (and their AI assistants) receive the most precise information available.

  :::

### llmsTxtTemplate

* Types: `string`

* Default:

  ```ts
  const DEFAULT_LLMSTXT_TEMPLATE = `\
  # {title}

  {description}

  {details}

  ## Table of Contents

  {toc}`
  ```

* Details:

  Defines the structure of the `llms.txt` file. You can rearrange the default placeholders—`{title}`, `{description}`, `{details}`, and `{toc}`—or introduce new ones using `llmsTxtTemplateGetter`.

### llmsTxtTemplateGetter

* Type: `TemplateGetterOptions`

  ```ts
  /**
   * Link extension options for generated links
   */
  export type LinkExtension = '.html' | '.md'

  /**
   * Page with additional LLM-friendly content
   */
  export interface LLMPage extends Page {
    /**
     * The page's Markdown content
     *
     * @example '# Guide\n\nA guide'
     */
    markdown: string

    /**
     * The page's excerpt
     *
     * @example 'Introduction to the guide'
     */
    excerpt: string
  }

  /**
   * State object for LLM text generation
   */
  export interface LLMState {
    /**
     * VuePress app instance
     */
    app: App

    /**
     * Site base URL
     */
    base: string

    /**
     * Optional domain to prepend to URLs
     */
    domain?: string

    /**
     * Link extension for generated links
     */
    linkExtension?: LinkExtension

    /**
     * The path of the current locale.
     */
    currentLocale: string

    /**
     * Current site locale data
     */
    siteLocale: SiteLocaleData

    /**
     * Whether to generate llms.txt files for all locales.
     */
    allLocales: boolean
  }

  export type TemplateGetter = (pages: LLMPage[], state: LLMState) => string

  export interface TemplateGetterOptions {
    /** Any custom variable */
    [key: string]: TemplateGetter | string | undefined
  }
  ```

* Default: `{}`

* Details:

  Provides custom variables or getter functions for the [`llmsTxtTemplate`](#llmstxttemplate).

  You can use this to inject static strings or dynamically generated content.

  **Example: Overriding the title**

  ```ts
  llmsPlugin({
    llmsTxtTemplateGetter: {
      title: 'My Custom Docs Title',
    },
  })
  ```

  **Example: Adding a custom variable**

  ```ts
  llmsPlugin({
    llmsTxtTemplate: '# {title}\n\n{customNote}',
    llmsTxtTemplateGetter: {
      customNote: 'Note: This content is optimized for AI agents.',
    },
  })
  ```

  **Example: Generating a custom list of pages**

  ```ts
  llmsPlugin({
    llmsTxtTemplate: '# {title}\n\n## Page List\n\n{pageList}',
    llmsTxtTemplateGetter: {
      pageList: (pages, state) =>
        pages.map((page) => `- ${page.title}`).join('\n'),
    },
  })
  ```

## Frontmatter

The plugin respects the following `frontmatter` properties in your Markdown files.

### title {#frontmatter-title}

* Types: `string`
* Details:
  * On the **homepage** (`README.md`), this overrides the site title in `llms.txt`.
  * On **regular pages**, this serves as the page title in the Table of Contents.

### description {#frontmatter-description}

* Types: `string`
* Details:

  * On the **homepage** (`README.md`), this overrides the site description in `llms.txt`.
  * On **regular pages**, this provides the page summary in the Table of Contents.

  *Recommendation: Write clear, concise descriptions for every page to help LLMs understand the context and relevance of the link.*

### heroText {#frontmatter-herotext}

* Types: `string`
* Details:
  * Used exclusively on the homepage (locale `README.md`). It serves as the primary title source for `llms.txt`.

### tagline {#frontmatter-tagline}

* Types: `string`
* Details:
  * Used exclusively on the homepage (locale `README.md`). It serves as the primary description source for `llms.txt`.

### details {#frontmatter-details}

* Types: `string`
* Details:
  * Used exclusively on the homepage (locale `README.md`). It provides the content for the `{details}` section in `llms.txt`.

### llmstxt

* Types: `boolean`
* Default: `true`
* Details:
  * Controls whether the current page is included in the generated LLM files. Set to `false` to hide a specific page from AI agents.

## Others

It is recommended to configure server redirects so that AI agents can reliably access files via `.md` or `.txt` extensions, even if they guess the URL structure.

For example, on **Netlify**, add the following to `public/_redirects`:

```txt
/llms.md         /llms.txt 200!
/llms-full.md    /llms-full.txt 200!
```

For more details on redirect syntax, refer to the [Netlify documentation](https://docs.netlify.com/routing/redirects).

---

---
url: /plugins/analytics/index.md
---
# Analytics Plugins

---

---
url: /plugins/analytics/baidu-analytics.md
---
# baidu-analytics

This plugin integrates [Baidu Analytics](https://tongji.baidu.com/) (Baidu Tongji) into your VuePress site, allowing you to track visitor traffic and user interactions.

::: tip

Please **disable** the [SPA mode](https://tongji.baidu.com/web/help/article?id=324\&type=0) in your Baidu Analytics settings.

This plugin automatically handles page view reporting on route changes. Enabling Baidu's built-in SPA mode may result in duplicate data or incorrect statistics.

:::

## Usage

```bash
npm i -D @vuepress/plugin-baidu-analytics@next
```

```ts title=".vuepress/config.ts"
import { baiduAnalyticsPlugin } from '@vuepress/plugin-baidu-analytics'

export default {
  plugins: [
    baiduAnalyticsPlugin({
      // options
    }),
  ],
}
```

### Event Tracking

Once configured, the plugin will automatically report page view (PV) events for both initial page loads and subsequent route navigations.

For advanced usage, the global `_hmt` array is exposed on the `window` object. You can utilize this to push [custom events](https://tongji.baidu.com/holmes/Analytics/%E6%8A%80%E6%9C%AF%E6%8E%A5%E5%85%A5%E6%8C%87%E5%8D%97/JS%20API/JS%20API%20%E4%BD%BF%E7%94%A8%E6%89%8B%E5%86%8C) manually.

```ts
// Example: Manually reporting a custom event
window._hmt = window._hmt || []
window._hmt.push(['_trackEvent', 'category', 'action', 'label', 'value'])
```

## Options

### id

* Type: `string`
* Required: Yes
* Details: The tracking ID for your Baidu Analytics account. This is usually the string found in the `hm.js` script URL provided by Baidu (e.g., `hm.js?your_tracking_id`).

---

---
url: /plugins/analytics/clarity-analytics.md
---
s

# clarity-analytics

Seamlessly integrate [Microsoft Clarity](https://clarity.microsoft.com/) into your VuePress project.

## Usage

```bash
npm i -D @vuepress/plugin-clarity-analytics@next
```

```ts title=".vuepress/config.ts"
import { clarityAnalyticsPlugin } from '@vuepress/plugin-clarity-analytics'

export default {
  plugins: [
    clarityAnalyticsPlugin({
      // options
    }),
  ],
}
```

## Features

Microsoft Clarity is a behavioral analysis tool that helps you understand how users interact with your website. This plugin simplifies the setup process, enabling you to capture actionable insights without complex configuration.

Key features include:

* **Session Recordings:** Watch playbacks of user sessions to see exactly how they navigate your site.
* **Heatmaps:** Visualize clicks, scrolls, and area engagement to identify what content matters most.
* **Smart Insights:** Leverage AI-powered analysis with Copilot to summarize user behavior and trends.

For more details on capabilities, please refer to the [Clarity Features Overview](https://learn.microsoft.com/en-us/clarity/setup-and-installation/about-clarity#supported-features).

### Advanced Usage

Once the plugin is enabled, the `clarity()` function is exposed on the global `window` object. You can use this to interact with the [Clarity Client API](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-api) for advanced tasks, such as:

* Identifying users.
* Tracking custom events.
* Managing cookie consent.

## Options

### id

* Type: `string`
* Required: Yes
* Details: The Project ID assigned by Microsoft Clarity. You can find this in your Clarity dashboard under Settings.

### crossOrigin

* Type: `string`
* Default: `undefined`
* Details: The `crossorigin` attribute for the injected script tag. This configures the [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) setting for loading the Clarity resources.

---

---
url: /plugins/analytics/google-analytics.md
---
# google-analytics

Seamlessly integrate [Google Analytics 4](https://analytics.google.com/) (GA4) into your VuePress site.

This plugin leverages the [Global Site Tag (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs) to enable robust traffic analysis and user tracking.

## Usage

```bash
npm i -D @vuepress/plugin-google-analytics@next
```

```ts title=".vuepress/config.ts"
import { googleAnalyticsPlugin } from '@vuepress/plugin-google-analytics'

export default {
  plugins: [
    googleAnalyticsPlugin({
      // options
    }),
  ],
}
```

### Reporting Events

Google Analytics 4 [automatically collects a wide range of events](https://support.google.com/analytics/answer/9234069) by default, such as `page_view`, `first_visit`, and `scroll`.

For standard metric collection, simply set the [Measurement ID](#id).

If you require advanced tracking capabilities, this plugin exposes the global `gtag()` function on the `window` object. You can utilize this function to report [custom events](https://developers.google.com/analytics/devguides/collection/ga4/events) programmatically based on user interactions within your site.

## Options

### id

* Type: `string`

* Required: Yes

* Details:

  The Google Analytics 4 Measurement ID (must start with `'G-'`).

  Please refer to the [official guide](https://support.google.com/analytics/answer/9539598) to locate your Measurement ID. Ensure you are using a GA4 Measurement ID (`G-XXXXXXXXXX`) rather than a Universal Analytics Tracking ID (`UA-XXXXXXXX`).

* Example:

  ```ts title=".vuepress/config.ts"
  export default {
    plugins: [
      googleAnalyticsPlugin({
        id: 'G-XXXXXXXXXX',
      }),
    ],
  }
  ```

### debug

* Type: `boolean`

* Details:
  Enables the sending of events to the Google Analytics DebugView. This is useful for verifying your setup and troubleshooting event data during development. [Learn more about DebugView](https://support.google.com/analytics/answer/7201382).

* Example:

  ```ts title=".vuepress/config.ts"
  export default {
    plugins: [
      googleAnalyticsPlugin({
        id: 'G-XXXXXXXXXX',
        debug: true,
      }),
    ],
  }
  ```

---

---
url: /plugins/analytics/umami-analytics.md
---
# umami-analytics

Seamlessly integrate [Umami Analytics](https://umami.is/)—a privacy-focused, open-source web analytics solution—into your VuePress site.

## Usage

```bash
npm i -D @vuepress/plugin-umami-analytics@next
```

```ts title=".vuepress/config.ts"
import { umamiAnalyticsPlugin } from '@vuepress/plugin-umami-analytics'

export default {
  plugins: [
    umamiAnalyticsPlugin({
      // options
    }),
  ],
}
```

This plugin supports both [Umami Cloud](https://cloud.umami.is/login) and [Self-hosted](https://umami.is/docs/install) instances.

### Reporting Events

Out of the box, the plugin automatically captures page view events during initial visits and subsequent route changes.

For advanced tracking needs, the global `umami` object is exposed on the `window` instance. You can utilize this to trigger [custom events](https://umami.is/docs/tracker-functions) programmatically via `umami.track()`.

## Options

### id

* Type: `string`
* Required: Yes
* Details: The unique Website ID provided by your Umami dashboard.

### link

* Type: `string`
* Default: `'https://us.umami.is/script.js'`
* Details: The source URL of the Umami tracking script.

### autoTrack

* Type: `boolean`
* Default: `true`
* Details:

  Controls whether to track pageviews and events automatically.

  Set this to `false` if you wish to disable automatic data collection and rely solely on manual tracking functions.

### cache

* Type: `boolean`
* Details:

  Enables caching to improve the tracking script's performance.

  **Note:** This feature utilizes Session Storage. Depending on your region's regulations, you may need to disclose this usage to your visitors.

### domains

* Type: `string[]`
* Details:

  A list of allowed domains. Tracking will only occur when the site is accessed via these specific domains.

### hostUrl

* Type: `string`
* Default: `link`
* Details:

  A custom endpoint for sending analytics data. If not specified, it defaults to the script location defined in `link`.

---

---
url: /plugins/blog/index.md
---
# Blog Plugins

---

---
url: /plugins/blog/blog/index.md
---
# blog

Blog plugin for VuePress, providing article collection, categorization, type filtering, and excerpt generation.

## Usage

```bash
npm i -D @vuepress/plugin-blog@next
```

```ts title=".vuepress/config.ts"
import { blogPlugin } from '@vuepress/plugin-blog'

export default {
  plugins: [
    blogPlugin({
      // options
    }),
  ],
}
```

---

---
url: /plugins/blog/blog/config.md
---
# Config

## Plugin Options

### getInfo

* Type: `(page: Page) => Record<string, unknown>`
* Reference:
  * [Guide → Article Collection](./guide.md#gathering-info)
* Details:

  A function to extract article information from pages.

  The extracted information is injected into the route meta, making it accessible via client-side composables.

### filter

* Type: `(page: Page) => boolean`
* Default: `(page) => Boolean(page.filePathRelative) && !page.frontmatter.home`
* Reference:
  * [Guide → Article Collection](./guide.md#collecting-articles)
* Details:

  A function to determine which pages are treated as blog articles.

  By default, it includes all pages generated from Markdown files, excluding the homepage.

### category

* Type: `BlogCategoryOptions[]`
* Reference:
  * [Guide → Categories and Types](./guide.md#customizing-categories-and-types)
* Details: Category configurations. See [Category Config](#blog-category-config).

### type

* Type: `BlogTypeOptions[]`
* Reference:
  * [Guide → Categories and Types](./guide.md#customizing-categories-and-types)
* Details: Type configurations. See [Type Config](#blog-type-config).

### slugify

* Type: `(name: string) => string`
* Default: `(name) => name.replace(/ _/g, '-').replace(/[:?*|\\/<>]/g, "").toLowerCase()`
* Details: A function that converts strings into URL-friendly slugs for route registration.

### excerpt

* Type: `boolean`
* Default: `true`
* Reference: [Guide → Excerpt Generation](./guide.md#generating-excerpt)
* Details: Enables or disables excerpt generation for pages.

### excerptSeparator

* Type: `string`
* Default: `<!-- more -->`
* Reference:
  * [Guide → Excerpt Generation](./guide.md#generating-excerpt)
* Details: The separator used to manually define excerpts within the content.

### excerptLength

* Type: `number`
* Default: `300`
* Reference:
  * [Guide → Excerpt Generation](./guide.md#generating-excerpt)
* Details:

  The target length for auto-generated excerpts.

  ::: tip

  The generator will cut the text at the nearest position meeting or exceeding this length.

  Set to `0` to disable automatic excerpt generation.

  :::

### excerptFilter

* Type: `(page: Page) => boolean`
* Default: Same as the `filter` option
* Reference:
  * [Guide → Excerpt Generation](./guide.md#generating-excerpt)
* Details:

  A function to filter pages for excerpt generation.

  ::: tip

  Use this to exclude pages from automatic excerpt generation. For instance, if `excerpt` or `description` is already defined in the frontmatter, you might prefer to use those values directly.

  :::

### isCustomElement

* Type: `(tagName: string) => boolean`
* Default: `() => false`
* Reference:
  * [Guide → Generating Excerpt](./guide.md#generating-excerpt)
* Details:

  A function to identify custom elements.

  This is used to distinguish custom elements from unknown tags, which are otherwise stripped during excerpt generation.

### metaScope

* Type: `string`
* Default: `"_blog"`
* Details:

  The key under which the extracted information is injected into the route meta.

  ::: tip

  Setting this to an empty string will inject the information directly into the route meta root, rather than nesting it under a field.

  :::

### hotReload

* Type: `boolean`
* Default: Enabled if the `--debug` flag is used
* Details:

  Enables hot reload support in the development server.

  ::: tip To theme developers

  This is disabled by default due to potential performance impacts on sites with extensive categories and types. It may also slow down hot updates when editing Markdown.

  It is recommended to enable this only when users are actively adding or organizing categories/tags. For general use, keep it disabled.

  Alternatively, you can detect the number of pages in the user's project and decide whether to enable it programmatically.

  :::

## Blog Category Config

The blog category configuration accepts an array, where each item defines a specific "category" rule.

```ts
interface BlogCategoryOptions {
  /**
   * Unique category name
   */
  key: string

  /**
   * Function to retrieve categories from a page
   */
  getter: (page: Page) => string[]

  /**
   * A custom function to sort the pages
   */
  sorter?: (pageA: Page, pageB: Page) => number

  /**
   * The path pattern for the registered page
   *
   * @description `:key` will be replaced by the "slugify" result of the original key
   *
   * @default `/:key/`
   */
  path?: string | false

  /**
   * Page layout name
   *
   * @default 'Layout'
   */
  layout?: string

  /**
   * Frontmatter configuration
   */
  frontmatter?: (localePath: string) => Record<string, string>

  /**
   * The path pattern or custom function for the item page
   *
   * @description When providing a string, `:key` and `:name` will be replaced by the "slugify" result of the original key and name
   *
   * @default `/:key/:name/`
   */
  itemPath?: string | false | ((name: string) => string)

  /**
   * Item page layout name
   *
   * @default 'Layout'
   */
  itemLayout?: string

  /**
   * Frontmatter configuration for items
   */
  itemFrontmatter?: (name: string, localePath: string) => Record<string, string>
}
```

## Blog Type Config

The blog type configuration accepts an array, where each item defines a specific "type" rule.

```ts
interface BlogTypeOptions {
  /**
   * Unique type name
   */
  key: string

  /**
   * A filter function to determine if a page belongs to this type
   */
  filter: (page: Page) => boolean

  /**
   * A custom function to sort the pages
   */
  sorter?: (pageA: Page, pageB: Page) => number

  /**
   * The path pattern for the registered page
   *
   * @default '/:key/'
   */
  path?: string

  /**
   * Layout name
   *
   * @default 'Layout'
   */
  layout?: string

  /**
   * Frontmatter configuration
   */
  frontmatter?: (localePath: string) => Record<string, string>
}
```

## Composition API

The following APIs are available via `@vuepress/plugin-blog/client`.

* Blog category

  ```ts
  const useBlogCategory: <
    T extends Record<string, unknown> = Record<string, unknown>,
  >(
    key?: string,
  ) => ComputedRef<BlogCategoryData<T>>
  ```

  The `key` argument represents the unique category key.

  If no key is provided, the plugin attempts to infer the key from the current route.

* Blog type

  ```ts
  const useBlogType: <
    T extends Record<string, unknown> = Record<string, unknown>,
  >(
    key?: string,
  ) => ComputedRef<BlogTypeData<T>>
  ```

  The `key` argument represents the unique type key.

  If no key is provided, the plugin attempts to infer the key from the current route.

The return values are:

```ts
interface Article<T extends Record<string, unknown> = Record<string, unknown>> {
  /** Article path */
  path: string
  /** Article info */
  info: T
}

interface BlogCategoryData<
  T extends Record<string, unknown> = Record<string, unknown>,
> {
  /** Category path */
  path: string

  /**
   * Available only when the current route matches a specific item path
   */
  currentItems?: Article<T>[]

  /** Category map */
  map: {
    /** Unique key under current category */
    [key: string]: {
      /** Category path of the key */
      path: string
      /** Category items of the key */
      items: Article<T>[]
    }
  }
}

interface BlogTypeData<
  T extends Record<string, unknown> = Record<string, unknown>,
> {
  /** Type path */
  path: string

  /** Items under current type */
  items: Article<T>[]
}
```

---

---
url: /plugins/blog/blog/guide.md
---
# Guide

Empowers VuePress themes with blog functionality, including article collection, categorization, and excerpt generation.

## Article Collection

The plugin uses the `filter` option to determine which pages should be treated as articles.

::: tip
By default, all pages generated from Markdown files are considered articles, excluding the homepage.
:::

## Gathering Info

Use the `getInfo` option to define a function that extracts article metadata from pages.

The plugin injects this collected information into the `routeMeta` field, making it accessible via the Composition API.

::: details Demo

```ts title="theme entrance"
import { blogPlugin } from '@vuepress/plugin-blog'

export default {
  name: 'vuepress-theme-xxx',
  plugins: [
    blogPlugin({
      filter: ({ filePathRelative, frontmatter }) => {
        // Exclude pages not generated from files
        if (!filePathRelative) return false

        // Exclude pages in the `archives` directory
        if (filePathRelative.startsWith('archives/')) return false

        // Exclude pages that do not use the default layout
        if (frontmatter.home || frontmatter.layout) return false

        return true
      },

      getInfo: ({ frontmatter, title, git = {}, data = {} }) => {
        // Extract page info
        const info: Record<string, unknown> = {
          title,
          author: frontmatter.author || '',
          categories: frontmatter.categories || [],
          date: frontmatter.date || git.createdTime || null,
          tags: frontmatter.tags || [],
          excerpt: data.excerpt || '',
        }

        return info
      },
    }),
    // other plugins ...
  ],
}
```

:::

## Customizing Categories and Types

This plugin allows you to organize articles into two primary collection types:

* **Category**: Groups articles based on labels (e.g., Tags, Categories).
* **Type**: Filters articles based on specific conditions (e.g., "Diary" entries, "Starred" posts).

You can configure these using the `category` and `type` array options.

### Category Configuration

Use the `category` option to create label-based groupings.

For example, if you want to group articles by "tags" defined in the frontmatter, generate a map page at `/tag/` (using a `TagMap` layout), and list articles for specific tags at `/tag/:tagName` (using a `TagList` layout), you would use the following configuration:

```ts title="theme entrance"
import { blogPlugin } from '@vuepress/plugin-blog'

export default {
  name: 'vuepress-theme-xxx',
  plugins: [
    blogPlugin({
      // other options ...
      category: [
        {
          key: 'tag',
          getter: ({ frontmatter }) => frontmatter.tag || [],
          path: '/tag/',
          layout: 'TagMap',
          frontmatter: () => ({ title: 'Tag page' }),
          itemPath: '/tag/:name/',
          itemLayout: 'TagList',
          itemFrontmatter: (name) => ({ title: `Tag ${name}` }),
        },
      ],
    }),
    // other plugins ...
  ],
}
```

### Type Configuration

Use the `type` option to create specific collection lists.

For example, to display a list of "Starred" articles (marked by `star: true` in the frontmatter) at `/star/` using a `StarList` layout:

```ts title="theme entrance"
import { blogPlugin } from '@vuepress/plugin-blog'

export default {
  name: 'vuepress-theme-xxx',
  plugins: [
    blogPlugin({
      // other options ...
      type: [
        {
          key: 'star',
          filter: ({ frontmatter }) => frontmatter.star,
          path: '/star/',
          layout: 'StarList',
          frontmatter: () => ({ title: 'Star page' }),
        },
      ],
    }),
    // other plugins ...
  ],
}
```

For a complete list of options, please refer to the [Category Config](./config.md#blog-category-config) and [Type Config](./config.md#blog-type-config).

## Using Composition API in Client-side

During page generation, the plugin injects the following information into `frontmatter.blog`:

```ts
interface BlogFrontmatterOptions {
  /** Current type of the page */
  type: 'category' | 'type'
  /** Unique key under current category or tag */
  key: string
  /**
   * Current category name
   *
   * @description Only available in category item page
   */
  name?: string
}
```

You can use the `useBlogCategory()` and `useBlogType()` hooks to retrieve the data bound to the current route. Alternatively, you can pass a specific `key` as an argument to retrieve data associated with that key.

Based on the configuration examples above, here is how you can access "tag" and "star" data on the client side:

`TagMap` layout:

```vue
<script setup lang="ts">
import { useBlogCategory } from '@vuepress/plugin-blog/client'
import { RouteLink } from 'vuepress/client'

const categoryMap = useBlogCategory('tag')
</script>

<template>
  <div>
    <h1>Tag page</h1>
    <ul>
      <li v-for="({ items, path }, name) in categoryMap.map" :key="path">
        <RouteLink :key="name" :to="path" class="category">
          {{ name }}
          <span class="category-num">
            {{ items.length }}
          </span>
        </RouteLink>
      </li>
    </ul>
  </div>
</template>
```

`TagList` layout:

```vue
<script setup lang="ts">
import { useBlogCategory } from '@vuepress/plugin-blog/client'
import { RouteLink } from 'vuepress/client'

const categoryMap = useBlogCategory('tag')
</script>

<template>
  <div>
    <h1>Tag page</h1>
    <div class="category-wrapper">
      <RouteLink
        v-for="({ items, path }, name) in categoryMap.map"
        :key="name"
        :to="path"
        class="category"
      >
        {{ name }}
        <span class="category-num">
          {{ items.length }}
        </span>
      </RouteLink>
    </div>
    <div v-if="categoryMap.currentItems" class="article-wrapper">
      <div v-if="!categoryMap.currentItems.length">No articles found.</div>
      <article
        v-for="{ info, path } in categoryMap.currentItems"
        :key="path"
        class="article"
        @click="$router.push(path)"
      >
        <header class="title">
          {{ info.title }}
        </header>
        <hr />
        <div class="article-info">
          <span v-if="info.author" class="author"
            >Author: {{ info.author }}</span
          >
          <span v-if="info.date" class="date"
            >Date: {{ new Date(info.date).toLocaleDateString() }}</span
          >
          <span v-if="info.category" class="category"
            >Category: {{ info.category.join(', ') }}</span
          >
          <span v-if="info.tag" class="tag"
            >Tag: {{ info.tag.join(', ') }}</span
          >
        </div>
        <div v-if="info.excerpt" class="excerpt" v-html="info.excerpt" />
      </article>
    </div>
  </div>
</template>
```

`StarList` layout:

```vue
<script setup lang="ts">
import { useBlogType } from '@vuepress/plugin-blog/client'
import ParentLayout from '@vuepress/theme-default/layouts/Layout.vue'

import ArticleList from '../components/ArticleList.vue'

const stars = useBlogType('star')
</script>

<template>
  <div v-if="stars.items?.length" class="article-wrapper">
    <article
      v-for="{ info, path } in stars.items"
      :key="path"
      class="article"
      @click="$router.push(path)"
    >
      <header class="title">
        {{ info.title }}
      </header>
      <hr />
      <div class="article-info">
        <span v-if="info.author" class="author">Author: {{ info.author }}</span>
        <span v-if="info.date" class="date"
          >Date: {{ new Date(info.date).toLocaleDateString() }}</span
        >
        <span v-if="info.category" class="category"
          >Category: {{ info.category.join(', ') }}</span
        >
        <span v-if="info.tag" class="tag">Tag: {{ info.tag.join(', ') }}</span>
      </div>
      <div v-if="info.excerpt" class="excerpt" v-html="info.excerpt" />
    </article>
  </div>
  <div v-else>No articles found.</div>
</template>
```

For details on return types, please refer to [Composition API Return Types](./config.md#composition-api).

## I18n Support

This plugin features native Internationalization (i18n) support. Your configurations are automatically applied to each locale.

For example, if you define the following locales in your config:

```ts title=".vuepress/config.ts"
export default {
  locales: {
    '/': {
      lang: 'en-US',
    },
    '/zh/': {
      lang: 'zh-CN',
    },
  },
}
```

The plugin will automatically generate `/zh/star/` alongside `/star/`. Each path will only display articles belonging to the corresponding locale.

## Generating Excerpt

The plugin includes a built-in excerpt generator, which can be enabled by setting `excerpt: true`.

::: tip Excerpt Limitations

An excerpt is an HTML fragment used to display a short preview of an article. Please note the following restrictions:

* **Syntax Support**: Unknown tags (including Vue components) and Vue-specific syntax will be removed during generation. To preserve custom non-Vue elements, use the `isCustomElement` option.
* **Assets**: As excerpts are HTML fragments, relative paths and aliases for images will be removed. To ensure images display correctly in excerpts, use absolute paths (based on `.vuepress/public`) or full URLs.

:::

The generator prioritizes the use of a separator to determine the excerpt. The default separator is `<!-- more -->`, which can be customized via the `excerptSeparator` option.

If no valid separator is found, the generator extracts content from the beginning of the file up to a specified length (default: `300` characters). This length can be adjusted using the `excerptLength` option.

To control which pages should generate excerpts, use the `excerptFilter` option.

::: tip Example

You may prefer to use `frontmatter.description` as excerpt when available, you can configure the filter function to return `false` whenever `frontmatter.description` is present, skipping the automatic generation for those pages.

:::

---

---
url: /plugins/blog/comment/index.md
---
# comment

Comment plugin for VuePress supporting multiple providers.

## Usage

```bash
npm i -D @vuepress/plugin-comment@next
```

```ts title=".vuepress/config.ts"
import { commentPlugin } from '@vuepress/plugin-comment'

export default {
  plugins: [
    commentPlugin({
      provider: 'Waline', // Artalk | Giscus | Waline | Twikoo
      // provider-specific options
    }),
  ],
}
```

## Supported Providers

* [Artalk](./artalk/)
* [Giscus](./giscus/)
* [Twikoo](./twikoo/)
* [Waline](./waline/)

## Guide

See [Guide](./guide.md) for detailed configuration.

---

---
url: /plugins/blog/comment/artalk/index.md
---
# Artalk

Artalk is a clean self-hosted commenting system that you can easily deploy on your server and integrate into your front-end pages.

Deploy the Artalk comment box on your blog or any other page to add rich social functionality.

## Install

```bash
npm i -D artalk
```

## Deploy Artalk Server

See the [Artalk documentation](https://artalk.js.org/guide/deploy.html).

## Configuration

Please set `provider: "Artalk"` and pass your server link to `server` in the plugin options.

For other configuration items, see [Artalk Config](./config.md).

::: tip

The plugin retains the `el` option and inserts Artalk itself on the page. At the same time, the plugin will automatically set the `pageTitle`, `pageKey` and `site` options for you according to the VuePress information.

:::

## Dark Mode

To let Artalk apply the correct theme, you need to pass a boolean value to `<CommentService />` through `darkmode` prop, representing whether the dark mode is currently enabled.

---

---
url: /plugins/blog/comment/artalk/config.md
---
# Artalk Options

## Config

See [Artalk Configuration](https://artalk.js.org/guide/frontend/config.html) for details.

* The `el`, `pageTitle`, `pageKey`, and `site` options are reserved for the plugin and will be automatically inferred from VuePress config.

* The two function options `imgUploader` and `avatarURLBuilder` can only be set on the client side.

## Plugin Config

You can directly configure serializable options in the plugin options:

```ts title=".vuepress/config.ts"
import { commentPlugin } from '@vuepress/plugin-comment'

export default {
  plugins: [
    commentPlugin({
      provider: 'Artalk',
      // other options
      // ...
    }),
  ],
}
```

## Client Config

You can use the `defineArtalkConfig` function to customize Artalk:

```ts title=".vuepress/client.ts"
import { defineArtalkConfig } from '@vuepress/plugin-comment/client'
import { defineClientConfig } from 'vuepress/client'

defineArtalkConfig({
  // Artalk config
})
```

---

---
url: /plugins/blog/comment/giscus/index.md
---
# Giscus

Giscus is a commenting system based on GitHub Discussion that is easy to start.

## Preparation

1. Create a public repository and open discussion panel as a place to store comments.
2. Install the [Giscus App](https://github.com/apps/giscus) to have permission to access the corresponding repository.
3. After completing the above steps, please go to the [Giscus page](https://giscus.app) to get your settings.

   You just need to fill in the repository and Discussion categories, then scroll to the "Enable giscus" section at the bottom of the page and obtain four attributes: `data-repo`, `data-repo-id`, `data-category` and `data-category-id`.

## Config

Please set `provider: "Giscus"` and pass `data-repo`, `data-repo-id`, `data-category` and `data-category-id` as plugin options as `repo`, `repoId`, `category` `categoryId`.

For other options, see [Giscus Config](./config.md).

## Theme

By default, the theme of Giscus is `light` or `dark` (based on darkmode status).

::: tip Dark Mode

To let Giscus apply the correct theme, you need to pass a boolean value to `<CommentService />` via `darkmode` property, indicating whether darkmode is currently enabled.

:::

If you want to customize theme in lightmode and darkmode, you can set `lightTheme` and `darkTheme` option with a built-in theme keyword or a custom CSS link starting with `https://`.

---

---
url: /plugins/blog/comment/giscus/config.md
---
# Giscus Options

## Config

### repo

* Type: `string`
* Required: Yes
* Details: The name of repository to store discussions

### repoId

* Type: `string`
* Required: Yes
* Details: The ID of repository to store discussions. Generate through [Giscus Page](https://giscus.app/)

### category

* Type: `string`
* Required: Yes
* Details: The name of the discussion category

### categoryId

* Type: `string`
* Required: Yes
* Details: The ID of the discussion category. Generate through [Giscus Page](https://giscus.app/)

### mapping

* Type: `string`
* Default: `"pathname"`
* Details: Page - Discussion mapping. For details see [Giscus Page](https://giscus.app/)

### strict

* Type: `boolean`
* Default: `true`
* Details: Whether to enable strict mapping

### lazyLoading

* Type: `boolean`
* Default: `true`
* Details: Whether to enable lazy loading

### reactionsEnabled

* Type: `boolean`
* Default: `true`
* Details: Whether to enable reactions

### inputPosition

* Type: `"top" | "bottom"`
* Default: `"top"`
* Details: Input position

### lightTheme

* Type: `GiscusTheme`

  ```ts
  type GiscusTheme =
    | 'dark_dimmed'
    | 'dark_high_contrast'
    | 'dark_protanopia'
    | 'dark'
    | 'light_high_contrast'
    | 'light_protanopia'
    | 'light'
    | 'preferred_color_scheme'
    | 'transparent_dark'
    | `https://${string}`
  ```

* Default: `"light"`

* Details:

  Giscus theme used in light mode

  Should be a built-in theme keyword or a CSS link starting with `https://`.

### darkTheme

* Type: `GiscusTheme`

  ```ts
  type GiscusTheme =
    | 'dark_dimmed'
    | 'dark_high_contrast'
    | 'dark_protanopia'
    | 'dark'
    | 'light_high_contrast'
    | 'light_protanopia'
    | 'light'
    | 'preferred_color_scheme'
    | 'transparent_dark'
    | `https://${string}`
  ```

* Default: `"dark"`

* Details:

  Giscus theme used in dark mode

  Should be a built-in theme keyword or a CSS link starting with `https://`.

## Plugin Config

You can directly configure serializable options in the plugin options:

```ts title=".vuepress/config.ts"
import { commentPlugin } from '@vuepress/plugin-comment'

export default {
  plugins: [
    commentPlugin({
      provider: 'Giscus',
      // other options
      // ...
    }),
  ],
}
```

## Client Config

You can use the `defineGiscusConfig` function to customize Giscus:

```ts title=".vuepress/client.ts"
import { defineGiscusConfig } from '@vuepress/plugin-comment/client'
import { defineClientConfig } from 'vuepress/client'

defineGiscusConfig({
  // Giscus config
})
```

---

---
url: /plugins/blog/comment/guide.md
---
# Guide

## Configuration

The plugin offers flexible configuration through both the plugin options and the client configuration file.

### Using Plugin Options

```ts title=".vuepress/config.ts"
import { commentPlugin } from '@vuepress/plugin-comment'

export default {
  plugins: [
    commentPlugin({
      provider: 'Artalk', // Artalk | Giscus | Waline | Twikoo
      // provider-specific options
    }),
  ],
}
```

### Using Client Config

```ts title=".vuepress/client.ts"
import {
  defineArtalkConfig,
  // defineGiscusConfig,
  // defineTwikooConfig,
  // defineWalineConfig,
} from '@vuepress/plugin-comment/client'
import { defineClientConfig } from 'vuepress/client'

defineArtalkConfig({
  // options
})
```

### Configuration Logic

To ensure optimal performance and proper serialization, options are split between the plugin configuration and the client configuration:

* **Plugin Options**: Static options such as `provider`, `locales`, and resource links must be set here. This allows the bundler to perform **tree-shaking**, ensuring that code for unused providers is excluded from the final build.

* **Client Config**: Dynamic options, specifically those involving functions or callbacks, must be set here. Since these cannot be serialized in the main config, the client config serves as the runtime entry point.

## Component Usage

The plugin registers a global `<CommentService />` component that you can place anywhere in your layout.

**For Users**:
You can inject the component using aliases or layout slots provided by your theme. A common practice is to place it immediately after the `<PageNav />` component.

**For Theme Developers**:
You should include the `<CommentService />` component directly within your theme's layout files to provide built-in comment support.

### Visibility & Identification

You can control the visibility of the comment section and customize the unique identifier for each page:

* **Global Toggle**: Use the `comment` option in the plugin configuration to set the default visibility for the entire site.
* **Per-Page Toggle**: Use the `comment` key in the frontmatter to enable or disable comments for a specific page, overriding the global setting.
* **Custom Identifier**: Use the `commentID` key in the frontmatter to define a custom identifier for the page's comments (e.g., when migrating posts or changing URLs).

## Available Providers

We support the following comment services. Please refer to their respective guides for setup details: [Giscus](giscus/README.md), [Waline](waline/README.md), [Artalk](artalk/README.md), and [Twikoo](twikoo/README.md).

::: tip Recommendations

* **Giscus**: Ideal for **developers** and technical blogs, as it uses GitHub Discussions to store comments.
* **Waline**: A comprehensive choice for **general users**, offering a rich feature set and backend flexibility.

:::

## Common Options

### provider&#x20;

* Type: `"Artalk" | "Giscus" | "Twikoo" | "Waline" | "None"`
* Default: `"None"`
* Details: The comment service provider to use.

### comment

* Type: `boolean`
* Default: `true`
* Details: Whether to enable the comment feature globally by default.

---

---
url: /plugins/blog/comment/twikoo/index.md
---
# Twikoo

A concise, safe and free static site commenting system, based on [Tencent Cloud Development](https://curl.qcloud.com/KnnJtUom).

## Install

```bash
npm i -D twikoo
```

## Getting started

1. Apply for [MongoDB](https://www.mongodb.com/cloud/atlas/register) account

2. Create a free MongoDB database, the recommended region is `AWS / N. Virginia (us-east-1)`

3. Click CONNECT on the Clusters page, follow the steps to allow connections from all IP addresses ([Why?](https://vercel.com/support/articles/how-to-allowlist-deployment-ip-address)), create Database user, and record the database connection string, please change the `<password>` in the connection string to the database password

4. Sign up for a [Vercel](https://vercel.com/signup) account

5. Click the button below to deploy Twikoo to Vercel in one click

   [![Vercel](https://vercel.com/button)](https://vercel.com/import/project?template=https://github.com/imaegoo/twikoo/tree/dev/src/vercel-min)

6. Go to Settings - Environment Variables, add the environment variable `MONGODB_URI`, the value is the database connection string in step 3

7. Go to Overview, click the link under Domains, if the environment configuration is correct, you can see the prompt "Twikoo cloud function is running normally"

8. Vercel Domains (with `https://` prefix, e.g. `https://xxx.vercel.app`) is your environment ID

## Configuration

Please set `provider: "Twikoo"` and pass your server address to `envId` in the plugin options.

For other configuration items, see [Twikoo Config](./config.md).

---

---
url: /plugins/blog/comment/twikoo/config.md
---
# Twikoo Options

## Config

### envId

* Type: `string`
* Required: Yes
* Details: Vercel address or Tencent CloudBase environment ID.

## Plugin Config

You can directly configure serializable options in the plugin options:

```ts title=".vuepress/config.ts"
import { commentPlugin } from '@vuepress/plugin-comment'

export default {
  plugins: [
    commentPlugin({
      provider: 'Twikoo',
      // other options
      // ...
    }),
  ],
}
```

## Client Config

You can use the `defineTwikooConfig` function to customize Twikoo:

```ts title=".vuepress/client.ts"
import { defineTwikooConfig } from '@vuepress/plugin-comment/client'
import { defineClientConfig } from 'vuepress/client'

defineTwikooConfig({
  // Twikoo config
})
```

---

---
url: /plugins/blog/comment/waline/index.md
---
# Waline

A safe comment system with backend.

## Install

```bash
npm i -D @waline/client
```

## LeanCloud Settings (Database)

1. [Sign in](https://console.leancloud.app/login) or [sign up](https://console.leancloud.app/register) to LeanCloud and enter the [Console](https://console.leancloud.app/apps).

2. Click the [Create app](https://console.leancloud.app/apps) button to create a new app and enter a name you like:

   ![Create App](./assets/leancloud-app-1.jpg)

3. Enter the app, then select `Settings` > `App Keys` in the left bottom corner. You will see `APP ID`, `APP Key` and `Master Key` of your app. We will use them later.

   ![ID and Key](./assets/leancloud-app-2.jpg)

## Deploy to Vercel (Server)

[![Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwalinejs%2Fwaline%2Ftree%2Fmain%2Fexample)

1. Click the button above to redirect to Vercel and deploy with the Waline template.

   ::: tip

   If you haven't logged in, we recommend you sign in with GitHub.

   :::

2. Input your Vercel project name then click `Create`.

   ![skip team](/images/comment/vercel-2.png)

3. A repository named as your input will be created and initialized automatically based on the Waline example template by Vercel.

   ![deploy](/images/comment/vercel-3.png)

   After a minute or two, Vercel should finish the deployment. Click `Go to Dashboard` to redirect to your application dashboard.

   ![deploy](/images/comment/vercel-4.png)

4. Click `Settings` menu on the top, and `Environment Variables` button on the side to go to environment variables setting page. Then set `LEAN_ID`, `LEAN_KEY` and `LEAN_MASTER_KEY`. The variables' values should be the ones you got in the previous step. `APP ID` is the value of `LEAN_ID`, and `APP Key` to `LEAN_KEY`, `Master Key` to `LEAN_MASTER_KEY`.

   ![set environment variables](/images/comment/vercel-5.png)

5. To let your environment variables setting take effect, you need to redeploy your application. Click `Deployments` menu on the top and find the latest deployment at the top of list, click `Redeploy` button in the right dropdown menu.

   ![redeploy](/images/comment/vercel-6.png)

6. If everything is ok, Vercel will redirect to `Overview` page to start redeployment. Wait a moment and the `STATUS` will change to `Ready`. Now you can click `Visit` to visit the site. This link is your server address.

   ![redeploy success](/images/comment/vercel-7.png)

## Assign Domain (Optional)

1. Click `Settings` - `Domains` to go to domain setting page.

2. Input domain you want to assign and click `Add` button.

   ![Add domain](/images/comment/vercel-8.png)

3. Add a new `CNAME` record in your domain service server.

   | Type  | Name    | Value                |
   | ----- | ------- | -------------------- |
   | CNAME | example | cname.vercel-dns.com |

4. You can use your own domain to visit the Waline comment system after it goes into effect. :tada:

   * serverURL: example.your-domain.com
   * admin panel: example.your-domain.com/ui

   ![success](/images/comment/vercel-9.png)

## Client

### Using plugin

Set `provider: "Waline"` in the plugin options, and set `serverURL` as the link obtained in the previous step.

Then, place the `<CommentService>` component at a suitable location in your site (usually at the bottom of the page), you will be able to see the comment box.

::: tip

You can also pass in other options supported by Waline (except `el`). For details, see [Waline Config](config.md)

:::

## Comment Management (Management)

1. After the deployment is complete, please visit `<serverURL>/ui/register` to register. The first person to register will be set as an administrator.
2. After you log in as administrator, you can see the comment management interface. You can edit, mark or delete comments here.
3. Users can also register their account through comment box, and they will be redirected to their profile page after logging in.

---

---
url: /plugins/blog/comment/waline/config.md
---
# Waline Config

## Config

### serverURL

* Type: `string`
* Required: Yes
* Details: Waline server address URL

### emoji

* Type: `(string | WalineEmojiInfo)[] | false`

  ```ts
  type WalineEmojiPresets = `http://${string}` | `https://${string}`

  interface WalineEmojiInfo {
    /**
     * Emoji name show on tab
     */
    name: string
    /**
     * Current folder link
     */
    folder?: string
    /**
     * Common prefix of Emoji icons
     */
    prefix?: string
    /**
     * Type of Emoji icons, will be regarded as file extension
     */
    type?: string
    /**
     * Emoji icon show on tab
     */
    icon: string
    /**
     * Emoji image list
     */
    items: string[]
  }
  ```

* Default: `['//unpkg.com/@waline/emojis@1.1.0/weibo']`

* Reference:
  * [Guide → Emoji](https://waline.js.org/en/guide/features/emoji.html)

* Details: Emoji settings

### dark

* Type: `string | boolean`
* Default: `false`
* Reference:
  * [Custom Style](https://waline.js.org/en/guide/features/style.html)
* Details: Dark mode support. Setting a boolean will set the dark mode according to its value. Set it to `'auto'` will display darkmode due to device settings. Filling in a CSS selector will enable darkmode only when the selector match waline ancestor nodes.

### commentSorting

* Type: `WalineCommentSorting`
* Default: `'latest'`
* Details: Comment list sorting method. Should be one of `'latest'`, `'oldest'`, or `'hottest'`.

### meta

* Type: `string[]`
* Default: `['nick', 'mail', 'link']`
* Details: Reviewer attributes. Should be one of `'nick'`, `'mail'`, `'link'`.

### requiredMeta

* Type: `string[]`
* Default: `[]`
* Details:

  Set required fields. Available values:

  * `[]`
  * `['nick']`
  * `['nick', 'mail']`

### login

* Type: `string`
* Default: `'enable'`
* Details:

  Login mode status. Available values:

  * `'enable'`: Enable login (default)
  * `'disable'`: Login is disabled, users should fill in information to comment
  * `'force'`: Forced login, users must login to comment

### wordLimit

* Type: `number | [number, number]`
* Default: `0`
* Details: Comment word limit. When a single number is filled in, it's the maximum number of comment words. No limit when set to `0`.

### pageSize

* Type: `number`
* Default: `10`
* Details: Number of comments per page.

### imageUploader&#x20;

* Type: `WalineImageUploader | false`

  ```ts
  type WalineImageUploader = (image: File) => Promise<string>
  ```

* Reference:
  * [Cookbook → Upload Image](https://waline.js.org/en/cookbook/customize/upload-image.html)

* Details:

  Custom image upload method. The default behavior is to embed images Base 64 encoded, you can set this to `false` to disable image uploading.

  The function should receive an image object and return a Promise that provides the image address.

### highlighter&#x20;

* Type: `WalineHighlighter | false`

  ```ts
  type WalineHighlighter = (code: string, lang: string) => string
  ```

* Reference:
  * [Cookbook → Customize Highlighter](https://waline.js.org/en/cookbook/customize/highlighter.html)

* Details:

  **Code highlighting** uses `hanabi` by default. The function passes in original content of code block and language of the code block. You should return a string directly.

  You can pass in a code highlighter of your own, or set to `false` to disable code highlighting.

### texRenderer&#x20;

* Type: `WalineTexRenderer | false`

  ```ts
  type WalineTexRenderer = (blockMode: boolean, tex: string) => string
  ```

* Reference:
  * [Cookbook → Customize TeX Renderer](https://waline.js.org/en/cookbook/customize/tex-renderer.html)
  * [MathJax](https://www.mathjax.org/)
  * [KaTeX](https://katex.org/)

* Details:

  Customize TeX rendering. The default behavior is to prompt that the preview mode does not support TeX. The function provides two parameters: the first parameter indicates whether it should be rendered in block level, and the second parameter is the string of the TeX content. Return an HTML string as render result.

  You can import TeX renderer to provide preview feature. We recommend you use KaTeX or MathJax, or set to `false` to disable parsing TeX.

### search&#x20;

* Type: `WalineSearchOptions | false`

  ```ts
  interface WalineSearchImageData extends Record<string, unknown> {
    /**
     * Image link
     */
    src: string

    /**
     * Image title
     *
     * @description Used for alt attribute of image
     */
    title?: string

    /**
     * Image preview link
     *
     * @description For better loading performance, we will use this thumbnail first in the list
     *
     * @default src
     */
    preview?: string
  }

  type WalineSearchResult = WalineSearchImageData[]

  interface WalineSearchOptions {
    /**
     * Search action
     */
    search: (word: string) => Promise<WalineSearchResult>

    /**
     * Default result when opening list
     *
     * @default () => search('')
     */
    default?: () => Promise<WalineSearchResult>

    /**
     * Fetch more action
     *
     * @description It will be triggered when the list scrolls to the bottom. If your search service supports paging, you should set this to achieve infinite scrolling
     *
     * @default (word) => search(word)
     */
    more?: (word: string, currentCount: number) => Promise<WalineSearchResult>
  }
  ```

* Details: Customize search features. You can disable search function by setting it to `false`.

### recaptchaV3Key

* Type: `string`
* Details:

  reCAPTCHA V3 is a captcha service provided by Google. You can add reCAPTCHA V3 site key with `recaptchaV3Key` to enable it.

  You should also set environment variable `RECAPTCHA_V3_SECRET` for server.

### reaction

* Type: `boolean | string[]`
* Default: `false`
* Details:

  Add emoji interaction function to the article. Set it to `true` to provide the default emoji, you can also customize the emoji image by setting the emoji URL array, and supports a maximum of 8 emojis.

### metaIcon&#x20;

* Type: `boolean`
* Default: `true`
* Details: Whether to import meta icon.

### locales&#x20;

* Type: `WalineLocales`

  ```ts
  interface WalineLocales {
    [localePath: string]: Partial<WalineLocale>
  }
  ```

* Reference:
  * [Waline Locales](https://waline.js.org/en/cookbook/customize/locale.html)

* Details:
  Waline locales.

## Plugin Config

You can directly configure serializable options in the plugin options:

```ts title=".vuepress/config.ts"
import { commentPlugin } from '@vuepress/plugin-comment'

export default {
  plugins: [
    commentPlugin({
      provider: 'Waline',
      // other options
      // ...
    }),
  ],
}
```

## Client Config

You can use the `defineWalineConfig` function to customize Waline:

```ts title=".vuepress/client.ts"
import { defineWalineConfig } from '@vuepress/plugin-comment/client'
import { defineClientConfig } from 'vuepress/client'

defineWalineConfig({
  // Waline config
})
```

---

---
url: /plugins/blog/feed/index.md
---
# feed

## Usage

```bash
npm i -D @vuepress/plugin-feed@next
```

```ts title=".vuepress/config.ts"
import { feedPlugin } from '@vuepress/plugin-feed'

export default {
  plugins: [
    feedPlugin({
      // options
    }),
  ],
}
```

---

---
url: /plugins/blog/feed/channel.md
---
# Channel Config

The `channel` option allows you to configure metadata for the generated feed channel.

## channel.title

* Type: `string`
* Default: `SiteConfig.title`
* Details: The title of the channel.

## channel.link

* Type: `string`
* Default: Deployment link (generated from `options.hostname` and `context.base`)
* Details: The address of the channel

## channel.description

* Type: `string`
* Default: `SiteConfig.description`
* Details: The description of the channel.

## channel.language

* Type: `string`
* Default:
  * `siteConfig.locales['/'].lang`
  * Falls back to `"en-US"` if the above is not available.
* Details: The language of the channel.

## channel.copyright

* Type: `string`
* Default:
  * Tries to use `author.name` from the channel options.
  * Falls back to `Copyright by $author`.
* Recommended to set manually: **Yes**
* Details: The copyright information for the channel.

## channel.pubDate

* Type: `string` (must be a valid Date ISOString)
* Default: The current time when the plugin is invoked
* Recommended to set manually: **Yes**
* Details: The publication date of the channel.

## channel.lastUpdated

* Type: `string` (must be a valid Date ISOString)
* Default: The current time when the plugin is invoked
* Details: The last update time of the channel content.

## channel.ttl

* Type: `number`
* Recommended to set manually: **Yes**
* Details: Time to Live (TTL) in minutes. This indicates how long a feed reader should cache the content before making a new request.

## channel.image

* Type: `string`
* Recommended to set manually: **Yes**
* Details: The channel image. It is recommended to use a square image with a size of at least 512×512 pixels.

## channel.icon

* Type: `string`
* Recommended to set manually: **Yes**
* Details: The channel icon. It should be a square image of at least 128×128 pixels. A transparent background is recommended.

## channel.author

* Type: `FeedAuthor`
* Recommended to set manually: **Yes**
* Details: The primary author of the channel.

::: details FeedAuthor format

```ts
interface FeedAuthor {
  /** Author name */
  name: string
  /** Author's email */
  email?: string
  /** Author's site */
  url?: string
  /**
   * Author's avatar address
   *
   * Square, preferably not less than 128×128 with transparent background
   */
  avatar?: string
}
```

:::

## channel.hub

* Type: `string`
* Details: The URL for the WebSub hub. Since WebSub requires a server backend (which differs from the static nature of VuePress), you generally do not need to configure this unless you have a specific requirement. For details, see [WebSub](https://w3c.github.io/websub/#subscription-migration).

---

---
url: /plugins/blog/feed/config.md
---
# Plugin Config

## hostname

* Type: `string`
* Required: Yes

The domain name where the site is deployed.

## atom

* Type: `boolean`
* Default: `false`

Whether to generate an Atom feed.

## json

* Type: `boolean`
* Default: `false`

Whether to generate a JSON feed.

## rss

* Type: `boolean`
* Default: `false`

Whether to generate an RSS feed.

## image

* Type: `string`

A large image or icon for the feed, typically used as a banner.

## icon

* Type: `string`

A small icon for the feed, typically used as a favicon.

## count

* Type: `number`
* Default: `100`

The maximum number of items to include in the feed. After sorting all valid pages, only the first `count` items will be preserved.

If your site contains a large number of articles, consider adjusting this option to reduce the feed file size.

## preservedElements

* Type: `(RegExp | string)[] | (tagName: string) => boolean`

Custom elements or components that should be preserved in the feed content.

::: tip
By default, all unknown tags will be removed.
:::

## filter

* Type: `(page: Page)=> boolean`
* Default:

  ```js
  ;({ frontmatter, filePathRelative }) =>
    Boolean(frontmatter.feed ?? (filePathRelative && !frontmatter.home))
  ```

A custom filter function to determine which pages are included in the feed.

## sorter

* Type: `(pageA: Page, pageB: Page)=> number`

* Default:

  ```ts
  // dateSorter is from @vuepress/helper
  ;(pageA: Page, pageB: Page): number =>
    dateSorter(
      pageA.data.git?.createdTime
        ? new Date(pageA.data.git?.createdTime)
        : pageA.frontmatter.date,
      pageB.data.git?.createdTime
        ? new Date(pageB.data.git?.createdTime)
        : pageB.frontmatter.date,
    )
  ```

A custom sorter function for feed items.

The default behavior sorts items by the file creation time retrieved from git (requires `@vuepress/plugin-git`).

::: tip
You should enable `@vuepress/plugin-git` to accurately use the creation time of pages for sorting. Otherwise, feed items will follow the default page order in VuePress.
:::

## channel

The `channel` option configures *Feed Channels*.

For available options, please see [Config → Channel](channel.md).

## devServer

* Type: `boolean`
* Default: `false`

Whether to enable feed generation in the development server.

::: tip
For performance reasons, hot reload is not available. You must restart the devServer to sync changes.
:::

## devHostname

* Type: `string`
* Default: `"http://localhost:${port}"`

The hostname to use when running in the development server.

## atomOutputFilename

* Type: `string`
* Default: `"atom.xml"`

The output filename for the Atom feed, relative to the output directory.

## atomXslTemplate

* Type: `string`
* Default: Content of `@vuepress/plugin-feed/templates/atom.xsl`

The content of the XSL template file for Atom.

## atomXslFilename

* Type: `string`
* Default: `"atom.xsl"`

The output filename for the Atom XSL file, relative to the output directory.

## jsonOutputFilename

* Type: `string`
* Default: `"feed.json"`

The output filename for the JSON feed, relative to the output directory.

## rssOutputFilename

* Type: `string`
* Default: `"rss.xml"`

The output filename for the RSS feed, relative to the output directory.

## rssXslTemplate

* Type: `string`
* Default: Content of `@vuepress/plugin-feed/templates/rss.xsl`

The content of the XSL template file for RSS.

## rssXslFilename

* Type: `string`
* Default: `"rss.xsl"`

The output filename for the RSS XSL file, relative to the output directory.

## getter

The controller for feed generation. See [Feed Getter](./getter.md).

::: tip
The plugin includes a built-in getter. Set this option only if you require full control over the feed generation process.
:::

## locales

* Type: `Record<string, BaseFeedOptions>`

Configuration for specific locales.

All options listed above are supported within locales, except for `hostname`.

---

---
url: /plugins/blog/feed/frontmatter.md
---
# Frontmatter Config

You can customize how individual pages appear in the feed by configuring the page frontmatter.

## Inclusion Control

By default, all valid articles are included in the feed generation. To exclude a specific page from the feed, set `feed: false` in its frontmatter.

## Standard Information

The plugin automatically extracts the following standard frontmatter properties to populate feed items.

### title

* Type: `string`

The title of the page. It is automatically inferred from the first `h1` header if not specified.

### description

* Type: `string`

A summary or description of the page.

### date

* Type: `Date`

The publication date of the page.

### article

* Type: `boolean`

Specifies whether the page is an article.

> If set to `false`, the page will be treated as a non-article page and excluded from the feed.

### copyright

* Type: `string`

Copyright information specific to this page.

### cover / image / banner

* Type: `string`

The cover image for the page. This must be a complete URL or an absolute path.

## Feed Options

You can use the `feed` object to override standard properties or provide specific configurations for the RSS/Atom/JSON feed item.

### feed.title

* Type: `string`

Overrides the title used for this item in the feed.

### feed.description

* Type: `string`

Overrides the description used for this item in the feed.

### feed.content

* Type: `string`

Custom content for the feed item. If not provided, the page content is used.

### feed.author

* Type: `FeedAuthor[] | FeedAuthor`

The author(s) specific to this feed item.

::: details FeedAuthor format

```ts
interface FeedAuthor {
  /**
   * Author name
   */
  name?: string

  /**
   * Author email
   */
  email?: string

  /**
   * Author site
   *
   * @description json format only
   */
  url?: string

  /**
   * Author avatar
   *
   * @description json format only
   */
  avatar?: string
}
```

:::

### feed.contributor

* Type: `FeedContributor[] | FeedContributor`

The contributor(s) specific to this feed item.

::: details FeedContributor format

```ts
interface FeedContributor {
  /**
   * Author name
   */
  name?: string

  /**
   * Author email
   */
  email?: string

  /**
   * Author site
   *
   * @description json format only
   */
  url?: string

  /**
   * Author avatar
   *
   * @description json format only
   */
  avatar?: string
}
```

:::

### feed.guid

* Type: `string`

A unique identifier for the feed item.

::: tip
Ensure that every feed item has a globally unique GUID to prevent feed readers from marking updated items as new or duplicating them.
:::

---

---
url: /plugins/blog/feed/getter.md
---
# Feed Getter

You can take full control of how feed items are generated by configuring the `getter` object in the plugin options.

## getter.title

* Type: `(page: Page, app: App) => string`
* Details: Customizes the title of the feed item.

## getter.link

* Type: `(page: Page, app: App) => string`
* Details: Customizes the link (URL) of the feed item.

## getter.description

* Type: `(page: Page, app: App) => string | undefined`
* Details: Customizes the description or summary of the feed item.

::: tip

Since Atom supports HTML in summaries, you can return HTML content here. However, to ensure correct rendering, the returned string must start with the prefix `html:`.

:::

## getter.content

* Type: `(page: Page, app: App) => string`
* Details: Customizes the main content of the feed item.

## getter.author

* Type: `(page: Page, app: App) => FeedAuthor[]`
* Details: Retrieves the list of authors for the feed item.

::: tip

This getter should return an empty array `[]` if no author information is available.

:::

::: details FeedAuthor format

```ts
interface FeedAuthor {
  /**
   * Author name
   */
  name?: string

  /**
   * Author email
   */
  email?: string

  /**
   * Author site
   *
   * @description json format only
   */
  url?: string

  /**
   * Author avatar
   *
   * @description json format only
   */
  avatar?: string
}
```

:::

## getter.category

* Type: `(page: Page, app: App) => FeedCategory[] | undefined`
* Details: Retrieves the categories associated with the feed item.

::: details FeedCategory format

```ts
interface FeedCategory {
  /**
   * Category Name
   */
  name: string

  /**
   * A string that identifies a categorization taxonomy
   *
   * @description rss format only
   */
  domain?: string

  /**
   * The categorization scheme via a URI
   *
   * @description atom format only
   */
  scheme?: string
}
```

:::

## getter.enclosure

* Type: `(page: Page, app: App) => FeedEnclosure | undefined`
* Details: Specifies a media enclosure (e.g., audio, video, or attachment) for the feed item.

::: details FeedEnclosure format

```ts
interface FeedEnclosure {
  /**
   * Enclosure link
   */
  url: string

  /**
   * The MIME type of the enclosure
   *
   * @description should be a standard MIME Type, rss format only
   */
  type: string

  /**
   * Size in bytes
   *
   * @description rss format only
   */
  length?: number
}
```

:::

## getter.publishDate

* Type: `(page: Page, app: App) => Date | undefined`
* Details: Determines the publication date of the feed item.

## getter.lastUpdateDate

* Type: `(page: Page, app: App) => Date`
* Details: Determines the last modification date of the feed item.

## getter.image

* Type: `(page: Page, app: App) => string`
* Details: Sets a featured image for the feed item.

::: tip

Ensure the returned string is a full, absolute URL.

:::

## getter.contributor

* Type: `(page: Page, app: App) => FeedContributor[]`
* Details: Retrieves the list of contributors for the feed item.

::: tip

This getter should return an empty array `[]` if no contributor information is available.

:::

::: details FeedContributor format

```ts
interface FeedContributor {
  /**
   * Contributor name
   */
  name?: string

  /**
   * Contributor email
   */
  email?: string

  /**
   * Contributor site
   *
   * @description json format only
   */
  url?: string

  /**
   * Contributor avatar
   *
   * @description json format only
   */
  avatar?: string
}
```

:::

## getter.copyright

* Type: `(page: Page, app: App) => string | undefined`
* Details: Specifies the copyright information for the feed item.

---

---
url: /plugins/blog/feed/guide.md
---
# Guide

## Usage

The plugin generates feeds in the following three formats:

* Atom 1.0
* JSON 1.1
* RSS 2.0

Enable the formats you need by setting `atom`, `json`, or `rss` to `true` in the plugin options.

To ensure feed links are generated correctly, the `hostname` option is required.

## Readable Preview

Atom and RSS feeds include XSL templates, allowing them to be rendered as human-readable HTML when opened in a browser. Check out the [atom](/atom.xml) and [rss](/rss.xml) feeds of this site for a live demo.

To preview feeds in your development environment, set `devServer: true` in the plugin options. If your local setup differs from the default `http://localhost:{port}`, you should also configure `devHostname`.

## Channel Settings

You can customize global feed metadata via the `channel` option.

We recommend configuring the following fields:

* `channel.pubDate`: Set to the current ISOString to indicate the feed generation time.
* `channel.ttl`: Define the content update frequency (in minutes).
* `channel.copyright`: Specify copyright information.
* `channel.author`: Set the default author for the channel.

For a complete list of options and their default values, please refer to [Channel Config](./channel.md).

## Feed Generation

By default, all articles are included in the feed.

You can control individual feed items using the `feed` option in the page frontmatter. See [Frontmatter Config](./frontmatter.md) for mapping details.

For complete control over the item generation logic, you can configure the `getter` function in the plugin options. See [Configuration → Feed Getter](./getter.md) for details.

### I18n Support

The plugin automatically generates separate feeds for each language.

You can provide language-specific configurations via the `locales` option.

---

---
url: /plugins/development/index.md
---
# Development Plugins

---

---
url: /plugins/development/active-header-links.md
---
# active-header-links

This plugin will listen to page scroll event. When the page scrolls to a certain *header anchor*, this plugin will change the route hash to that *header anchor* if there is a corresponding *header link*.

This plugin is mainly used to develop themes, and has been integrated into the default theme. You won't need to use it directly in most cases.

## Usage

```bash
npm i -D @vuepress/plugin-active-header-links@next
```

```ts title=".vuepress/config.ts"
import { activeHeaderLinksPlugin } from '@vuepress/plugin-active-header-links'

export default {
  plugins: [
    activeHeaderLinksPlugin({
      // options
    }),
  ],
}
```

## Options

### headerLinkSelector

* Type: `string`

* Default: `'a.vp-sidebar-item'`

* Details:

  Selector of *header link*.

  If a *header anchor* does not have a corresponding *header link*, this plugin won't change the route hash to that anchor when scrolling to it.

### headerAnchorSelector

* Type: `string`

* Default: `'.header-anchor'`

* Details:

  Selector of *header anchor*.

  You don't need to specify this option unless you have changed the `permalinkClass` option of [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor#readme) via [markdown.anchor](https://vuejs.press/reference/config.html#markdown-anchor).

* Also see:
  * [Guide > Markdown > Syntax Extensions > Header Anchors](https://vuejs.press/guide/markdown.html#header-anchors)

### delay

* Type: `number`

* Default: `200`

* Details:

  The delay of the debounced scroll event listener.

### offset

* Type: `number`

* Default: `5`

* Details:

  Even if you click the link of the *header anchor* directly, the `scrollTop` might not be exactly equal to `offsetTop` of the *header anchor*, so we add an offset to avoid the error.

---

---
url: /plugins/development/git.md
---
# git

This plugin collects Git information for your pages, including creation and update timestamps, contributor lists, and changelogs.

The [lastUpdated](../../themes/default/config.md#lastupdated) and [contributors](../../themes/default/config.md#contributors) features in the default theme are powered by this plugin.

This plugin is primarily intended for theme development. In most cases, you will not need to use it directly.

## Usage

```bash
npm i -D @vuepress/plugin-git@next
```

```ts title=".vuepress/config.ts"
import { gitPlugin } from '@vuepress/plugin-git'

export default {
  plugins: [
    gitPlugin({
      // options
    }),
  ],
}
```

## Git Repository

This plugin requires your project to be located within a [Git Repository](https://git-scm.com/book/en/Git-Basics-Getting-a-Git-Repository) to properly collect data from the commit history.

Ensure that the full commit history is available when building your site. CI workflows often use [--depth 1](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt) when cloning repositories to improve performance, which prevents the plugin from accessing the necessary history. You must disable this shallow clone behavior (usually by setting `fetch-depth: 0`) for the plugin to work correctly in CI environments.

::: warning
This plugin may significantly increase data preparation time during builds, especially for projects with a large number of pages. You may consider disabling this plugin in `dev` mode to improve the development experience.
:::

## Options

### createdTime

* Type: `boolean`

* Default: `true`

* Details:

  Whether to collect the creation timestamp of the page.

### updatedTime

* Type: `boolean`

* Default: `true`

* Details:

  Whether to collect the update timestamp of the page.

### contributors

* Type: `boolean | ContributorsOptions`

  ```ts
  interface ContributorInfo {
    /**
     * The contributor's username on the Git hosting service
     */
    username: string
    /**
     * The contributor's display name on the page. Defaults to `username`.
     */
    name?: string
    /**
     * Aliases for the contributor.
     * Useful when a contributor's local Git username differs from their
     * hosting service username. Use aliases to map them to the correct account.
     */
    alias?: string[] | string
    /**
     * The primary email of the contributor
     */
    email?: string
    /**
     * Alternative emails for the contributor (e.g., emails used in past commits).
     */
    emailAlias?: string[] | string
    /**
     * The avatar URL of the contributor.
     *
     * If the hosting service is `github`, this can be left blank,
     * as the plugin will automatically populate it.
     */
    avatar?: string
    /**
     * The profile URL of the contributor.
     *
     * If the hosting service is `github`, this can be left blank,
     * as the plugin will automatically populate it.
     */
    url?: string
  }

  interface ContributorsOptions {
    /**
     * Pre-defined contributor information
     */
    info?: ContributorInfo[]

    /**
     * Whether to include avatars in contributor information
     * @default false
     */
    avatar?: boolean

    /**
     * The pattern for avatar URLs
     * - `:username` - Contributor's username
     *
     * @example 'https://github.com/:username'
     */
    avatarPattern?: string

    /**
     * A function to transform the contributors list (e.g., to deduplicate or sort).
     * Accepts the list collected by the plugin and returns the transformed list.
     */
    transform?: (contributors: GitContributorInfo[]) => GitContributorInfo[]
  }
  ```

* Default: `true`

* Details:

  Whether to collect contributor information for the page.

### changelog

* Type: `boolean | ChangelogOptions`

  ```ts
  interface ChangelogOptions {
    /**
     * The maximum number of changelog entries to collect
     */
    maxCount?: number

    /**
     * The URL of the Git repository, e.g., https://github.com/vuepress/ecosystem
     */
    repoUrl?: string

    /**
     * The pattern for commit URLs
     *
     * - `:repo` - The URL of the Git repository
     * - `:hash` - The hash of the commit
     *
     * @default ':repo/commit/:hash'
     */
    commitUrlPattern?: string

    /**
     * The pattern for issue URLs
     *
     * - `:repo` - The URL of the Git repository
     * - `:issue` - The ID of the issue
     *
     * @default ':repo/issues/:issue'
     */
    issueUrlPattern?: string

    /**
     * The pattern for tag URLs
     *
     * - `:repo` - The URL of the Git repository
     * - `:tag` - The name of the tag
     *
     * @default ':repo/releases/tag/:tag'
     */
    tagUrlPattern?: string
  }
  ```

* Default: `false`

* Details:

  Whether to collect the changelog for the page.

### filter

* Type: `(page: Page) => boolean`

* Details:

  A function to filter pages. Git information will only be collected if this function returns `true`.

### locales

* Type: `Record<string, GitLocaleData>`

  ```ts
  export interface GitLocaleData {
    /**
     * The title for the contributors section
     */
    contributors: string

    /**
     * The title for the changelog section
     */
    changelog: string

    /**
     * The text representing a commit "on" a specific date
     */
    timeOn: string

    /**
     * The text for the "View Changelog" button
     */
    viewChangelog: string

    /**
     * The text for "Latest Updated"
     */
    latestUpdateAt: string
  }
  ```

* Details:

  Locale configuration, primarily used by the [Git Components](#component).

## Frontmatter

### gitInclude

* Type: `string[]`

* Details:

  An array of relative file paths. The Git history of these files will be included when calculating the current page's data (e.g., timestamps and contributors).

* Example:

```md
---
gitInclude:
  - relative/path/to/file1
  - relative/path/to/file2
---
```

### contributors

* Type: `boolean | string[]`

* Details:

  Controls the collection of contributor information for the current page. This overrides the global [contributors](#contributors) option.

  * `true` - Enable collection.
  * `false` - Disable collection.
  * `string[]` - A list of additional contributors. Useful for manually specifying contributors who may not appear in the Git history.

### changelog

* Type: `boolean`

* Details:

  Whether to collect the changelog for the current page. This overrides the global [changelog](#changelog) option.

## Composables

You can import the following composables from `@vuepress/plugin-git/client`.

### useChangelog

Returns the changelog for the current page.

```ts
export interface CoAuthorInfo {
  /**
   * Co-author name
   */
  name: string
  /**
   * Co-author email
   */
  email: string
}

export interface GitChangelogItem extends GitChangelogInfo {
  /**
   * Commit hash
   */
  hash: string
  /**
   * Unix timestamp in milliseconds
   */
  time: number
  /**
   * Commit message
   */
  message: string
  /**
   * The URL of the commit
   */
  commitUrl?: string
  /**
   * Release tag associated with the commit
   */
  tag?: string
  /**
   * The URL of the release tag
   */
  tagUrl?: string
  /**
   * Commit author name
   */
  author: string
  /**
   * Commit author email
   */
  email: string

  /**
   * The co-authors of the commit
   */
  coAuthors?: CoAuthorInfo[]

  /**
   * Formatted date string of the commit
   */
  date: string
}

export const useChangelog: (
  enabled?: MaybeRefOrGetter<boolean>,
) => ComputedRef<GitChangelogItem[]>
```

### useContributors

Returns the list of contributors for the current page.

```ts
export interface GitContributorInfo {
  /**
   * Contributor display name
   */
  name: string
  /**
   * Contributor email
   */
  email: string

  /**
   * Contributor username on the Git hosting service
   */
  username: string
  /**
   * Number of commits
   */
  commits: number
  /**
   * Contributor avatar URL
   */
  avatar?: string
  /**
   * Contributor profile URL
   */
  url?: string
}

export const useContributors: (
  enabled?: MaybeRefOrGetter<boolean>,
) => ComputedRef<GitContributorInfo[]>
```

### useLastUpdated

Returns the last updated time of the current page.

```ts
export interface LastUpdated {
  /**
   * The Date object of the last updated time
   */
  date: Date
  /**
   * The ISO string of the last updated time
   */
  iso: string
  /**
   * The formatted text of the last updated time
   */
  text: string
  /**
   * The locale string for the date format
   */
  locale: string
}

export const useLastUpdated: (
  enabled?: MaybeRefOrGetter<boolean>,
) => ComputedRef<LastUpdated | null>
```

## Page Data

This plugin injects a `git` field into the page data.

You can access the collected Git information via the page data object:

```ts
import type { GitPluginPageData } from '@vuepress/plugin-git'
import { usePage } from 'vuepress/client'

export default {
  setup(): void {
    const page = usePage<GitPluginPageData>()
    console.log(page.value.git)
  },
}
```

### git.createdTime

* Type: `number`

* Details:

  The Unix timestamp (in milliseconds) of the page's first commit.

  This value reflects the earliest commit timestamp among the current page and any files listed in [gitInclude](#gitinclude).

### git.updatedTime

* Type: `number`

* Details:

  The Unix timestamp (in milliseconds) of the page's last commit.

  This value reflects the latest commit timestamp among the current page and any files listed in [gitInclude](#gitinclude).

### git.contributors

* Type: `GitContributorInfo[]`

```ts
interface GitContributorInfo {
  // display name
  name: string
  email: string
  // username on the git hosting service
  username: string
  commits: number
  avatar?: string
  url?: string
}
```

* Details:

  The list of contributors for the page.

  This list includes contributors from the current page and any files listed in [gitInclude](#gitinclude).

### git.changelog

* Type: `GitChangelogInfo[]`

```ts
interface CoAuthorInfo {
  /**
   * Co-author name
   */
  name: string
  /**
   * Co-author email
   */
  email: string
}

interface GitChangelogInfo {
  /**
   * Commit hash
   */
  hash: string
  /**
   * Unix timestamp in milliseconds
   */
  time: number
  /**
   * Commit message
   */
  message: string
  /**
   * The URL of the commit
   */
  commitUrl?: string
  /**
   * Release tag associated with the commit
   */
  tag?: string
  /**
   * The URL of the release tag
   */
  tagUrl?: string
  /**
   * Commit author name
   */
  author: string
  /**
   * Commit author email
   */
  email: string

  /**
   * The co-authors of the commit
   */
  coAuthors?: CoAuthorInfo[]
}
```

* Details:

  The changelog for the page.

  This list includes commit history from the current page and any files listed in [gitInclude](#gitinclude).

## Git Component{#component}

The plugin registers global components for displaying Git information, which can be easily used within themes.

### GitContributors

Displays a list of contributors for the current page.

```vue{4}
<template>
  <div vp-content>
    <Content />
    <GitContributors />
  </div>
</template>
```

**Preview:**

### GitChangelog

Displays the changelog for the current page.

```vue{4}
<template>
  <div vp-content>
    <Content />
    <GitChangelog />
  </div>
</template>
```

**Preview:**

---

---
url: /plugins/development/palette.md
---
# palette

Provide palette support for your theme.

This plugin is primarily designed for theme development and has been integrated into the default theme. You typically won't need to use it directly in most cases.

For theme authors, this plugin provides users with the ability to customize styles.

## Usage

```bash
npm i -D @vuepress/plugin-palette@next
```

```ts title=".vuepress/config.ts"
import { palettePlugin } from '@vuepress/plugin-palette'

export default {
  plugins: [
    palettePlugin({
      // options
    }),
  ],
}
```

## Palette and Style

This plugin provides a `@vuepress/plugin-palette/palette` (palette file) and a `@vuepress/plugin-palette/style` (style file) for import in your theme styles.

The palette file is used to define style variables, so it's typically imported at the beginning of your theme styles. For example, users can define [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties), [SASS variables](https://sass-lang.com/documentation/variables), [LESS variables](http://lesscss.org/features/#variables-feature), or [Stylus variables](https://stylus-lang.com/docs/variables.html) in the palette, and then you can use those variables in your theme styles.

The style file is used to override default styles or add extra styles, so it's typically imported at the end of your theme styles.

## Usage

Use this plugin in your theme, assuming you're using SASS:

```ts
import { palettePlugin } from '@vuepress/plugin-palette'

export default {
  // ...
  plugins: [
    palettePlugin({ preset: 'sass' }),
    // ...
  ],
}
```

### Usage of Palette

Import the plugin's palette file wherever your theme needs to use the corresponding variables, such as in the `Layout.vue` file:

```vue
<template>
  <h1 class="palette-title">Hello, Palette!</h1>
</template>

<style lang="scss">
/* import variables from the plugin's palette file */
@use '@vuepress/plugin-palette/palette' as *;

/* set default value for variables */
$color: red !default;

/* use variables in your styles */
.palette-title {
  color: $color;
}
</style>
```

Then users can customize variables in `.vuepress/styles/palette.scss`:

```scss
$color: green;
```

### Usage of Style

Import the plugin's style file after your theme's styles, for example, in the `clientConfigFile`:

```ts
// import your theme's style file
import 'path/to/your/theme/style'
// import the plugin's style file
import '@vuepress/plugin-palette/style'
```

Then users can add extra styles in `.vuepress/styles/index.scss` and override your theme's default styles:

```scss
h1 {
  font-size: 2.5rem;
}
```

## Options

### preset

* Type: `'css' | 'less' | 'sass' | 'stylus'`

* Default: `'css'`

* Details:

  Set preset for other options.

  If you don't need advanced customization of the plugin, it's recommended to set only this option and omit others.

### userPaletteFile

* Type: `string`

* Default:
  * css: `'.vuepress/styles/palette.css'`
  * less: `'.vuepress/styles/palette.less'`
  * sass: `'.vuepress/styles/palette.scss'`
  * stylus: `'.vuepress/styles/palette.styl'`

* Details:

  File path of the user palette file, relative to source directory.

  The default value depends on the [preset](#preset) option.

  This file is where users define style variables, and it's recommended to keep the default file path as a convention.

### tempPaletteFile

* Type: `string`

* Default:
  * css: `'styles/palette.css'`
  * less: `'styles/palette.less'`
  * sass: `'styles/palette.scss'`
  * stylus: `'styles/palette.styl'`

* Details:

  File path of the generated palette temp file, relative to temp directory.

  The default value depends on the [preset](#preset) option.

  You should import the palette file via `'@vuepress/plugin-palette/palette'` alias, so you don't need to change this option in most cases.

### userStyleFile

* Type: `string`

* Default:
  * css: `'.vuepress/styles/index.css'`
  * less: `'.vuepress/styles/index.less'`
  * sass: `'.vuepress/styles/index.scss'`
  * stylus: `'.vuepress/styles/index.styl'`

* Details:

  File path of the user style file, relative to source directory.

  The default value depends on the [preset](#preset) option.

  This file is where users override default styles or add extra styles, and it's recommended to keep the default file path as a convention.

### tempStyleFile

* Type: `string`

* Default:
  * css: `'styles/index.css'`
  * less: `'styles/index.less'`
  * sass: `'styles/index.scss'`
  * stylus: `'styles/index.styl'`

* Details:

  File path of the generated style temp file, relative to temp directory.

  The default value depends on the [preset](#preset) option.

  You should import the style file via `'@vuepress/plugin-palette/style'` alias, so you don't need to change this option in most cases.

### importCode

* Type: `(filePath: string) => string`

* Default:
  * css: `` (filePath) => `@import '${filePath}';\n` ``
  * less: `` (filePath) => `@import '${filePath}';\n` ``
  * sass: `` (filePath) => `@forward 'file:///${filePath}';\n` ``
  * stylus: `` (filePath) => `@require '${filePath}';\n` ``

* Details:

  Function to generate import code.

  The default value depends on the [preset](#preset) option.

  This option is used for generating [tempPaletteFile](#temppalettefile) and [tempStyleFile](#tempstylefile), and you don't need to change this option in most cases.

---

---
url: /plugins/development/reading-time.md
---
# reading-time

This plugin analyzes your page content to generate word counts and estimated reading times.

## Usage

```bash
npm i -D @vuepress/plugin-reading-time@next
```

```ts title=".vuepress/config.ts"
import { readingTimePlugin } from '@vuepress/plugin-reading-time'

export default {
  plugins: [
    readingTimePlugin({
      // options
    }),
  ],
}
```

## Page Data (Node.js Side)

The plugin calculates statistics for every page and injects them into the `page.data.readingTime` property. This object contains:

* `minutes`: The estimated reading time in minutes (`number`).
* `words`: The total word count (`number`).

You can access this data directly within Node.js during the build process, such as inside the `extendsPage` or `onInitialized` lifecycles:

```ts
export default {
  // ...
  extendsPage: (page) => {
    // Access reading time data for the current page being processed
    console.log(page.data.readingTime) // { minutes: 3.2, words: 934 }
  },

  onInitialized: (app) => {
    // Iterate through all pages in the VuePress app
    app.pages.forEach((page) => {
      console.log(page.data.readingTime) // { minutes: 3.2, words: 934 }
    })
  },
}
```

## Composition API (Client Side)

To display reading time information in your theme or components, you can use the composition APIs provided by the client module.

Import `useReadingTimeData` for raw numbers or `useReadingTimeLocale` for localized strings:

```vue
<script setup lang="ts">
import {
  useReadingTimeData,
  useReadingTimeLocale,
} from '@vuepress/plugin-reading-time/client'

// Get raw values (e.g., for custom logic or sorting)
const readingTimeData = useReadingTimeData() // { minutes: 1.1, words: 100 }

// Get localized text based on current site configuration
const readingTimeLocale = useReadingTimeLocale() // { time: "1 minute", words: "100 words" }
</script>
```

## Options

### wordPerMinute

* Type: `number`
* Default: `300`
* Details: Reading speed in words per minute.

### locales

* Type: `ReadingTimePluginLocaleConfig`

  ```ts
  interface ReadingTimePluginLocaleData {
    /**
     * Word template, `$word` will be automatically replaced by actual words
     */
    word: string

    /**
     * Text for less than one minute
     */
    less1Minute: string

    /**
     * Time template, `$time` will be automatically replaced by actual time
     */
    time: string
  }

  interface ReadingTimePluginLocaleConfig {
    [localePath: string]: Partial<ReadingTimePluginLocaleData>
  }
  ```

* Details: Locale config for reading time text and word count text.

::: details Built-in Supported Languages

* **Simplified Chinese** (zh-CN)
* **Traditional Chinese** (zh-TW)
* **English (United States)** (en-US)
* **German** (de-DE)
* **Russian** (ru-RU)
* **Ukrainian** (uk-UA)
* **Vietnamese** (vi-VN)
* **Portuguese** (pt)
* **Polish** (pl-PL)
* **French** (fr-FR)
* **Spanish** (es-ES)
* **Slovak** (sk-SK)
* **Japanese** (ja-JP)
* **Turkish** (tr-TR)
* **Korean** (ko-KR)
* **Finnish** (fi-FI)
* **Indonesian** (id-ID)
* **Dutch** (nl-NL)

:::

## Client API

You can import and use these APIs from `@vuepress/plugin-reading-time/client`:

::: tip These APIs won't throw errors even if you disable the plugin.

:::

### useReadingTimeData

```ts
interface ReadingTime {
  /** Expected reading time in minutes */
  minutes: number
  /** Words count of content */
  words: number
}

const useReadingTimeData: () => ComputedRef<ReadingTime | null>
```

Returns `null` when the plugin is disabled.

### useReadingTimeLocale

```ts
interface ReadingTimeLocale {
  /** Expected reading time text in locale */
  time: string
  /** Word count text in locale */
  words: string
}

const useReadingTimeLocale: () => ComputedRef<ReadingTimeLocale>
```

## Theme Integration

For plugin and theme authors, a programmatic "Use API" is available. This approach is recommended over adding the plugin to the `plugins` array directly in your theme, as it handles registration ordering and prevents duplicate registration.

```js title="your plugin or theme entry"
import { useReadingTimePlugin } from '@vuepress/plugin-reading-time'

export default (options) => (app) => {
  useReadingTimePlugin(app, {
    // your options
  })

  return {
    name: 'vuepress-plugin-xxx', // or vuepress-theme-xxx
  }
}
```

::: tip Why use the "Use API"?

1. **Singleton Pattern**: VuePress warns if a plugin is registered multiple times (where only the first takes effect). `useReadingTimePlugin` checks for existing instances and skips registration if already present.
2. **Execution Order**: If you rely on reading time data within the `extendsPage` lifecycle, the reading time plugin must execute *before* your code. `useReadingTimePlugin` ensures the correct initialization order so `page.data.readingTime` is available when you need it.

:::

If you need to force a specific configuration or reset the plugin state, you can use `removeReadingTimePlugin`:

```js title="your plugin or theme entry"
import { useReadingTimePlugin } from '@vuepress/plugin-reading-time'

export default (options) => (app) => {
  // Remove any previously registered instances of the reading time plugin
  removeReadingTimePlugin(app)

  // Register the plugin again to ensure your specific options take precedence
  useReadingTimePlugin(app, {
    // your options
  })

  return {
    name: 'vuepress-plugin-xxx', // or vuepress-theme-xxx
  }
}
```

---

---
url: /plugins/development/rtl.md
---
# RTL

This plugin sets text direction to RTL on configured locales.

## Usage

```bash
npm i -D @vuepress/plugin-rtl@next
```

```ts title=".vuepress/config.ts"
import { rtlPlugin } from '@vuepress/plugin-rtl'

export default {
  plugins: [
    rtlPlugin({
      // options
      locales: ['/ar/'],
    }),
  ],
}
```

## Demo

## Options

### locales

* Type: `string[]`
* Default: `['/']`
* Details: RTL locale paths to enable RTL layout.

### selector

* Type: `SelectorOptions`

  ```ts
  interface SelectorOptions {
    [cssSelector: string]: {
      [attr: string]: string
    }
  }
  ```

* Default: `{ 'html': { dir: 'rtl' } }`

* Details: Selector configuration to enable RTL layout. The default settings mean that the `dir` attribute of the `html` element will be set to `rtl` in RTL locales.

---

---
url: /plugins/development/sass-palette/index.md
---
# sass-palette

This plugin is mainly facing plugin and theme developers, it is more powerful than [`@vuepress/plugin-palette`](../palette.md).

::: tip

You should manually install these deps in your project:

* When using Vite bundler: `sass-embedded`
* When using Webpack bundler: `sass-embedded` and `sass-loader`

:::

## Usage

You must invoke `useSassPalettePlugin` function during plugin initialization to use this plugin.

```bash
npm i -D @vuepress/plugin-sass-palette@next
```

```js title="Your plugin or theme entry"
import { useSassPalettePlugin } from '@vuepress/plugin-sass-palette'

export const yourPlugin = (options) => (app) => {
  useSassPalettePlugin(app, {
    // plugin options
  })

  return {
    // your plugin api
  }
}
```

---

---
url: /plugins/development/sass-palette/config.md
---
# Config

## Options

### id

* Type: `string`
* Required: Yes
* Details: The unique identifier for the plugin instance. This is used to scope the style system and avoid conflicts between different plugins or themes.

### config

* Type: `string`
* Default: `` `.vuepress/styles/${id}-config.scss` ``
* Details: The path to the user's Sass configuration file, relative to the source directory.

::: tip

This file is where users define Sass variables.

The default filename is prefixed with the `id` defined above.

:::

### defaultConfig

* Type: `string`
* Default: `"@vuepress/plugin-sass-palette/styles/default/config.scss"`
* Details: The absolute path to the default Sass configuration file.

::: tip

As a plugin developer, you should use this file to provide fallback values for variables using the `!default` flag.

:::

### palette

* Type: `string`
* Default: `` `.vuepress/styles/${id}-palette.scss` ``
* Details: The path to the user's palette file, relative to the source directory.

::: tip

This file allows users to control injected CSS variables. All variables defined here will be converted to kebab-case and injected into the CSS root.

The default filename is prefixed with the `id` defined above.

:::

### defaultPalette

* Type: `string`
* Details: The absolute path to the default palette file.

::: tip

As a plugin developer, you should use this file to provide default CSS variables via Sass variables using the `!default` flag. These will also be converted to kebab-case and injected.

:::

### generator

* Type: `string`
* Details:

  The absolute path to a custom generator file. This is used to derive new values based on the palette configuration.

  For example, you can use this to generate a `$theme-color-light` variable based on the `$theme-color` provided by the user.

### style

* Type: `string`
* Details: The path to the user's custom style file, relative to the source directory. This is used for standard CSS/Sass customization.

## Alias

The following aliases are available for import:

* **config**: `@sass-palette/${id}-config` (Derived from `id`)
* **palette**: `@sass-palette/${id}-palette` (Derived from `id`)
* **style**: `@sass-palette/${id}-style` (Only available when the `style` option is set)
* **helper**: `@sass-palette/helper`

---

---
url: /plugins/development/sass-palette/guide.md
---
# Guide

Compared to [`@vuepress/plugin-palette`](../palette.md), this plugin offers advanced styling capabilities:

* **Derived Styles:** Generate related styles based on user configuration.
* **Theme-like Customization:** Allow plugins to offer style customization similar to themes.
* **Style Isolation/Sharing:** Group applications across multiple plugins or themes via the `id` option.

To use this plugin effectively, you need to understand the **ID option** and three core styling concepts: **Configuration**, **Palette**, and **Generator**.

## ID Option

This plugin is designed to work across both plugins and themes (unlike the official palette plugin, which is restricted to themes).

The `id` option is the key mechanism for scoping. Calling `useSassPalette` creates a style system isolated by this ID. All generated aliases and module names will be prefixed with this ID.

This mechanism allows you to:

* **Share a style system:**
  By using the same ID, multiple plugins (or a theme and its plugins) can share variables.

  Since aliases are prefixed with the ID, you can use a unified set of style variables. Users can configure color variables, breakpoints, and other settings in a single file, and the changes will automatically apply to all themes and plugins using that ID.

  ::: tip Example
  `vuepress-theme-hope` uses the ID `hope`. Any plugin that also uses the ID `hope` will inherit the styles configured by the user for the theme.
  :::

* **Isolate styles:**
  By using different IDs, plugins will not affect each other. We recommend setting the `id` to your plugin name to ensure isolation.

  With default settings, users configure your plugin styles in the `.vuepress/styles` directory using Sass files starting with your ID. You access these variables via `${id}-config` and `${id}-palette`.

  ::: tip Example
  If `vuepress-theme-hope` uses ID `hope` and a separate plugin uses ID `abc`, they are completely independent. They access their specific variables via modules like `hope-config`/`hope-palette` and `abc-config`/`abc-palette` respectively.
  :::

* **Avoid side effects:**
  Calling the plugin multiple times with the same ID is safe and causes no conflicts.

## Config

The **Config** file is dedicated to **Sass variables**. These variables can be accessed via the `${id}-config` module.

You can specify a user configuration file (typically in `.vuepress/styles/`) and provide a default configuration file. The default file should use the `!default` flag to allow user overrides.

::: details Example

Invoking the plugin in `vuepress-plugin-abc`:

```js
useSassPalette(app, {
  id: 'abc',
  defaultConfig: 'vuepress-plugin-abc/styles/config.scss',
})
```

**User config file:**

```scss title=".vuepress/styles/abc-palette.scss"
$navbar-height: 3.5rem;
```

**Default config file:**

```scss title="vuepress-plugin-abc/styles/palette.scss"
$navbar-height: 2rem !default;
$sidebar-width: 18rem !default;
```

**Usage in plugin Sass files:**

```scss
// <style lang="scss"> block or directly imported scss
@debug abc-config.$navbar-height; // 3.5rem
@debug abc-config.$sidebar-width; // 18rem
```

:::

### Limitations

The plugin uses the `additionalData` option to inject the `${id}-config` module. This comes with limitations:

The `${id}-config` module is only available in:

* `<style lang="scss">` blocks in Vue SFC files.
* Sass files imported directly by script files (e.g., `import "./styles.scss"`).

If a Sass file is imported via `@use` or `@import` within another Sass file, the module will **not** be automatically available. In such cases, you must manually import it using `@use "@sass-palette/${id}-config";`.

## Palette

The **Palette** file is used for **CSS Variable** injection. Every variable defined here will be injected into the root stylesheet as a CSS variable with a kebab-case name.

The default user palette filename is `${id}-palette.scss`. Like the config file, you can provide a default palette file containing fallback values with `!default`.

::: details Example

Invoking the plugin in `vuepress-plugin-abc`:

```js
useSassPalette(app, {
  id: 'abc',
  defaultPalette: 'vuepress-plugin-abc/styles/palette.scss',
})
```

**User palette:**

```scss title=".vuepress/styles/abc-palette.scss"
$color-a: red;
```

**Default palette:**

```scss title="vuepress-plugin-abc/styles/palette.scss"
$color-a: blue !default;
$color-b: green !default;
```

**Resulting CSS:**

```scss
:root {
  --color-a: red;
  --color-b: green;
}
```

:::

The palette module is named `${id}-palette`. It shares the same `additionalData` limitations as the config module, requiring manual import in nested Sass files.

### Color Settings (Dark Mode)

To support light and dark modes, you can define color variables as a map containing `light` and `dark` keys. The plugin will automatically generate the appropriate CSS variables for each mode.

::: details Example

```scss
// User palette
$text-color: (
  light: #222,
  dark: #999,
);

// Default palette
$text-color: (
  light: #2c3e50,
  dark: #9e9e9e,
) !default;
$bg-color: (
  light: #fff,
  dark: #1e1e1e,
) !default;
```

**Generated CSS:**

```scss
:root {
  --text-color: #222;
  --bg-color: #fff;
}

[data-theme='dark'] {
  --text-color: #999;
  --bg-color: #1e1e1e;
}
```

:::

### Allowed Variable Types

Only **colors** (including light/dark maps), **lengths**, and **strings** are allowed in the palette. Other types will be discarded to ensure valid CSS variable generation.

:::: tip Why this limitation?

CSS variables usually represent visual properties (colors, dimensions). Restricting types prevents compilation errors. Complex values can still be passed as strings.

::: details Example

If you want a variable for transition properties:

```scss
// ❌ Incorrect: Regarded as a Sass list.
// Triggers a warning and will be dropped.
$moveTransition: width 0.3s ease;

// ✅ Correct: Wrapped in quotes.
// Result: :root { --move-transition: width 0.3s ease; }
$moveTransition: 'width 0.3s ease';
```

:::

::::

## Helper

The plugin exposes its internal Sass functions via a helper module. You can use this alias `@sass-palette/helper` to access utility functions for your own style logic.

## Generator

The **Generator** file allows you to create **derived values** based on variables from the palette or config files.

Variables defined in the generator are:

1. Injected as CSS variables (just like the Palette).
2. Available in the palette module for Sass usage.

::: details Example

You might need a lighter version of the user's theme color.

```scss
@use 'sass:color';
@use '@sass-palette/helper';

// Define a new variable based on an existing palette variable ($theme-color)
$theme-color-light: (
  light: color.scale(helper.get-color($theme-color), $lightness: 10%),
  dark: color.scale(helper.get-dark-color($theme-color), $lightness: 10%),
) !default;
```

You can also rely on config variables:

```scss
// Generator with id "abc"
@use 'sass:color';
@use '@sass-palette/abc-config';
@use '@sass-palette/helper';

$code-c-bg: abc-config.$highlighter == 'shiki'? #fff: #f8f8f8;
```

:::

## User Styles

Theme developers can use the `style` option to allow users to customize the site's appearance with standard CSS/Sass.

You must manually include the user style file by importing the alias `@sass-palette/${id}-style`. This should be imported **after** your theme's base styles to ensure user overrides take precedence.

::: tip
`@sass-palette/${id}-style` is a direct alias to the user's style file and can be imported in JS, TS, or Sass.
:::

---

---
url: /plugins/development/theme-data.md
---
# theme-data

Provide client data for your theme, with VuePress [i18n](https://vuejs.press/guide/i18n.html) support.

This plugin is mainly used to develop themes, and has been integrated into the default theme. You won't need to use it directly in most cases.

For theme authors, this plugin will help you use the same i18n mechanism as VuePress and the default theme. However, if you don't want to provide i18n support, or you want to implement your own approach, you don't need this plugin.

## Usage

```bash
npm i -D @vuepress/plugin-theme-data@next
```

```ts title=".vuepress/config.ts"
import { themeDataPlugin } from '@vuepress/plugin-theme-data'

export default {
  plugins: [
    themeDataPlugin({
      // options
    }),
  ],
}
```

## Options

### themeData

* Type: `ThemeData`

* Required: Yes

* Details:

  The theme data object that you want to use in client side.

  You can provide theme data in Node side via this option, and use it in client side via [useThemeData](#usethemedata) and [useThemeLocaleData](#usethemelocaledata).

* Example:

```ts title=".vuepress/config.ts"
export default {
  plugins: [
    themeDataPlugin({
      themeData: {
        foo: 'foo',
        locales: {
          '/zh/': {
            foo: 'zh-foo',
          },
        },
      },
    }),
  ],
}
```

::: warning
The theme data object will be processed by `JSON.stringify()` before forwarding to client side, so you should ensure that you provide a JSON-friendly object.
:::

## Composition API

### useThemeData

* Details:

  Returns the theme data ref object.

  The value is provided by [themeData](#themedata) option.

* Example:

```ts
import type { ThemeData } from '@vuepress/plugin-theme-data/client'
import { useThemeData } from '@vuepress/plugin-theme-data/client'

type MyThemeData = ThemeData<{
  foo: string
}>

export default {
  setup(): void {
    const themeData = useThemeData<MyThemeData>()
    console.log(themeData.value)
  },
}
```

### useThemeLocaleData

* Details:

  Returns the theme data ref object in current locale.

  The properties of current locale have been merged into the root-level properties.

* Example:

```ts
import type { ThemeData } from '@vuepress/plugin-theme-data/client'
import { useThemeLocaleData } from '@vuepress/plugin-theme-data/client'

type MyThemeData = ThemeData<{
  foo: string
}>

export default {
  setup(): void {
    const themeLocaleData = useThemeLocaleData<MyThemeData>()
    console.log(themeLocaleData.value)
  },
}
```

---

---
url: /plugins/development/toc.md
---
# toc

This plugin will provide a table-of-contents (TOC) component.

## Usage

```bash
npm i -D @vuepress/plugin-toc@next
```

```ts title=".vuepress/config.ts"
import { tocPlugin } from '@vuepress/plugin-toc'

export default {
  plugins: [
    tocPlugin({
      // options
    }),
  ],
}
```

## Differences with Markdown TOC Syntax

Similar to the [Table of Contents Markdown Syntax](https://vuejs.press/guide/markdown.html#table-of-contents), the TOC component provided by this plugin can be used in your markdown content directly:

```md
<!-- markdown toc syntax -->

[[toc]]

<!-- vue toc component -->
<Toc />
```

Both of them can be pre-rendered correctly in build mode. However, there are some differences between them.

The markdown syntax `[[toc]]` can only be used in markdown files. It is parsed by markdown-it, and the generated TOC is static content.

The component `<Toc/>` can be used in both markdown files and vue files. It is loaded by vue, and the generated TOC is a vue component.

This plugin can work together with [@vuepress/plugin-active-header-links](./active-header-links.md) by setting the [headerLinkSelector](./active-header-links.md#headerlinkselector) to match the `linkClass` option. When the page scrolls to a certain header anchor, the corresponding link will be added the `linkActiveClass` class name.

Therefore, this plugin is more useful for theme developers.

## Options

### componentName

* Type: `string`

* Default: `'Toc'`

* Details:

  Specify the name of the TOC component.

### headersOptions

* Type: `Partial<GetHeadersOptions>`

* Default: `{}`

* Details:

  Override the default values of the component [headersOptions](#headersoptions-1) prop.

### renderOptions

* Type: `Partial<TocPropsOptions>`

* Default: `{}`

* Details:

  Override the default values of the component [renderOptions](#renderoptions-1) prop.

## Component Props

The TOC component also accepts props for customization.

```vue
<template>
  <Toc
    :headers="headers"
    :headers-options="headersOptions"
    :render-options="renderOptions"
  />
</template>
```

### headers

* Type: `PageHeader[]`

```ts
interface PageHeader {
  level: number
  title: string
  slug: string
  children: PageHeader[]
}
```

* Details:

  Specify the headers array to render.

  If this prop is not specified, the headers of current page will be used.

### headersOptions

* Type: `Partial<GetHeadersOptions>`

  See [GetHeadersOptions](../../tools/helper/client.md#getheaders)

* Default:

  See [GetHeadersOptions](../../tools/helper/client.md#getheaders), it can be overridden by [headersOptions](#headersoptions) in plugin options.

* Details:

  Customize header extracting behavior.

### renderOptions

* Type: `TocRenderOptions`

```ts
interface TocRenderOptions {
  /**
   * Container tag name
   *
   * @default 'nav'
   */
  containerTag?: string

  /**
   * Container class name
   *
   * @default 'vuepress-toc'
   */
  containerClass?: string

  /**
   * List class name
   *
   * @default 'vuepress-toc-list'
   */
  listClass?: string

  /**
   * Item class name
   *
   * @default 'vuepress-toc-item'
   */
  itemClass?: string

  /**
   * Link tag type
   *
   * @default 'RouteLink'
   */
  linkTag?: 'a' | 'RouteLink' | 'RouterLink'

  /**
   * Link class name
   *
   * @default 'vuepress-toc-link'
   */
  linkClass?: string

  /**
   * Active link class name
   *
   * @default 'active'
   */
  linkActiveClass?: string

  /**
   * Active children link class name
   *
   * @default 'active'
   */
  linkChildrenActiveClass?: string
}
```

* Default:

  Following default values can be overridden by [renderOptions](#renderoptions) in plugin options.

  ```ts
  const defaultOptions = {
    containerTag: 'nav',
    containerClass: 'vuepress-toc',
    listClass: 'vuepress-toc-list',
    itemClass: 'vuepress-toc-item',
    linkTag: 'RouteLink',
    linkClass: 'vuepress-toc-link',
    linkActiveClass: 'active',
    linkChildrenActiveClass: 'active',
  }
  ```

* Details:

  Customize TOC component render behavior.

  If the `containerTag` is set to an empty string `''`, the `<nav>` container will be removed totally.

* Example:

  The rendered TOC component with default options looks like:

```vue
<template>
  <!-- container -->
  <nav class="vuepress-toc">
    <!-- list -->
    <ul class="vuepress-toc-list">
      <!-- item -->
      <li class="vuepress-toc-item">
        <!-- link -->
        <RouteLink class="vuepress-toc-link" to="#foo">Foo</RouteLink>
      </li>
      <!-- item with children -->
      <li class="vuepress-toc-item">
        <!-- link (children active) -->
        <RouteLink class="vuepress-toc-link active" to="#bar">Bar</RouteLink>
        <!-- list (children) -->
        <ul class="vuepress-toc-list">
          <!-- item -->
          <li class="vuepress-toc-item">
            <!-- link (active) -->
            <RouteLink class="vuepress-toc-link active" to="#bar-child">
              Bar Child
            </RouteLink>
          </li>
        </ul>
      </li>
    </ul>
  </nav>
</template>
```

---

---
url: /plugins/features/index.md
---
# Feature Plugins

---

---
url: /plugins/features/back-to-top.md
---
# back-to-top

This plugin adds a *back to top* button to your site. The button appears in the bottom right corner when scrolling down and scrolls the page to the top when clicked.

This plugin has been integrated into the default theme.

## Usage

```bash
npm i -D @vuepress/plugin-back-to-top@next
```

```ts title=".vuepress/config.ts"
import { backToTopPlugin } from '@vuepress/plugin-back-to-top'

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

## Options

### threshold

* Type: `number`
* Default: `100`
* Details: Scroll threshold distance to display the back to top button (in pixels)

### progress

* Type: `boolean`
* Default: `true`
* Details: Whether to display scroll progress

## Styles

You can customize the style of the *back to top* button via CSS variables:

@[code css](@vuepress/plugin-back-to-top/src/client/styles/vars.css)

---

---
url: /plugins/features/catalog.md
---
# catalog

This plugin automatically generates catalog pages and provides catalog components.

## Usage

```bash
npm i -D @vuepress/plugin-catalog@next
```

```ts title=".vuepress/config.ts"
import { catalogPlugin } from '@vuepress/plugin-catalog'

export default {
  plugins: [
    catalogPlugin({
      // Your options
    }),
  ],
}
```

First, you should set catalog info in `routeMeta`:

```ts title=".vuepress/config.ts"
import { catalogPlugin } from '@vuepress/plugin-catalog'

export default {
  extendsPage: (page) => {
    // Set catalog info in routeMeta
    page.routeMeta = {
      // Catalog title
      title: page.title,
      // ... other information
    }
  },
}
```

You can then import `defineCatalogInfoGetter` from `@vuepress/plugin-catalog/client` and use it in [client config file][client-config] to extract catalog info from route meta.

```ts title=".vuepress/client.ts"
import { defineCatalogInfoGetter } from '@vuepress/plugin-catalog/client'

defineCatalogInfoGetter((meta) => (meta.title ? { title: meta.title } : null))
```

Catalog info should contain:

* `title`: Catalog title
* `order`: Catalog order (optional)
* `content`: Catalog content component (optional)

::: tip Sorting with order

The plugin sorts pages by `order` in the following sequence:

```:no-line-numbers
// Positive numbers from small to large
Project with order 1
Project with order 2
...
Project with order 10
...
// Projects without order
Project without order
Project without order
...
// Negative numbers from small to large
Project with order -10
// ...
Project with order -2
Project with order -1
```

:::

## Options

### level&#x20;

* Type: `1 | 2 | 3`
* Default: `3`
* Details: Maximum depth of catalog items.

### index&#x20;

* Type: `boolean`
* Default: `false`
* Details: Whether to show index numbers for catalog items.

### frontmatter

* Type: `(path: string) => Record<string, any>`
* Details: Frontmatter getter for generated pages.
* Example:

  ```ts title=".vuepress/config.ts"
  import { catalogPlugin } from '@vuepress/plugin-catalog'

  export default {
    plugins: [
      catalogPlugin({
        frontmatter: (path) => ({
          // Frontmatter you want
          // You may customize title, author, time, etc.
        }),
      }),
    ],
  }
  ```

### exclude

* Type: `(RegExp | string)[]`
* Default: `[]`
* Details:

  Catalog page path to be excluded during generation.

  * `"/foo/"` means only exclude catalog page generation at `/foo/` folder.
  * `/^\/foo\//` means exclude catalog page generation at `/foo/` folder and its subfolders.

  ::: tip 404 pages will be automatically excluded.

  :::

### component

* Type: `string`
* Details: Component name to use as the catalog component.

### locales

* Type: `CatalogPluginLocaleConfig`

  ```ts
  interface CatalogPluginLocaleData {
    /**
     * Catalog title
     */
    title: string

    /**
     * Empty hint
     */
    empty: string
  }

  interface CatalogPluginLocaleConfig {
    [localePath: string]: Partial<CatalogPluginLocaleData>
  }
  ```

* Details: Locales configuration for catalog component.

::: details Built-in Supported Languages

* **Simplified Chinese** (zh-CN)
* **Traditional Chinese** (zh-TW)
* **English (United States)** (en-US)
* **German** (de-DE)
* **Russian** (ru-RU)
* **Ukrainian** (uk-UA)
* **Vietnamese** (vi-VN)
* **Portuguese** (pt)
* **Polish** (pl-PL)
* **French** (fr-FR)
* **Spanish** (es-ES)
* **Slovak** (sk-SK)
* **Japanese** (ja-JP)
* **Turkish** (tr-TR)
* **Korean** (ko-KR)
* **Finnish** (fi-FI)
* **Indonesian** (id-ID)
* **Dutch** (nl-NL)

:::

## Client Options

### defineCatalogInfoGetter

```ts
interface CatalogInfo {
  /** Catalog title */
  title: string
  /** Catalog order */
  order?: number
  /** Catalog content */
  content?: Component
}

type CatalogInfoGetter = (meta: Record<string, unknown>) => CatalogInfo | null

const defineCatalogInfoGetter: (options: CatalogInfoGetter) => void
```

Customizes how to extract catalog info from route meta.

## Components

### Catalog

* Details:

  This plugin globally registers a `<Catalog />` component by default (unless you set the `component` option).

  You can use `<Catalog />` in theme layouts or directly in Markdown files.

  The component supports four props:

  * `level`: Changes the display depth (maximum 3 levels), default is `3`.
  * `base`: Displays catalog of the specified folder, default is the current folder.
  * `index`: Adds index numbers to catalog items, default is no numbers.
  * `hideHeading`: Hides the component title, default is to display the `Catalog` title.

[client-config]: https://vuejs.press/guide/configuration.html#client-config-file

## Styles

You can customize catalog styles via CSS variables:

@[code css](@vuepress/plugin-catalog/src/client/styles/vars.css)

---

---
url: /plugins/features/copy-code.md
---
# copy-code

This plugin will automatically add a copy button to the top right corner of each code block on PC devices.

This plugin has been integrated into the default theme.

## Usage

```bash
npm i -D @vuepress/plugin-copy-code@next
```

```ts title=".vuepress/config.ts"
import { copyCodePlugin } from '@vuepress/plugin-copy-code'

export default {
  plugins: [
    copyCodePlugin({
      // options
    }),
  ],
}
```

## Options

### selector

* Type: `string | string[]`
* Default: `'[vp-content] div[class*="language-"] pre'`
* Details:

  Code block selector

### showInMobile

* Type: `boolean`
* Default: `false`
* Details:

  Whether to display copy button on the mobile device

### duration

* Type: `number`
* Default: `2000`
* Details:

  Hint display time, setting it to `0` will disable the hint.

### ignoreSelector

* Type: `string[] | string`
* Default: `""`
* Details:

  Elements selector in code blocks, used to ignore related elements when copying.

  For example, `['.token.comment']` will ignore nodes with the class name `.token.comment` in code blocks (which in `prismjs` refers to ignoring comments).

### inline

* Type: `string[] | string | boolean`
* Default: `false`
* Details:

  Whether to copy inline code content when double click.

  * `boolean`: Whether to copy inline code content when double click.
  * `string | string[]`: The selector of inline code.

### transform&#x20;

* Type: `(preElement: HTMLPreElement) => void`

* Default: `undefined`

* Details:

  A transformer to modify the content of the code block in the `<pre>` element before copying. This option is only valid when using `useCopyCode()`.

* Example:

  ```ts title=".vuepress/client.ts"
  import { useCopyCode } from '@vuepress/plugin-copy-code/client'

  export default {
    setup(): void {
      useCopyCode({
        transform: (preElement) => {
          // Remove all `.ignore` elements
          preElement.querySelectorAll('.ignore').forEach((el) => el.remove())
          // insert copyright
          preElement.innerHTML += `\n Copied by VuePress`
        },
        // ...other options
      })
    },
  }
  ```

### locales

* Type: `CopyCodePluginLocaleConfig`

  ```ts
  interface CopyCodePluginLocaleData {
    /**
     * Copy text
     */
    copy: string

    /**
     * Copied text
     */
    copied: string
  }

  interface CopyCodePluginLocaleConfig {
    [localePath: string]: Partial<CopyCodePluginLocaleData>
  }
  ```

* Details:

  Locales config for copy code plugin.

* Example:

  ```ts title=".vuepress/config.ts"
  import { copyCodePlugin } from '@vuepress/plugin-copy-code'

  export default {
    locales: {
      '/': {
        // this is a supported language
        lang: 'en-US',
      },
      '/xx/': {
        // the plugin does not support this language
        lang: 'mm-NN',
      },
    },

    plugins: [
      copyCodePlugin({
        locales: {
          '/': {
            // Override copy button label text
            copy: 'Copy Codes from code block',
          },

          '/xx/': {
            // Complete locale config for `mm-NN` language here
          },
        },
      }),
    ],
  }
  ```

::: details Built-in Supported Languages

* **Simplified Chinese** (zh-CN)
* **Traditional Chinese** (zh-TW)
* **English (United States)** (en-US)
* **German** (de-DE)
* **German (Australia)** (de-AT)
* **Russian** (ru-RU)
* **Ukrainian** (uk-UA)
* **Vietnamese** (vi-VN)
* **Portuguese** (pt)
* **Polish** (pl-PL)
* **French** (fr-FR)
* **Spanish** (es-ES)
* **Slovak** (sk-SK)
* **Japanese** (ja-JP)
* **Turkish** (tr-TR)
* **Korean** (ko-KR)
* **Finnish** (fi-FI)
* **Indonesian** (id-ID)
* **Dutch** (nl-NL)

:::

## Styles

You can customize the icon of the *copy button* via CSS variables:

@[code{1-6} css](@vuepress/plugin-copy-code/src/client/styles/vars.css)

---

---
url: /plugins/features/copyright.md
---
# copyright

This plugin can automatically append copyright information when visitors copy content from your site, and can also prohibit site copying or selection.

## Usage

```bash
npm i -D @vuepress/plugin-copyright@next
```

```ts title=".vuepress/config.ts"
import { copyrightPlugin } from '@vuepress/plugin-copyright'

export default {
  plugins: [
    copyrightPlugin({
      // options
    }),
  ],
}
```

### Enabling Copyright

This plugin **is disabled globally by default**, you can:

* Manually enable it by setting `copy: true` in page frontmatter
* Set `global: true` in plugin options to enable it globally, and set `copy: false` in page frontmatter to disable it.

To avoid disturbing visitors, copyright information will be appended only when the copied content length is greater than 100. Set `triggerLength` in plugin options if you want to change this threshold, or set `copy.triggerLength` in page frontmatter.

You can set default author and license information via `author` and `license` in plugin options.

If your site have different authors and license in different pages, you can set `authorGetter` and `licenseGetter` with function `(page: Page) => string` that takes the current page object as parameter and returns the corresponding information.

The plugin will generate copyright information from author, license, and page link via template by default, and append it when copying. If you think that this is not flexible enough, you can set `copyrightGetter` option to return a completely customized information with Page object or return null to use the default template.

### Disable Copy and Selection

If you want to prevent users copying long content, you can set `maxLength` in plugin options to customize this limit, or set `copy.maxLength` in page frontmatter.

* If you don't want users to copy your entire site or specific page text, you can set `disableCopy` in plugin options or `copy.disableCopy` in page frontmatter. The latter has higher priority.
* If you don't want users to select your entire site or specific page text, you can set `disableSelection` in plugin options or `copy.disableSelection` in page frontmatter. The latter has higher priority.

## Options

### author

* Type: `string`
* Details: Default author information

### license

* Type: `string`
* Details: Default license information

### authorGetter

* Type: `(page: Page) => string | null`
* Details: Author getter

### licenseGetter

* Type: `(page: Page) => string | null`
* Details: License getter

### copyrightGetter

* Type: `(page: Page) => string | null`
* Details: Copyright getter

### canonical

* Type: `string`
* Details: Canonical deploy location

  ::: tip Example

  If you are deploying same content under `https://myblog.com` and `https://blog.com/username/`, you may want to prefer one site as reference link.

  * If you prefer the first one, you should set `canonical` to `https://myblog.com`
  * If you prefer the second one, you should set `canonical` to `https://blog.com/username/`

  So copyright message triggered on another site also points to your preferred site.

  :::

### global

* Type: `boolean`
* Default: `false`
* Details: Whether enable globally

### disableCopy

* Type: `boolean`
* Default: `false`
* Details: Disable copy

### disableSelection

* Type: `boolean`
* Default: `false`
* Details: Disable selection

### triggerLength

* Type: `number`
* Default: `100`
* Details: Min content length triggering copyright append

### maxLength

* Type: `number`
* Default: `0`
* Details: Max content length which allows to copy, `0` means no limit

### locales

* Type: `CopyrightPluginLocaleConfig`

  ```ts
  interface CopyrightPluginLocaleData {
    /**
     * Author text
     *
     * @description `:author` will be replaced by author
     */
    author: string

    /**
     * License text
     *
     * @description `:license` will be replaced by current license
     */
    license: string

    /**
     * Link text
     *
     * @description `:link` will be replaced by current page link
     */
    link: string
  }

  interface CopyrightPluginLocaleConfig {
    [localePath: string]: Partial<CopyrightPluginLocaleData>
  }
  ```

* Details: Locale config for copyright plugin.

* Example:

  ```ts title=".vuepress/config.ts"
  import { copyrightPlugin } from '@vuepress/plugin-copyright'

  export default {
    locales: {
      '/': {
        // this is a supported language
        lang: 'en-US',
      },
      '/xx/': {
        // the plugin does not support this language
        lang: 'mm-NN',
      },
    },

    plugins: [
      copyrightPlugin({
        locales: {
          '/': {
            // Override link text
            link: 'Original posted at :link',
          },

          '/xx/': {
            // Complete locale config for `mm-NN` language here
          },
        },
      }),
    ],
  }
  ```

::: details Built-in Supported Languages

* **Simplified Chinese** (zh-CN)
* **Traditional Chinese** (zh-TW)
* **English (United States)** (en-US)
* **German** (de-DE)
* **Russian** (ru-RU)
* **Ukrainian** (uk-UA)
* **Vietnamese** (vi-VN)
* **Portuguese** (pt)
* **Polish** (pl-PL)
* **French** (fr-FR)
* **Spanish** (es-ES)
* **Slovak** (sk-SK)
* **Japanese** (ja-JP)
* **Turkish** (tr-TR)
* **Korean** (ko-KR)
* **Finnish** (fi-FI)
* **Hungarian** (hu-HU)
* **Indonesian** (id-ID)
* **Dutch** (nl-NL)

:::

## Frontmatter

### copy.triggerLength

* Type: `number`
* Default: `100`
* Details: Min content length triggering copyright append

### copy.maxLength

* Type: `number`
* Default: `0`
* Details: Max content length which allows to copy, `0` means no limit

### copy.disableCopy

* Type: `boolean`
* Default: `false`
* Details: Disable copy

### copy.disableSelection

* Type: `boolean`
* Default: `false`
* Details: Disable selection

---

---
url: /plugins/features/icon.md
---
# icon

Provides icon component.

## Usage

```bash
npm i -D @vuepress/plugin-icon@next
```

```ts title=".vuepress/config.ts"
import { iconPlugin } from '@vuepress/plugin-icon'

export default {
  plugins: [
    iconPlugin({
      // options
    }),
  ],
}
```

We support multiple types of icons:

* `iconify` (default)
* `fontawesome`
* `iconfont`

Also, you can use images links with any icon types (relative links are NOT supported).

If you want a new type of icon, please open an issue or submit a PR.

In markdown, you can use `::icon decorators... =size /color key=value complex-key="complex value"...::` to insert custom icons.

* A string starting with `=` will be treated as a size definition.
* A string starting with `/` will be treated as a color definition.
* Any string which itself is a valid html attribute will parsed, standardized and added to the icon element.
* The rest part will be treated as the icon name.

```md
::icon =16 /red:: <!-- <VPIcon icon="icon" color="red" size="16px" /> -->

::icon rotate vertical-align=middle:: <!-- <VPIcon icon="icon rotate" vertical-align="middle" /> -->
```

::: preview

::mdi:home /blue::
::mdi:apple =2rem vertical-align=text-bottom::

:::

## Icon Types

### Iconify

For full icon list, see <https://icon-sets.iconify.design/>. To use a icon, copy it's icon name of `iconify-icon` in the selector.

Additionally, iconify support the following props:

* `mode`: `svg` (default) `style` `bg` or `mask` to change the render icon mode
* `inline`: `false` to disable inline icon
* `flip`: `horizontal` or `vertical` to flip the icon
* `rotate`: `90`, `180`, `270` to rotate the icon

If you use 1 icon set mostly, you can set the prefix to the icon set name (E.g.: `mdi:`), Then you can use the icon name without the prefix. Manually declaring a full icon name will override the prefix:

```md
::home:: <!-- mdi:home -->
::svg-spinners:180-ring:: <!-- svg-spinners:180-ring -->
```

### Font Awesome

For free icon list, see <https://fontawesome.com/v6/search?o=r&m=free>. To use a icon, copy it's icon name in the selector.

The `fontawesome` keyword only includes the free solid and regular icons. If you want to use the brand icons, you need to use the `fontawesome-with-brands` keyword.

Solid icons can be used directly. if you want to use regular or brand icons, you need to add the `regular:` or `brands:` prefix to the icon name:

```md
::home:: <!-- fas fa-home (solid is default) -->
::solid:home:: <!-- fas fa-home -->
::regular:heart:: <!-- far fa-heart -->
::brands:apple:: <!-- fab fa-apple -->
```

Besides, a three letter prefix, first letter or full class name are also supported:

```md
::s:home:: <!-- fas fa-home -->
::fas:home:: <!-- fas fa-home -->
::fa-solid:home:: <!-- fa-solid fa-home -->

::b:apple:: <!-- fab fa-apple -->
::fab:apple:: <!-- fab fa-apple -->
::fa-brands:apple:: <!-- fa-brands fa-apple -->

::r:heart:: <!-- far fa-heart -->
::far:heart:: <!-- far fa-heart -->
::fa-regular:heart:: <!-- fa-regular fa-heart -->
```

You can add other classes that fontawesome supports after the icon name and split them with a space, where `fa-` prefix is optional:

```md
<!-- a small size icon -->

::home fa-sm:: <!-- fas fa-home fa-sm -->

<!-- rotate 180deg -->

::home rotate-180:: <!-- fas fa-home fa-rotate-180 -->
```

See <https://docs.fontawesome.com/web/style/styling> for all available classes.

::: tip FontAwesome Kits and Pro features

By default, we use jsdelivr CDN to load V6 version of FontAwesome free icons. This should be enough for most open source projects.

Besides, you can purchase at [fontawesome.com](https://fontawesome.com) to use kits.

FontAwesome kits with pro features support pro icons, more icon styles and uploading your own icons.

For details, please follow [FontAwesome document](https://docs.fontawesome.com/).

* [Full Icon List](https://fontawesome.com/search)

:::

### Iconfont

[Iconfont](https://iconfont.cn) is a vector icon management and communication platform created by Alimama MUX.

Every designer can upload icons to Iconfont platform, and users are allow to create projects from these icons. The project can be used in a variety of formats.

### Generating Your Own Iconfont Links

#### Create a project

First, you need to create a new project to set and manage your website's icons:

1. Log in to Iconfont.
2. Find "Resources → My Projects" at the top of the website, and click the "New Project" icon in the upper right corner.
3. Set a recognizable project name
4. Fill in `FontClass/Symbol prefix` with `icon-`. You can also fill in according to your preference, but you need to manually set this value to `prefix` option with an extra `"iconfont"` class in the front, e.g.: `iconfont icon-`

![New Project](./assets/iconfont-new.png)

#### Import Icon

Search and find the icon you want to use, and click the "Add to Library" button on the icon

![Add to library](./assets/iconfont-add.png)

When you complete searching, click the "Add to Library" icon in the upper right corner, click "Add to Project" below, select the project you created then confirm.

#### Edit Icon

On the project page, you can edit the icons in the project, including adjustments with position, size, rotate, color, Unicode number and Font Class / Symbol.

![Edit icon](./assets/iconfont-edit.png)

#### Generate Links

Click the "Font Class" button above the project and click Generate.

![Generate link](./assets/iconfont-generate.png)

Then set `assets` option with the generated link.

::: tip

You need to regenerate and update the link every time you add a new icon.

:::

### Images

Images links are supported with any icon types (relative links are NOT supported).

```md
<!-- A full link -->

::https://example.com/icon.png::

<!-- icon.png should be placed in .vuepress/public folder -->

<VPIcon icon="/icon.png" /> <!-- ::/icon.png:: is NOT supported as it will be parsed as color -->
```

## Options

### assets

* Type: `IconAsset`

  ```ts
  export type BuiltInIcon =
    | 'fontawesome-with-brands'
    | 'fontawesome'
    | 'iconify'

  export type IconLink =
    | `//${string}`
    | `/${string}`
    | `http://${string}`
    | `https://${string}`

  export type IconAsset = (BuiltInIcon | IconLink)[] | BuiltInIcon | IconLink
  ```

* Default: `"iconify"`

* Details:

  Icon assets to be used.

  The following keywords are supported and you may use other CDN links or even your own:

  * `iconify`: Iconify
  * `fontawesome`: Font Awesome free icons only
  * `fontawesome-with-brands`: Font Awesome free icons and brand icons

### type

* Type: `IconType`

  ```ts
  export type IconType = 'fontawesome' | 'iconfont' | 'iconify' | 'unknown'
  ```

* Default: Inferred from `assets`

* Details:

  Type of the icon, the plugin will try to infer the type from the assets, and fallbacks to `unknown`.

  Notably, the plugin can recognize:

  * iconfont css links
  * fontawesome kits
  * CDN links for fontawesome and iconify

### prefix

* Type: `string`

* Default: Inferred from `assets` and `type`

* Details:

  Prefix for the icon component. By default, the plugin will use:

  * `iconfont icon-` for iconfont type
  * empty string for all other types

### component

* Type: `string`
* Default: `"VPIcon"`
* Details: Name of the icon component

### markdown

* Type: `boolean`
* Default: `true`
* Details: Whether to enable icon syntax (`::icon::`) in markdown

## Component Props

### icon {#icon-prop}

* Type: `string`
* Required: Yes
* Details: Icon name

### color

* Type: `string`
* Default: `"inherit"`
* Details: Color used for icon.

### size

* Type: `number | string`
* Default: Current font size
* Details: Icon size.

### verticalAlign

* Type: `string`
* Default: `"-0.125em"`
* Details: Vertical alignment of the icon.

### sizing

* Type: `"width" | "height" | "both"`
* Default: `"height"`
* Details: Icon size adjustment method.
  * `width`: Set width only
  * `height`: Set height only
  * `both`: Set width and height

---

---
url: /plugins/features/medium-zoom.md
---
# medium-zoom

Integrate [medium-zoom](https://github.com/francoischalifour/medium-zoom#readme) into VuePress, which can provide the ability to zoom images.

This plugin has been integrated into the default theme.

## Usage

```bash
npm i -D @vuepress/plugin-medium-zoom@next
```

```ts title=".vuepress/config.ts"
import { mediumZoomPlugin } from '@vuepress/plugin-medium-zoom'

export default {
  plugins: [
    mediumZoomPlugin({
      // options
    }),
  ],
}
```

## Options

### selector

* Type: `string`
* Default: `'[vp-content] > img, [vp-content] :not(a) > img'`
* Details:

  Selector of zoomable images.

  By default this plugin will make all images zoomable except those inside `<a>` tags.

### zoomOptions

* Type: `Object`

* Details:

  Options for medium-zoom.

* Reference:
  * [medium-zoom > Options](https://github.com/francoischalifour/medium-zoom#options)

## Styles

You can customize most of the zoom styles via [zoomOptions](#zoomoptions), while this plugin also provides some CSS variables for additional customization:

@[code css](@vuepress/plugin-medium-zoom/src/client/styles/vars.css)

## Composition API

### useMediumZoom

* Details:

  Returns the `Zoom` instance that is used by this plugin, so that you can use the instance [methods](https://github.com/francoischalifour/medium-zoom#methods) directly.

  This plugin will make images zoomable after navigating to current page. But if you are going to add new images dynamically, you may need this method to make those new images zoomable, too.

  This plugin adds an extra `refresh` method on the `Zoom` instance, which will call `zoom.detach()` then `zoom.attach()` with the [selector](#selector) as the default parameter. It will help you refresh the zoomable images for current page.

* Example:

```ts
import { useMediumZoom } from '@vuepress/plugin-medium-zoom/client'
import { nextTick } from 'vue'

export default {
  setup(): void {
    const zoom = useMediumZoom()

    // ... do something to add new images in current page

    // then you may need to call `refresh` manually to make those new images zoomable
    nextTick(() => {
      zoom.refresh()
    })
  },
}
```

---

---
url: /plugins/features/notice.md
---
# notice

Add notice popups to your site with this plugin.

## Usage

```bash
npm i -D @vuepress/plugin-notice@next
```

```ts title=".vuepress/config.ts"
import { noticePlugin } from '@vuepress/plugin-notice'

export default {
  plugins: [
    noticePlugin({
      // options
    }),
  ],
}
```

You can set multiple notices for different paths on your site.

Each notice configuration requires either a `path` or `match` option to determine which pages it should appear on. The `path` option is a string that matches all paths starting with it, while the `match` option is a regular expression to test against the page route path.

A notice configuration includes:

* `title`: Notice title, supports both text and HTML strings

* `content`: Notice content, supports text, HTML strings, and Markdown
  * When using Markdown as content, set `contentType` to `markdown`.

  * You can also use `contentFile` to specify the absolute path of a file (`.md` or `.html` format) to read the notice content from.

* `actions`: Notice actions

  An array of objects containing:

  * `text`: Action text

  * `link`: Action link (optional).

    Pathnames are treated as internal route links and handled by the router, while full URLs are treated as external links and opened in a new window.

  * `type`: `"default"` or `"primary"` (optional)

    Default value is `"default"`.

Here is an example:

```ts title=".vuepress/config.ts"
import { noticePlugin } from '@vuepress/plugin-notice'
import { path } from 'vuepress/utils'

export default {
  plugins: [
    noticePlugin({
      config: [
        {
          path: '/',
          title: 'Notice Title',
          content: 'Notice Content',
          actions: [
            {
              text: 'Primary Action',
              link: 'https://theme-hope.vuejs.press/',
              type: 'primary',
            },
            { text: 'Default Action' },
          ],
        },
        {
          path: '/zh/',
          title: 'Notice Title',
          contentType: 'markdown',
          content: '**Notice Content** [link](https://example.com)',
          actions: [
            {
              text: 'Primary Action',
              link: 'https://theme-hope.vuejs.press/',
              type: 'primary',
            },
            { text: 'Default Action' },
          ],
        },
        {
          path: '/example/',
          title: 'Notice Title',
          contentFile: path.resolve(__dirname, 'notice.md'),
          actions: [
            {
              text: 'Primary Action',
              link: 'https://theme-hope.vuejs.press/',
              type: 'primary',
            },
            { text: 'Default Action' },
          ],
        },
      ],
    }),
  ],
}
```

We also provide advanced options to control notice display behavior.

::: tip Display Control

By default, notices are shown whenever users enter the site, and remain closed for the session if users close them.

To prevent notices from appearing again after users close them (even in future visits), set `showOnce: true` in the notice options.

Notice state is remembered based on the notice title and content. You can set a custom `key` option to use your own identifier, allowing you to edit notice content without bothering users who have already acknowledged them.

:::

::: tip Fullscreen Mode

To display a fullscreen popup, use `fullscreen: true` in the notice options. We recommend combining this with `confirm: true`.

The notice will be displayed in the center of the screen, with other areas covered by a blur mask.

:::

::: tip Close Button

By default, there is a close button on the right side of the notice, allowing users to dismiss it. Users can also close fullscreen notices by clicking the mask.

However, if you want users to acknowledge the notice, set `confirm: true` so users can only close the notice by clicking action buttons.

:::

## Options

### config

* Type: `NoticeOptions[]`

  ```ts
  interface NoticeItemOptions {
    /**
     * Notice title
     */
    title: string

    /**
     * Notice content
     */
    content?: string

    /**
     * Notice content type
     * @default 'html'
     */
    contentType?: 'html' | 'markdown'

    /**
     * Notice content file absolute path, file format should be `.md` or `.html`.
     * Prioritize using the file content as `content`.
     * @example '/path/to/notice.md'
     */
    contentFile?: string

    /**
     * Notice key
     *
     * @description Used to identify and store the notice status
     */
    key?: string

    /**
     * Whether show notice only once or show it in every visit
     *
     * @default false
     */
    showOnce?: boolean

    /**
     * Whether the notice shall be confirmed
     *
     * @default false
     */
    confirm?: boolean

    /**
     * Whether the notice should appear fullscreen
     *
     * @default false
     */
    fullscreen?: boolean

    /**
     * Notice actions
     */
    actions?: NoticeActionOption[]
  }

  interface NoticePathOptions extends NoticeItemOptions {
    /**
     * Path prefix to match
     */
    path: string
  }

  interface NoticeMatchOptions extends NoticeItemOptions {
    /**
     * A regexp matching notice path
     */
    match: RegExp
  }

  type NoticeOptions = NoticeMatchOptions | NoticePathOptions
  ```

* Details:

  Notice configuration.

---

---
url: /plugins/features/nprogress.md
---
# nprogress {#nprogress-plugin}

Integrate [nprogress](https://github.com/rstacruz/nprogress) into VuePress, which provides a progress bar when navigating to another page.

This plugin has been integrated into the default theme.

## Usage

```bash
npm i -D @vuepress/plugin-nprogress@next
```

```ts title=".vuepress/config.ts"
import { nprogressPlugin } from '@vuepress/plugin-nprogress'

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

## Styles

You can customize the style of the progress bar via CSS variables:

@[code css](@vuepress/plugin-nprogress/src/client/styles/vars.css)

---

---
url: /plugins/features/photo-swipe.md
---
# photo-swipe

This plugin provides image gallery functionality with PhotoSwipe, allowing users to view images in an elegant fullscreen lightbox with zoom, navigation, and sharing capabilities.

## Usage

```bash
npm i -D @vuepress/plugin-photo-swipe@next
```

```ts title=".vuepress/config.ts"
import { photoSwipePlugin } from '@vuepress/plugin-photo-swipe'

export default {
  plugins: [
    photoSwipePlugin({
      // options
    }),
  ],
}
```

In preview mode, you can:

* Swipe left and right to preview other pictures on the page in order
* View the description of the picture
* Zoom in and out of the picture
* View pictures in fullscreen
* Download pictures
* Share pictures

::: tip

* Besides clicking "×" in the upper right corner to exit preview mode, scrolling up and down more than a certain distance will also exit preview mode.
* On mobile devices or when using a PC trackpad, you can use pan and zoom gestures in preview mode.

:::

## Options

### selector

* Type: `string | string[]`
* Default: `"[vp-content] :not(a) > img:not([no-view])"`
* Details: Image selector

### download

* Type: `boolean`
* Default: `true`
* Details: Whether to show the download button

### fullscreen

* Type: `boolean`
* Default: `true`
* Details: Whether to show the fullscreen button

### scrollToClose

* Type: `boolean`
* Default: `true`
* Details: Whether to close the current image when scrolling

### locales

* Type: `PhotoSwipePluginLocaleConfig`

  ```ts
  interface PhotoSwipePluginLocaleData {
    /**
     * Close button label text
     */
    close: string

    /**
     * Download button label text
     */
    download: string

    /**
     * Full screen button label text
     */
    fullscreen: string

    /**
     * Zoom button label text
     */
    zoom: string

    /**
     * Previous image button label text
     */
    arrowPrev: string

    /**
     * Next image button label text
     */
    arrowNext: string
  }

  interface PhotoSwipePluginLocaleConfig {
    [localePath: string]: Partial<PhotoSwipePluginLocaleData>
  }
  ```

* Details: Locales config for photo-swipe plugin

* Example:

  ```ts title=".vuepress/config.ts"
  import { photoSwipePlugin } from '@vuepress/plugin-photo-swipe'
  import { defineUserConfig } from 'vuepress'

  export default defineUserConfig({
    locales: {
      '/': {
        // this is a supported language
        lang: 'en-US',
      },
      '/xx/': {
        // the plugin does not support this language
        lang: 'mm-NN',
      },
    },

    plugins: [
      photoSwipePlugin({
        locales: {
          '/': {
            // Override close label text
            close: 'Close Image',
          },

          '/xx/': {
            // Complete locale config for `mm-NN` language here
          },
        },
      }),
    ],
  })
  ```

::: details Built-in Supported Languages

* **Simplified Chinese** (zh-CN)
* **Traditional Chinese** (zh-TW)
* **English (United States)** (en-US)
* **German** (de-DE)
* **Russian** (ru-RU)
* **Ukrainian** (uk-UA)
* **Vietnamese** (vi-VN)
* **Portuguese** (pt)
* **Polish** (pl-PL)
* **French** (fr-FR)
* **Spanish** (es-ES)
* **Slovak** (sk-SK)
* **Japanese** (ja-JP)
* **Turkish** (tr-TR)
* **Korean** (ko-KR)
* **Finnish** (fi-FI)
* **Indonesian** (id-ID)
* **Dutch** (nl-NL)

:::

## Frontmatter

### photoSwipe

* Type: `string | false`
* Details: Image selector for the current page, or `false` to disable photo-swipe on the current page

## Client Config

### definePhotoSwipeConfig

Options passed to [`photo-swipe`](http://photoswipe.com/)

```ts title=".vuepress/client.ts"
import { definePhotoSwipeConfig } from '@vuepress/plugin-photo-swipe/client'

definePhotoSwipeConfig({
  // set photoswipe options here
})
```

## API

You can also call PhotoSwipe with APIs.

`createPhotoSwipe` allows you to programmatically view image links with PhotoSwipe:

```vue
<script setup lang="ts">
import { createPhotoSwipe } from '@vuepress/plugin-photo-swipe/client'
import { onMounted, onUnmounted } from 'vue'

let state: PhotoSwipeState | null = null

const openPhotoSwipe = (index: number): void => {
  state?.open(index - 1)
}

onMounted(async () => {
  // Create a new PhotoSwipe instance with image links
  state = await createPhotoSwipe(
    [
      'https://example.com/image1.png',
      'https://example.com/image2.png',
      'https://example.com/image3.png',
    ],
    {
      // PhotoSwipe options
    },
  )
})

onUnmounted(() => {
  state?.destroy()
})
</script>

<template>
  <button v-for="i in 3" :key="i" type="button" @click="openPhotoSwipe(i)">
    Open photo {{ i }}
  </button>
</template>
```

## Styles

You can customize the style via CSS variables:

@[code css](@vuepress/plugin-photo-swipe/src/client/styles/vars.css)

---

---
url: /plugins/features/watermark.md
---
# watermark

Integrate [watermark-js-plus](https://github.com/zhensherlock/watermark-js-plus) into VuePress.

This plugin can add watermarks to pages. You can choose to add watermarks globally or on specific pages. You can also choose to add text watermarks or image watermarks.

## Usage

```sh
npm i -D @vuepress/plugin-watermark@next
```

```ts title=".vuepress/config.ts"
import { watermarkPlugin } from '@vuepress/plugin-watermark'

export default {
  plugins: [
    watermarkPlugin({
      enabled: true,
      watermarkOptions: {
        content: 'My Site',
      },
    }),
  ],
}
```

## Options

### enabled

* Type: `boolean | ((page: Page) => boolean)`

* Default: `true`

* Details:

  Specify which pages should have watermarks added.

  Pages with a `true` value will have watermarks added.

### watermarkOptions

* Type: `WatermarkOptions`

* Default: `undefined`

* Details: Configuration options. Please refer to [watermark-js-plus](https://zhensherlock.github.io/watermark-js-plus/config/) for details.

#### watermarkOptions.parent

* Type: `string`

* Default: `'body'`

* Details: Parent element selector for watermark insertion.

  By default, watermarks are inserted into the body element, but you can specify a different parent element on the page.

## Frontmatter

### watermark

* Type: `boolean | WatermarkOptions`

* Details:

  When the type is `boolean`, it indicates whether watermarks are enabled.

  When the type is `WatermarkOptions`, it represents the watermark configuration for the current page.

  Refer to [watermark-js-plus](https://zhensherlock.github.io/watermark-js-plus/config/) for configuration options.

```md
---
watermark:
  width: 200
  height: 200
  content: Your content
  opacity: 0.5
---
```

## Client Config

### defineWatermarkConfig(config)

* Type: `(config: MaybeRefOrGetter<WatermarkOptions>) => void`

Additional configuration to pass to [watermark-js-plus](https://zhensherlock.github.io/watermark-js-plus/config/).

```ts title=".vuepress/client.ts"
import { defineWatermarkConfig } from '@vuepress/plugin-watermark/client'

defineWatermarkConfig({
  // Set up additional watermark configurations here
})
```

In most cases, options should be defined in the Node.js configuration,
but there are special situations where client-side configuration is needed. For example,
you may need to control different watermark opacities or font colors
in **dark/light mode**, or pass callbacks such as `onSuccess` and `extraDrawFunc`.

```ts title=".vuepress/client.ts"
import { useDarkMode } from '@vuepress/helper/client'
import { defineWatermarkConfig } from '@vuepress/plugin-watermark/client'
import { computed } from 'vue'
import { defineClientConfig } from 'vuepress/client'

export default defineClientConfig({
  setup() {
    const isDark = useDarkMode()

    const watermarkConfig = computed(() => ({
      fontColor: isDark.value ? '#fff' : '#000',
      onSuccess: () => {
        console.log('success')
      },
    }))

    defineWatermarkConfig(watermarkConfig)
  },
})
```

---

---
url: /plugins/markdown/index.md
---
# Markdown Plugins

---

---
url: /plugins/markdown/append-date.md
---
# append-date

This plugin will append writing date to frontmatter based on [@vuepress/plugin-git](../development/git.md).

## Usage

```bash
npm i -D @vuepress/plugin-append-date@next
```

```ts title=".vuepress/config.ts"
import { appendDatePlugin } from '@vuepress/plugin-append-date'

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

## Options

### key

* Type: `string`
* Default: `"date"`
* Details: Frontmatter key to use when appending date

### format

* Type: `"date" | "time" | "full"`
* Default: `"date"`
* Details:

  Format of the date value when appending date:

  * `"date"`: YYYY-MM-DD format
  * `"time"`: HH:MM:SS format
  * `"full"`: YYYY-MM-DD HH:MM:SS format

---

---
url: /plugins/markdown/links-check.md
---
# links-check

This plugin checks for dead links in your markdown files.

This plugin has been integrated into the default theme.

## Usage

```bash
npm i -D @vuepress/plugin-links-check@next
```

```ts title=".vuepress/config.ts"
import { linksCheckPlugin } from '@vuepress/plugin-links-check'

export default {
  plugins: [
    linksCheckPlugin({
      // options
    }),
  ],
}
```

## Options

### dev

* Type: `boolean`

* Default: `true`

* Details:

  Whether to check dead links in markdown in dev server.

### build

* Type: `boolean | 'error'`

* Default: `true`

* Details:

  Whether to check dead links in markdown during build. If set to `'error'`, the build will fail when dead links are found.

### exclude

* Type: `(string | RegExp)[] | ((link: string, isDev: boolean) => boolean)`

* Details:

  Links to exclude from checking. You can use a list of strings or regular expressions, or a function that returns a boolean.

* Example:

  ```ts title=".vuepress/config.ts"
  import { linksCheckPlugin } from '@vuepress/plugin-links-check'

  export default {
    plugins: [
      linksCheckPlugin({
        exclude: [
          // exclude links by string
          '/exclude-link',
          // exclude links by regex
          /\/exclude-link-regex/,
        ],

        // or exclude links by function
        exclude: (link, isDev) => {
          if (isDev) {
            return link.startsWith('/exclude-link-dev')
          }
          return link.startsWith('/exclude-link-build')
        },
      }),
    ],
  }
  ```

---

---
url: /plugins/markdown/markdown-chart/index.md
---
# markdown-chart

Add powerful charts to your VuePress site.

This plugin provides 6 different chart libraries to help you insert charts into your Markdown files:

* **Chart.js**: A lightweight, easy-to-use, highly customizable chart library.

  Chart.js is lighter compared to ECharts.

* **ECharts**: A powerful, interactive charting and visualization library for browsers.

  ECharts is more powerful compared to Chart.js.

* **Flowchart**: A simple Markdown extension to generate flowcharts and sequence diagrams.

  Lightweight, focusing only on flowcharts.

* **Markmap**: Create mind maps from Markdown.

  The runtime is heavy, not recommended for production.

* **Mermaid**: Generate diagrams and flowcharts from text in a similar manner as Markdown.

  Powerful collection of common charts.

* **PlantUML**: UML diagrams powered by Java.

  No client-side runtime, extremely lightweight.

## Installation

::: code-tabs#shell

@tab pnpm

```bash
pnpm add -D @vuepress/plugin-markdown-chart@next
```

@tab yarn

```bash
yarn add -D @vuepress/plugin-markdown-chart@next
```

@tab npm

```bash
npm i -D @vuepress/plugin-markdown-chart@next
```

:::

## Usage

```ts
import { markdownChartPlugin } from '@vuepress/plugin-markdown-chart'

export default {
  plugins: [
    markdownChartPlugin({
      // Enable Chart.js
      chartjs: true,
      // Enable ECharts
      echarts: true,
      // Enable Flowchart.js
      flowchart: true,
      // Enable Markmap
      markmap: true,
      // Enable Mermaid
      mermaid: true,
      // Enable PlantUML
      plantuml: true,
    }),
  ],
}
```

## Available Charts

* [Chart.js](./chartjs.md)
* [ECharts](./echarts.md)
* [Flowchart](./flowchart.md)
* [Markmap](./markmap.md)
* [Mermaid](./mermaid.md)
* [PlantUML](./plantuml.md)

## Options

### chartjs

* Type: `boolean`
* Details: Whether to enable Chart.js support.

### echarts

* Type: `boolean`
* Details: Whether to enable ECharts support.

### flowchart

* Type: `boolean`
* Details: Whether to enable Flowchart support.

### markmap

* Type: `boolean`
* Details: Whether to enable Markmap support.

### mermaid

* Type: `boolean`
* Details: Whether to enable Mermaid support.

### plantuml

* Type: `boolean | MarkdownItPlantumlOptions[]`
* Details: Whether to enable PlantUML support. Can accept configuration options for advanced usage.

### DANGEROUS\_ALLOW\_SCRIPT\_EXECUTION

* Type: `boolean`
* Details: Whether to allow script execution in charts.

### DANGEROUS\_SCRIPT\_EXECUTION\_ALLOWLIST

* Type: `string[] | '*'`
* Default: `[]`
* Details: Only effective when `DANGEROUS_ALLOW_SCRIPT_EXECUTION` is enabled. A list of file paths allowed to execute chart scripts. Use `'*'` to allow all files.

---

---
url: /plugins/markdown/markdown-chart/chartjs.md
---
# Chart.js

Add [Chart.js][] support to the Markdown files in your VuePress site.

[chart.js]: https://www.chartjs.org/docs/latest/

## Installation

Install [Chart.js][] in your project:

::: code-tabs#shell

@tab pnpm

```bash
pnpm add -D chart.js
```

@tab yarn

```bash
yarn add -D chart.js
```

@tab npm

```bash
npm i -D chart.js
```

:::

Then enable it via:

```ts {7} title=".vuepress/config.ts"
import { markdownChartPlugin } from '@vuepress/plugin-markdown-chart'

export default {
  plugins: [
    markdownChartPlugin({
      // Enable Chart.js
      chartjs: true,
    }),
  ],
}
```

## Syntax

````md
::: chartjs Chart Title

```json
{
  // Your chart configuration here
}
```

:::
````

You should use `json` code block to provide your Chart.js configuration whenever possible, however for dynamic data generation, you can also use script blocks. Both `js` and `javascript` code blocks are also supported. You should assign your export object to `module.exports`.

::: warning

For security reasons, you need to manually allow script blocks in certain files. Set `DANGEROUS_ALLOW_SCRIPT_EXECUTION: true` and `DANGEROUS_SCRIPT_EXECUTION_ALLOWLIST: ['your/file/path.md']` in plugin options.

:::

## Demo

:::: preview Bar Chart

::: chartjs A bar chart

```json
{
  "type": "bar",
  "data": {
    "labels": ["Red", "Blue", "Yellow", "Green", "Purple", "Orange"],
    "datasets": [
      {
        "label": "# of Votes",
        "data": [12, 19, 3, 5, 2, 3],
        "backgroundColor": [
          "rgba(255, 99, 132, 0.2)",
          "rgba(54, 162, 235, 0.2)",
          "rgba(255, 206, 86, 0.2)",
          "rgba(75, 192, 192, 0.2)",
          "rgba(153, 102, 255, 0.2)",
          "rgba(255, 159, 64, 0.2)"
        ],
        "borderColor": [
          "rgba(255, 99, 132, 1)",
          "rgba(54, 162, 235, 1)",
          "rgba(255, 206, 86, 1)",
          "rgba(75, 192, 192, 1)",
          "rgba(153, 102, 255, 1)",
          "rgba(255, 159, 64, 1)"
        ],
        "borderWidth": 1
      }
    ]
  },
  "options": {
    "scales": {
      "y": {
        "beginAtZero": true
      }
    }
  }
}
```

:::

::::

:::: preview Bubble Chart

::: chartjs A Bubble Chart

```json
{
  "type": "bubble",
  "data": {
    "datasets": [
      {
        "label": "First Dataset",
        "data": [
          { "x": 20, "y": 30, "r": 15 },
          { "x": 40, "y": 10, "r": 10 }
        ],
        "backgroundColor": "rgb(255, 99, 132)"
      }
    ]
  }
}
```

:::

::::

:::: preview Line Chart

::: chartjs A Line Chart

```json
{
  "type": "line",
  "data": {
    "labels": ["January", "February", "March", "April", "May", "June", "July"],
    "datasets": [
      {
        "label": "My First Dataset",
        "data": [65, 59, 80, 81, 56, 55, 40],
        "fill": false,
        "borderColor": "rgb(75, 192, 192)",
        "tension": 0.1
      }
    ]
  }
}
```

:::

::::

:::: preview Polar Area Chart

::: chartjs A Polar Area Chart

```json
{
  "type": "polarArea",
  "data": {
    "labels": ["Red", "Green", "Yellow", "Grey", "Blue"],
    "datasets": [
      {
        "label": "My First Dataset",
        "data": [11, 16, 7, 3, 14],
        "backgroundColor": [
          "rgb(255, 99, 132)",
          "rgb(75, 192, 192)",
          "rgb(255, 205, 86)",
          "rgb(201, 203, 207)",
          "rgb(54, 162, 235)"
        ]
      }
    ]
  }
}
```

:::

::::

:::: preview Radar Chart

::: chartjs A Radar Chart

```json
{
  "type": "radar",
  "data": {
    "labels": [
      "Eating",
      "Drinking",
      "Sleeping",
      "Designing",
      "Coding",
      "Cycling",
      "Running"
    ],
    "datasets": [
      {
        "label": "My First Dataset",
        "data": [65, 59, 90, 81, 56, 55, 40],
        "fill": true,
        "backgroundColor": "rgba(255, 99, 132, 0.2)",
        "borderColor": "rgb(255, 99, 132)",
        "pointBackgroundColor": "rgb(255, 99, 132)",
        "pointBorderColor": "#fff",
        "pointHoverBackgroundColor": "#fff",
        "pointHoverBorderColor": "rgb(255, 99, 132)"
      },
      {
        "label": "My Second Dataset",
        "data": [28, 48, 40, 19, 96, 27, 100],
        "fill": true,
        "backgroundColor": "rgba(54, 162, 235, 0.2)",
        "borderColor": "rgb(54, 162, 235)",
        "pointBackgroundColor": "rgb(54, 162, 235)",
        "pointBorderColor": "#fff",
        "pointHoverBackgroundColor": "#fff",
        "pointHoverBorderColor": "rgb(54, 162, 235)"
      }
    ]
  },
  "options": {
    "elements": {
      "line": {
        "borderWidth": 3
      }
    }
  }
}
```

:::

::::

:::: preview Scatter Chart

::: chartjs A Scatter Chart

```json
{
  "type": "scatter",
  "data": {
    "datasets": [
      {
        "label": "Scatter Dataset",
        "data": [
          { "x": -10, "y": 0 },
          { "x": 0, "y": 10 },
          { "x": 10, "y": 5 },
          { "x": 0.5, "y": 5.5 }
        ],
        "backgroundColor": "rgb(255, 99, 132)"
      }
    ]
  },
  "options": {
    "scales": {
      "x": {
        "type": "linear",
        "position": "bottom"
      }
    }
  }
}
```

:::

::::

## Docs

For details, please see [Chart.js Docs](https://www.chartjs.org/docs/latest/).

---

---
url: /plugins/markdown/markdown-chart/echarts.md
---
# ECharts

Add [ECharts][] support to the Markdown files in your VuePress site.

[echarts]: https://echarts.apache.org/en/index.html

## Installation

Install [ECharts][] in your project:

::: code-tabs#shell

@tab pnpm

```bash
pnpm add -D echarts
```

@tab yarn

```bash
yarn add -D echarts
```

@tab npm

```bash
npm i -D echarts
```

:::

Then enable it via:

```ts {7} title=".vuepress/config.ts"
import { markdownChartPlugin } from '@vuepress/plugin-markdown-chart'

export default {
  plugins: [
    markdownChartPlugin({
      // Enable ECharts
      echarts: true,
    }),
  ],
}
```

## Syntax

### With JSON

If you can generate your chart data easily, you can just provide echarts config using JSON code block:

````md
::: echarts Title

```json
{
  // Your echarts config here.
}
```

:::
````

### With Scripts

You should use `json` code block to provide your ECharts configuration whenever possible, however for dynamic data generation, you can also use script blocks.

Both `js` or `javascript` code block are supported. We will expose the echarts lib as `echarts` and the instance as `myChart` in the script, and you are expected to assign the echarts option object to `option` variable. Also, you can assign `width` and `height` variable to set the chart size.

::: warning

For security reasons, you need to manually allow script blocks in certain files. Set `DANGEROUS_ALLOW_SCRIPT_EXECUTION: true` and `DANGEROUS_SCRIPT_EXECUTION_ALLOWLIST: ['your/file/path.md']` in plugin options.

:::

````md
::: echarts Title

```js
const option = {
  // Your echarts config here.
}
```

:::
````

::: tip

You can use top-level await and `fetch` to get data from network requests.

:::

## Advanced

You can import and call `defineEChartsConfig` in [client config file][client-config] to customize echarts.

```ts title=".vuepress/client.ts"
import { defineEChartsConfig } from '@vuepress/plugin-markdown-chart/client'

defineEChartsConfig({
  options: {
    // global echarts options
  },
  setup: async () => {
    // echarts setup
    // e.g.: await import("echarts-wordcloud")
  },
})
```

## Docs

For details, please see [ECharts Docs](https://echarts.apache.org/handbook/en/get-started/).

## Demo

:::: preview Line Chart

::::

:::: preview Bar Chart

::::

:::: preview Pie Chart

::::

:::: preview Scatter Chart

::::

:::: preview Polar Chart

::::

:::: preview Candlestick Chart

::::

:::: preview Radar Chart

::::

:::: preview Heat Map

::::

:::: preview Tree Chart

::::

:::: preview Multiple Chart

::::

:::: preview WordCloud (with setup function)

::::

[client-config]: https://vuejs.press/guide/configuration.html#client-config-file

---

---
url: /plugins/markdown/markdown-chart/flowchart.md
---
# Flowchart

Add flowchart support to the Markdown files in your VuePress site.

## Installation

Install [flowchart.ts](http://flowchart.js.org/) in your project:

::: code-tabs#shell

@tab pnpm

```bash
pnpm add -D flowchart.ts
```

@tab yarn

```bash
yarn add -D flowchart.ts
```

@tab npm

```bash
npm i -D flowchart.ts
```

:::

Then enable it via:

```ts {7} title=".vuepress/config.ts"
import { markdownChartPlugin } from '@vuepress/plugin-markdown-chart'

export default {
  plugins: [
    markdownChartPlugin({
      // Enable Flowchart
      flowchart: true,
    }),
  ],
}
```

## Syntax

````md
<!-- ↓ :preset is optional -->

```flow:preset

<!-- Your flowchart code here. -->

```
````

Available presets for now:

* `vue` (default)
* `ant`
* `pie`

## Demo

::: preview Vue theme

```flow
st=>start: Start|past:>http://www.google.com[blank]
e=>end: End|future:>http://www.google.com
op1=>operation: My Operation|past
op2=>operation: Stuff|current
sub1=>subroutine: My Subroutine|invalid
cond=>condition: Yes
or No?|approved:>http://www.google.com
c2=>condition: Good idea|rejected
io=>inputoutput: catch something...|future

st->op1(right)->cond
cond(yes, right)->c2
cond(no)->sub1(left)->op1
c2(yes)->io->e
c2(no)->op2->e
```

:::

::: preview Ant theme

```flow:ant
st=>start: Start|past:>http://www.google.com[blank]
e=>end: End|future:>http://www.google.com
op1=>operation: My Operation|past
op2=>operation: Stuff|current
sub1=>subroutine: My Subroutine|invalid
cond=>condition: Yes
or No?|approved:>http://www.google.com
c2=>condition: Good idea|rejected
io=>inputoutput: catch something...|future

st->op1(right)->cond
cond(yes, right)->c2
cond(no)->sub1(left)->op1
c2(yes)->io->e
c2(no)->op2->e
```

:::

::: preview Pie theme

```flow:pie
st=>start: Start|past:>http://www.google.com[blank]
e=>end: End|future:>http://www.google.com
op1=>operation: My Operation|past
op2=>operation: Stuff|current
sub1=>subroutine: My Subroutine|invalid
cond=>condition: Yes
or No?|approved:>http://www.google.com
c2=>condition: Good idea|rejected
io=>inputoutput: catch something...|future

st->op1(right)->cond
cond(yes, right)->c2
cond(no)->sub1(left)->op1
c2(yes)->io->e
c2(no)->op2->e
```

:::

## Flowchart Intro

### Node Types

Defines the shape that the node will take.

::: preview Start & End

* `[Variable]->start: [Text]`

  Used as the first node where flows start from.
  Default text is `Start`.

* `[Variable]->end: [Text]`

  Used as the last node where a flow ends.
  Default text is `End`.

```flow
st=>start: Start
e=>end: End

st->e
```

:::

::: preview Operation

Indicates that an operation needs to happen in the flow.

* `[Variable]->operation: [Text]`

```flow
process=>operation: Operation
e=>end: End

process->e
```

:::

::: preview Input / Output

Indicates that IO happens in a flow.

* `[Variable]->inputoutput: [Text]`

```flow
process=>inputoutput: Inputoutput
e=>end: End

process->e
```

:::

::: preview Subroutine

Indicates that a subroutine happens in the flow and that there should be another flowchart that documents this subroutine.

* `[Variable]->subroutine: [Text]`

```flow
process=>subroutine: Subroutine
e=>end: End

process->e
```

:::

::: preview Condition

Allows for a conditional or logical statement to direct the flow into one of two or more paths.

* `[Variable]->condition: [Text]`

* `[Variable]([yesText])->[Position]`

* `[Variable]([noText])->[Position]`

```flow
cond=>condition: Process?
process=>operation: Process
e=>end: End

cond(yes)->process->e
cond(no)->e
```

:::

::: preview Parallel

Allows for multiple flows to happen simultaneously.

* `[Variable]->parallel: [Text]`
* `[Variable](path1, direction)->[Position]`
* `[Variable](path1, direction)->[Position]`

```flow
para=>parallel: parallel tasks
process=>operation: Process
e=>end: End

para(path1, bottom)->process->e
para(path2)->e
```

:::

## Connections

Connections are defined in their own section below the node definitions.

The `->` operator specifies a connection from one node to another like `nodeVar1->nodeVar2->nodeVar3`.

Not all nodes need to be specified in one string and can be separated like so

```md
nodeVar1->nodeVar2
nodeVar2->nodeVar3
```

Connection syntax is as follows:

`<node variable name>[(<specification1>[, <specification2])]-><node variable name>[[(<specification1>[, <specification2])]-><node variable name>]`

Items in `[]` are optional.

### Directions

The following directions are available and define the direction the connection will leave the node from. If there are more than one specifier, it is always the last. All nodes have a default direction making this an optional specification. `<direction>` will be used and one of the below list should be used in its place.

* `left`
* `right`
* `top`
* `bottom`

### Node Specific Specifiers by Type

Each node variable has optional specifiers, like direction, and some have special specifiers depending on the node type that are defined below. Specifiers are added after the variable name in `()` and separated with `,` like `nodeVar(spec1, spec2)`.

* **start**
  **operation**
  **inputoutput**
  **subroutine**

  Optional direction

  `startVar(<direction>)->nextNode`

  `operationVar(<direction>)->nextNode`

  `inputoutputVar(<direction>)->nextNode`

  `subroutineVar(<direction>)->nextNode`

* **condition**

  Required logical specification of `yes` or `no`

  Optional direction

  ```md
  conditionalVar(yes, <direction>)->nextNode1
  conditionalVar(no, <direction>)->nextNode2
  ```

* **parallel**

  Required path specification of `path1`, `path2`, or `path3`

  Optional direction

  ```md
  parallelVar(path1, <direction>)->nextNode1
  parallelVar(path2, <direction>)->nextNode2
  parallelVar(path3, <direction>)->nextNode3
  ```

### Links

An external link can be added to a node with the `:>` operator.

The `st` node is linked with `http://www.google.com` and will open a new tab because `[blank]` is at the end of the URL.

The `e` node is linked with `http://www.yahoo.com` and will cause the page to navigate to that page instead of opening a new tab.

```md
st=>start: Start:>http://www.google.com[blank]
e=>end: End:>http://www.yahoo.com
```

## Advice

Symbols that should possibly not be used in the text: `=>` and `->` and `:>` and `|` and `@>` and `:$`

To emphasize a specific path in your flowchart, you can define it like this:

```md
st@>op1({"stroke":"Red"})@>cond({"stroke":"Red","stroke-width":6,"arrow-end":"classic-wide-long"})@>c2({"stroke":"Red"})@>op2({"stroke":"Red"})@>e({"stroke":"Red"})
```

---

---
url: /plugins/markdown/markdown-chart/markmap.md
---
# Markmap

Add Markmap support to the Markdown files in your VuePress site.

## Installation

Install `markmap-lib`, `markmap-toolbar` and `markmap-view` in your project:

::: code-tabs#shell

@tab pnpm

```bash
pnpm add -D markmap-lib markmap-toolbar markmap-view
```

@tab yarn

```bash
yarn add -D markmap-lib markmap-toolbar markmap-view
```

@tab npm

```bash
npm i -D markmap-lib markmap-toolbar markmap-view
```

:::

Then enable it via:

```ts {7} title=".vuepress/config.ts"
import { markdownChartPlugin } from '@vuepress/plugin-markdown-chart'

export default {
  plugins: [
    markdownChartPlugin({
      // Enable Markmap
      markmap: true,
    }),
  ],
}
```

## Syntax

````md
```markmap
<!-- contents here -->
```
````

Configuring through frontmatter syntax is supported.

## Demo

::: preview

````markmap
---
title: markmap
markmap:
  colorFreezeLevel: 2
---

## Links

- [Website](https://markmap.js.org/)
- [GitHub](https://github.com/gera2ld/markmap)

## Related Projects

- [coc-markmap](https://github.com/gera2ld/coc-markmap) for Neovim
- [markmap-vscode](https://marketplace.visualstudio.com/items?itemName=gera2ld.markmap-vscode) for VSCode
- [eaf-markmap](https://github.com/emacs-eaf/eaf-markmap) for Emacs

## Features

Note that if blocks and lists appear at the same level, the lists will be ignored.

### Lists

- **strong** ~~del~~ _italic_ ==highlight==
- `inline code`
- [x] checkbox
- Katex: $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$ <!-- markmap: fold -->
  - [More Katex Examples](#?d=gist:af76a4c245b302206b16aec503dbe07b:katex.md)
- Now we can wrap very very very very long text based on `maxWidth` option
- Ordered list
  1. item 1
  2. item 2

### Blocks

```js
console.log('hello, JavaScript')
```

| Products | Price |
| -------- | ----- |
| Apple    | 4     |
| Banana   | 2     |

![](https://markmap.js.org/favicon.png)
````

:::

---

---
url: /plugins/markdown/markdown-chart/mermaid.md
---
# Mermaid

Let the Markdown files in your VuePress site support [Mermaid][].

[mermaid]: https://mermaid.js.org/

## Installation

Install [Mermaid][] in your project:

::: code-tabs#shell

@tab pnpm

```bash
pnpm add -D mermaid
```

@tab yarn

```bash
yarn add -D mermaid
```

@tab npm

```bash
npm i -D mermaid
```

:::

Then enable it via:

```ts {7} title=".vuepress/config.ts"
import { markdownChartPlugin } from '@vuepress/plugin-markdown-chart'

export default {
  plugins: [
    markdownChartPlugin({
      // Enable Mermaid
      mermaid: true,
    }),
  ],
}
```

## Syntax

````md
```mermaid

<!-- Your mermaid code here. -->

```
````

Besides using mermaid, you can also use the following code blocks:

* class: `classDiagram`
* c4c: `C4Context`
* er: `erDiagram`
* gantt: `gantt`
* git-graph: `gitGraph`
* journey: `journey`
* mindmap: `mindmap`
* kanban: `kanban`
* pie: `pie`
* quadrant: `quadrantChart`
* requirement: `requirementDiagram`
* sequence: `sequenceDiagram`
* state: `stateDiagram-v2`
* timeline: `timeline`
* architecture: `architecture-beta`
* block: `block-beta`
* packet: `packet-beta`
* radar: `radar-beta`
* sankey: `sankey-beta`
* treemap: `treemap-beta`
* xy: `xychart-beta`

You do not need to declare diagram type and intent your code.

If the diagram supports setting title, you can add the title directly after fence info:

````md
```sequence Chart Title
sequence diagram body
...
```
````

## Usage

Please see [mermaid](https://mermaid.js.org/).

## Advanced

You can import and call `defineMermaidConfig` in [client config file][client-config] to customize mermaid:

```ts title=".vuepress/client.ts"
import { defineMermaidConfig } from '@vuepress/plugin-markdown-chart/client'

defineMermaidConfig({
  // mermaid options here
})
```

## Demo

::: preview Flowchart

```mermaid
---
title: Flowchart
---
flowchart TB
    c1-->a2
    subgraph one
    a1-->a2
    end
    subgraph two
    b1-->b2
    end
    subgraph three
    c1-->c2
    end
    one --> two
    three --> two
    two --> c2
```

:::

::: preview Sequence Diagram

```sequence Greetings
Alice ->> Bob: Hello Bob, how are you?
Bob-->>John: How about you John?
Bob--x Alice: I am good thanks!
Bob-x John: I am good thanks!
Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.

Bob-->Alice: Checking with John...
Alice->John: Yes... John, how are you?
```

:::

::: preview Class Diagram

```class Animal Example
note "From Duck till Zebra"
Animal <|-- Duck
note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
Animal <|-- Fish
Animal <|-- Zebra
Animal : +int age
Animal : +String gender
Animal: +isMammal()
Animal: +mate()
class Duck{
  +String beakColor
  +swim()
  +quack()
}
class Fish{
  -int sizeInFeet
  -canEat()
}
class Zebra{
  +bool is_wild
  +run()
}
```

:::

::: preview State Diagram

```state Check if n is negative

state if_state <<choice>>
[*] --> IsPositive
IsPositive --> if_state
if_state --> False: if n < 0
if_state --> True : if n >= 0
```

:::

::: preview Entity Relationship Diagrams

```er Er Example
CAR ||--o{ NAMED-DRIVER : allows
CAR {
    string registrationNumber
    string make
    string model
}
PERSON ||--o{ NAMED-DRIVER : is
PERSON {
    string firstName
    string lastName
    int age
}
```

:::

::: preview User Journey Diagram

```journey
title My working day
section Go to work
  Make tea: 5: Me
  Go upstairs: 3: Me
  Do work: 1: Me, Cat
section Go home
  Go downstairs: 5: Me
  Sit down: 5: Me
```

:::

::: preview Gantt Diagrams

```gantt
dateFormat  YYYY-MM-DD
title       Adding GANTT diagram functionality to mermaid
excludes    weekends
%% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)

section A section
Completed task            :done,    des1, 2014-01-06,2014-01-08
Active task               :active,  des2, 2014-01-09, 3d
Future task               :         des3, after des2, 5d
Future task2              :         des4, after des3, 5d

section Critical tasks
Completed task in the critical line :crit, done, 2014-01-06,24h
Implement parser                    :crit, done, after des1, 2d
Create tests for parser             :crit, active, 3d
Future task in critical line        :crit, 5d
Create tests for renderer           :2d
Add to mermaid                      :1d

section Documentation
Describe gantt syntax               :active, a1, after des1, 3d
Add gantt diagram to demo page      :after a1  , 20h
Add another diagram to demo page    :doc1, after a1  , 48h

section Last section
Describe gantt syntax               :after doc1, 3d
Add gantt diagram to demo page      :20h
Add another diagram to demo page    :48h
```

:::

::: preview Pie Chart Diagrams

```pie
title What Voldemort doesn't have?
  "FRIENDS" : 2
  "FAMILY" : 3
  "NOSE" : 45
```

:::

::: preview Git Graph Diagrams

```git-graph
commit
branch hotfix
checkout hotfix
commit
branch develop
checkout develop
commit id:"ash" tag:"abc"
branch featureB
checkout featureB
commit type:HIGHLIGHT
checkout main
checkout hotfix
commit type:NORMAL
checkout develop
commit type:REVERSE
checkout featureB
commit
checkout main
merge hotfix
checkout featureB
commit
checkout develop
branch featureA
commit
checkout develop
merge hotfix
checkout featureA
commit
checkout featureB
commit
checkout develop
merge featureA
branch release
checkout release
commit
checkout main
commit
checkout release
merge main
checkout develop
merge release
```

:::

::: preview C4C Diagrams

```c4c
title System Context diagram for Internet Banking System

Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
Person(customerB, "Banking Customer B")
Person_Ext(customerC, "Banking Customer C")
System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")

Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")

Enterprise_Boundary(b1, "BankBoundary") {

  SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")

  System_Boundary(b2, "BankBoundary2") {
    System(SystemA, "Banking System A")
    System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts.")
  }

  System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
  SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")

  Boundary(b3, "BankBoundary3", "boundary") {
    SystemQueue(SystemF, "Banking System F Queue", "A system of the bank, with personal bank accounts.")
    SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
  }
}

BiRel(customerA, SystemAA, "Uses")
BiRel(SystemAA, SystemE, "Uses")
Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
Rel(SystemC, customerA, "Sends e-mails to")
```

:::

::: preview Mindmap

```mindmap
root((VuePress))
  Out of box
    Default theme
      Navbar
      Sidebar
      Dark Mode
    I18n
    Search
      Search
      DocSearch<br />by algolia
  Customize
    Theme
      (hope)
    Plugins
      (components)
      (md-enhance)
```

:::

::: preview Timeline

```timeline
title Timeline of Industrial Revolution
section 17th-20th century
    Industry 1.0 : Machinery, Water power, Steam <br>power
    Industry 2.0 : Electricity, Internal combustion engine, Mass production
    Industry 3.0 : Electronics, Computers, Automation
section 21st century
    Industry 4.0 : Internet, Robotics, Internet of Things
    Industry 5.0 : Artificial intelligence, Big data,3D printing
```

:::

::: preview Sankey

```sankey
Agricultural 'waste',Bio-conversion,124.729
Bio-conversion,Liquid,0.597
Bio-conversion,Losses,26.862
Bio-conversion,Solid,280.322
Bio-conversion,Gas,81.144
Biofuel imports,Liquid,35
Biomass imports,Solid,35
Coal imports,Coal,11.606
Coal reserves,Coal,63.965
Coal,Solid,75.571
District heating,Industry,10.639
District heating,Heating and cooling - commercial,22.505
District heating,Heating and cooling - homes,46.184
Electricity grid,Over generation / exports,104.453
Electricity grid,Heating and cooling - homes,113.726
Electricity grid,H2 conversion,27.14
Electricity grid,Industry,342.165
Electricity grid,Road transport,37.797
Electricity grid,Agriculture,4.412
Electricity grid,Heating and cooling - commercial,40.858
Electricity grid,Losses,56.691
Electricity grid,Rail transport,7.863
Electricity grid,Lighting & appliances - commercial,90.008
Electricity grid,Lighting & appliances - homes,93.494
Gas imports,Ngas,40.719
Gas reserves,Ngas,82.233
Gas,Heating and cooling - commercial,0.129
Gas,Losses,1.401
Gas,Thermal generation,151.891
Gas,Agriculture,2.096
Gas,Industry,48.58
Geothermal,Electricity grid,7.013
H2 conversion,H2,20.897
H2 conversion,Losses,6.242
H2,Road transport,20.897
Hydro,Electricity grid,6.995
Liquid,Industry,121.066
Liquid,International shipping,128.69
Liquid,Road transport,135.835
Liquid,Domestic aviation,14.458
Liquid,International aviation,206.267
Liquid,Agriculture,3.64
Liquid,National navigation,33.218
Liquid,Rail transport,4.413
Marine algae,Bio-conversion,4.375
Ngas,Gas,122.952
Nuclear,Thermal generation,839.978
Oil imports,Oil,504.287
Oil reserves,Oil,107.703
Oil,Liquid,611.99
Other waste,Solid,56.587
Other waste,Bio-conversion,77.81
Pumped heat,Heating and cooling - homes,193.026
Pumped heat,Heating and cooling - commercial,70.672
Solar PV,Electricity grid,59.901
Solar Thermal,Heating and cooling - homes,19.263
Solar,Solar Thermal,19.263
Solar,Solar PV,59.901
Solid,Agriculture,0.882
Solid,Thermal generation,400.12
Solid,Industry,46.477
Thermal generation,Electricity grid,525.531
Thermal generation,Losses,787.129
Thermal generation,District heating,79.329
Tidal,Electricity grid,9.452
UK land based bioenergy,Bio-conversion,182.01
Wave,Electricity grid,19.013
Wind,Electricity grid,289.366
```

:::

::: preview Requirement

```requirement
requirement test_req {
id: 1
text: the test text.
risk: high
verifymethod: test
}

element test_entity {
type: simulation
}

test_entity - satisfies -> test_req
```

:::

::: preview Quadrant Chart

```quadrant
title Reach and engagement of campaigns
x-axis Low Reach --> High Reach
y-axis Low Engagement --> High Engagement
quadrant-1 We should expand
quadrant-2 Need to promote
quadrant-3 Re-evaluate
quadrant-4 May be improved
Campaign A: [0.3, 0.6]
Campaign B: [0.45, 0.23]
Campaign C: [0.57, 0.69]
Campaign D: [0.78, 0.34]
Campaign E: [0.40, 0.34]
Campaign F: [0.35, 0.78]
```

:::

::: preview XY Chart

```xy
title "Sales Revenue"
x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
y-axis "Revenue (in $)" 4000 --> 11000
bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
```

:::

::: preview Block Chart

```block
columns 3
Frontend blockArrowId6<[" "]>(right) Backend
space:2 down<[" "]>(down)
Disk left<[" "]>(left) Database[("Database")]

classDef front fill:#696,stroke:#333;
classDef back fill:#969,stroke:#333;
class Frontend front
class Backend,Database back
```

:::

::: preview Packet Chart

```packet
title UDP Packet
0-15: "Source Port"
16-31: "Destination Port"
32-47: "Length"
48-63: "Checksum"
64-95: "Data (variable length)"
```

:::

::: preview Radar Chart

```radar
---
config:
  radar:
    axisScaleFactor: 0.25
    curveTension: 0.1
  theme: base
  themeVariables:
    cScale0: "#FF0000"
    cScale1: "#00FF00"
    cScale2: "#0000FF"
    radar:
      curveOpacity: 0
---

axis A, B, C, D, E
curve c1{1,2,3,4,5}
curve c2{5,4,3,2,1}
curve c3{3,3,3,3,3}
```

:::

::: preview A Complex Example

```mermaid
graph TB
    sq[Square shape] --> ci((Circle shape))

    subgraph A
        od>Odd shape]-- Two line<br/>edge comment --> ro
        di{Diamond with <br/> line break} -.-> ro(Rounded<br>square<br>shape)
        di==>ro2(Rounded square shape)
    end

    %% Notice that no text in shape are added here instead that is appended further down
    e --> od3>Really long text with line break<br>in an Odd shape]

    %% Comments after double percent signs
    e((Inner / circle<br>and some odd <br>special characters)) --> f(,.?!+-*ز)

    cyr[Cyrillic]-->cyr2((Circle shape));

     classDef green fill:#9f6,stroke:#333,stroke-width:2px;
     classDef orange fill:#f96,stroke:#333,stroke-width:4px;
     class sq,e green
     class di orange
```

:::

[client-config]: https://vuejs.press/guide/configuration.html#client-config-file

---

---
url: /plugins/markdown/markdown-chart/plantuml.md
---
# PlantUML

Add [PlantUML][] support to the Markdown files in your VuePress site.

[plantuml]: https://plantuml.com/

## Installation

You can enable this feature via:

```ts {7} title=".vuepress/config.ts"
import { markdownChartPlugin } from '@vuepress/plugin-markdown-chart'

export default {
  plugins: [
    markdownChartPlugin({
      // Enable PlantUML
      plantuml: true,
    }),
  ],
}
```

## Syntax

You can insert the same content that [plantuml][] supports, for example:

```md
@startuml
content
@enduml
```

## Demo

::: preview Sequence Diagram

@startuml
Alice -> Bob: Authentication Request

alt successful case

```
Bob -> Alice: Authentication Accepted
```

else some kind of failure

```
Bob -> Alice: Authentication Failure
group My own label
Alice -> Log : Log attack start
    loop 1000 times
        Alice -> Bob: DNS Attack
    end
Alice -> Log : Log attack end
end
```

else Another type of failure

Bob -> Alice: Please repeat

end
@enduml

:::

::: preview Use Case

@startuml
:Main Admin: as Admin
(Use the application) as (Use)

User -> (Start)
User --> (Use)

Admin ---> (Use)

note right of Admin : This is an example.

note right of (Use)
A note can also
be on several lines
end note

note "This note is connected\nto several objects." as N2
(Start) .. N2
N2 .. (Use)
@enduml

:::

::: preview Class

@startuml
abstract class AbstractList
abstract AbstractCollection
interface List
interface Collection

List <|-- AbstractList
Collection <|-- AbstractCollection

Collection <|- List
AbstractCollection <|- AbstractList
AbstractList <|-- ArrayList

class ArrayList {
Object\[] elementData
size()
}

enum TimeUnit {
DAYS
HOURS
MINUTES
}

annotation SuppressWarnings

annotation Annotation {
annotation with members
String foo()
String bar()
}
@enduml

:::

::: preview Activity

@startuml
start
:ClickServlet.handleRequest();
:new page;
if (Page.onSecurityCheck) then (true)
:Page.onInit();
if (isForward?) then (no)
:Process controls;
if (continue processing?) then (no)
stop
endif

```
if (isPost?) then (yes)
  :Page.onPost();
else (no)
  :Page.onGet();
endif
:Page.onRender();
```

endif
else (false)
endif

if (do redirect?) then (yes)
:redirect process;
else
if (do forward?) then (yes)
:Forward request;
else (no)
:Render page template;
endif
endif

stop
@enduml

:::

::: preview Component

@startuml
package "Some Group" {
HTTP - \[First Component]
\[Another Component]
}

node "Other Groups" {
FTP - \[Second Component]
\[First Component] --> FTP
}

cloud {
\[Example 1]
}

database "MySql" {
folder "This is my folder" {
\[Folder 3]
}
frame "Foo" {
\[Frame 4]
}
}

\[Another Component] --> \[Example 1]
\[Example 1] --> \[Folder 3]
\[Folder 3] --> \[Frame 4]

@enduml

:::

::: preview State

@startuml
state start1  <>
state choice1 <>
state fork1   <>
state join2   <>
state end3    <>

\[\*]     --> choice1 : from start\nto choice
start1  --> choice1 : from start stereo\nto choice

choice1 --> fork1   : from choice\nto fork
choice1 --> join2   : from choice\nto join
choice1 --> end3    : from choice\nto end stereo

fork1   ---> State1 : from fork\nto state
fork1   --> State2  : from fork\nto state

State2  --> join2   : from state\nto join
State1  --> \[\*]     : from state\nto end

join2   --> \[\*]     : from join\nto end
@enduml

:::

::: preview Object

@startuml
object London
object Washington
object Berlin
object NewYork

map CapitalCity {
UK \*-> London
USA \*--> Washington
Germany \*---> Berlin
}

NewYork --> CapitalCity::USA
@enduml

:::

::: preview Deployment

@startuml
node node1
node node2
node node3
node node4
node node5
node1 -- node2 : label1
node1 .. node3 : label2
node1 ~~ node4 : label3
node1 == node5
@enduml

:::

::: preview Timing

@startuml
scale 5 as 150 pixels

clock clk with period 1
binary "enable" as en
binary "R/W" as rw
binary "data Valid" as dv
concise "dataBus" as db
concise "address bus" as addr

@6 as :write\_beg
@10 as :write\_end

@15 as :read\_beg
@19 as :read\_end

@0
en is low
db is "0x0"
addr is "0x03f"
rw is low
dv is 0

@:write\_beg-3
en is high
@:write\_beg-2
db is "0xDEADBEEF"
@:write\_beg-1
dv is 1
@:write\_beg
rw is high

@:write\_end
rw is low
dv is low
@:write\_end+1
rw is low
db is "0x0"
addr is "0x23"

@12
dv is high
@13
db is "0xFFFF"

@20
en is low
dv is low
@21
db is "0x0"

highlight :write\_beg to :write\_end #Gold:Write
highlight :read\_beg to :read\_end #lightBlue:Read

db@:write\_beg-1 <-> @:write\_end : setup time
db@:write\_beg-1 -> addr@:write\_end+1 : hold
@enduml

:::

::: preview RegExp

@startregex
/\<style(\s*lang=(\['"])(.*?)\2)?\s\*(?:scoped)?>(\[\s\S]+)\</style>
@endregex

:::

::: preview Network

@startuml
nwdiag {
group nightly {
color = "#FFAAAA";
description = "<\&clock> Restarted nightly <\&clock>";
web02;
db01;
}
network dmz {
address = "210.x.x.x/24"

```
  user [description = "<&person*4.5>\n user1"];
  web01 [address = "210.x.x.1, 210.x.x.20",  description = "<&cog*4>\nweb01"]
  web02 [address = "210.x.x.2",  description = "<&cog*4>\nweb02"];
```

}
network internal {
address = "172.x.x.x/24";

```
  web01 [address = "172.x.x.1"];
  web02 [address = "172.x.x.2"];
  db01 [address = "172.x.x.100",  description = "<&spreadsheet*4>\n db01"];
  db02 [address = "172.x.x.101",  description = "<&spreadsheet*4>\n db02"];
  ptr  [address = "172.x.x.110",  description = "<&print*4>\n ptr01"];
```

}
}
@enduml

:::

::: preview Salt

@startsalt
{+
{/ General | Fullscreen | Behavior | Saving }
{
{ Open image in: | ^Smart Mode^ }
\[X] Smooth images when zoomed
\[X] Confirm image deletion
\[ ] Show hidden images
}
\[Close]
}
@endsalt

:::

::: preview Archimate

@startuml
skinparam rectangle<> {
roundCorner 25
}
sprite $bProcess jar:archimate/business-process
sprite $aService jar:archimate/application-service
sprite $aComponent jar:archimate/application-component

rectangle "Handle claim"  as HC <<$bProcess>><> #Business
rectangle "Capture Information"  as CI <<$bProcess>><> #Business
rectangle "Notify\nAdditional Stakeholders" as NAS <<$bProcess>><> #Business
rectangle "Validate" as V <<$bProcess>><> #Business
rectangle "Investigate" as I <<$bProcess>><> #Business
rectangle "Pay" as P <<$bProcess>><> #Business

HC \*-down- CI
HC \*-down- NAS
HC \*-down- V
HC \*-down- I
HC \*-down- P

CI -right->> NAS
NAS -right->> V
V -right->> I
I -right->> P

rectangle "Scanning" as scanning <<$aService>><> #Application
rectangle "Customer admnistration" as customerAdministration <<$aService>><> #Application
rectangle "Claims admnistration" as claimsAdministration <<$aService>><> #Application
rectangle Printing <<$aService>><> #Application
rectangle Payment <<$aService>><> #Application

scanning -up-> CI
customerAdministration  -up-> CI
claimsAdministration -up-> NAS
claimsAdministration -up-> V
claimsAdministration -up-> I
Payment -up-> P

Printing -up-> V
Printing -up-> P

rectangle "Document\nManagement\nSystem" as DMS <<$aComponent>> #Application
rectangle "General\nCRM\nSystem" as CRM <<$aComponent>>  #Application
rectangle "Home & Away\nPolicy\nAdministration" as HAPA <<$aComponent>> #Application
rectangle "Home & Away\nFinancial\nAdministration" as HFPA <<$aComponent>>  #Application

DMS .up.|> scanning
DMS .up.|> Printing
CRM .up.|> customerAdministration
HAPA .up.|> claimsAdministration
HFPA .up.|> Payment

legend left
Example from the "Archisurance case study" (OpenGroup).
See
===

# <$bProcess> :business process

# <$aService> : application service

<$aComponent> : application component
endlegend
@enduml

:::

::: preview Gantt

@startgantt

Project starts the 2020-12-01

\[Task1] requires 10 days
sunday are closed

note bottom
memo1 ...
memo2 ...
explanations1 ...
explanations2 ...
end note

\[Task2] requires 20 days
\[Task2] starts 10 days after \[Task1]'s end
\-- Separator title --
\[M1] happens on 5 days after \[Task1]'s end

\-- end --
@endgantt

:::

::: preview Mindmap

@startmindmap
caption figure 1
title My super title

* <\&flag>Debian
  \*\* <\&globe>Ubuntu
  \*\*\* Linux Mint
  \*\*\* Kubuntu
  \*\*\* Lubuntu
  \*\*\* KDE Neon
  \*\* <\&graph>LMDE
  \*\* <\&pulse>SolydXK
  \*\* <\&people>SteamOS
  \*\* <\&star>Raspbian with a very long name
  \*\*\* Raspmbc => OSMC
  \*\*\* Raspyfi => Volumio

header
My super header
endheader

center footer My super footer

legend right
Short
legend
endlegend
@endmindmap

:::

::: preview WBS

@startwbs

* New Job
  ++ Decide on Job Requirements
  +++ Identity gaps
  +++ Review JDs
  ++++ Sign-Up for courses
  ++++ Volunteer
  ++++ Reading
  ++- Checklist
  +++- Responsibilities
  +++- Location
  ++ CV Upload Done
  +++ CV Updated
  ++++ Spelling & Grammar
  ++++ Check dates
  \---- Skills
  +++ Recruitment sites chosen
  @endwbs

:::

::: preview JSON

@startjson
\#highlight "lastName"
\#highlight "address" / "city"
\#highlight "phoneNumbers" / "0" / "number"
{
"firstName": "John",
"lastName": "Smith",
"isAlive": true,
"age": 28,
"address": {
"streetAddress": "21 2nd Street",
"city": "New York",
"state": "NY",
"postalCode": "10021-3100"
},
"phoneNumbers": \[
{
"type": "home",
"number": "212 555-1234"
},
{
"type": "office",
"number": "646 555-4567"
}
],
"children": \[],
"spouse": null
}
@endjson

:::

::: preview YAML

@startyaml
doe: "a deer, a female deer"
ray: "a drop of golden sun"
pi: 3.14159
xmas: true
french-hens: 3
calling-birds:
\- huey
\- dewey
\- louie
\- fred
xmas-fifth-day:
calling-birds: four
french-hens: 3
golden-rings: 5
partridges:
count: 1
location: "a pear tree"
turtle-doves: two
@endyaml

:::

---

---
url: /plugins/markdown/markdown-container.md
---
# markdown-container

Register markdown custom containers in your VuePress site.

This plugin simplifies the use of [markdown-it-container](https://github.com/markdown-it/markdown-it-container), but also retains its original capabilities.

## Usage

```bash
npm i -D @vuepress/plugin-markdown-container@next
```

```ts title=".vuepress/config.ts"
import { markdownContainerPlugin } from '@vuepress/plugin-markdown-container'

export default {
  plugins: [
    markdownContainerPlugin({
      // options
    }),
  ],
}
```

## Container Syntax

```md
::: <type> [info]
[content]
:::
```

* The `type` is required and should be specified via [type](#type) option.
* The `info` is optional, and the default value can be specified via `defaultInfo` in [locales](#locales) option.
* The `content` can be any valid markdown content.

::: tip
This plugin can be used multiple times to support different types of containers.
:::

## Options

### type

* Type: `string`

* Required: Yes

* Details:

  The type of the container.

  It will be used as the `name` param of [markdown-it-container](https://github.com/markdown-it/markdown-it-container#api).

### locales

* Type: `Record<string, { defaultInfo: string }>`

* Default: `{}`

* Details:

  The default `info` of the container in different locales.

  If this option is not specified, the default `info` will fallback to the uppercase of the [type](#type) option.

* Example:

```ts title=".vuepress/config.ts"
export default {
  plugins: [
    markdownContainerPlugin({
      type: 'tip',
      locales: {
        '/': {
          defaultInfo: 'TIP',
        },
        '/zh/': {
          defaultInfo: '提示',
        },
      },
    }),
  ],
}
```

* Reference:
  * [Guide > I18n](https://vuejs.press/guide/i18n.html)

### before

* Type: `(info: string) => string`

* Default:

  ```ts
  ;(info: string): string =>
    `<div class="custom-container ${type}">${info ? `<p class="custom-container-title">${info}</p>` : ''}\n`
  ```

* Details:

  A function to render the starting tag of the container.

  The first param is the `info` part of [container syntax](#container-syntax).

  This option will not take effect if you don't specify the [after](#after) option.

### after

* Type: `(info: string) => string`

* Default:

  ```ts
  ;(): string => '</div>\n'
  ```

* Details:

  A function to render the ending tag of the container.

  The first param is the `info` part of [container syntax](#container-syntax).

  This option will not take effect if you don't specify the [before](#before) option.

### render

* Type:

  ```ts
  type MarkdownItContainerRenderFunction = (
    tokens: Token[],
    index: number,
    options: unknown,
    env: MarkdownEnv,
    self: Renderer,
  ) => string
  ```

* Details:

  The `render` option of [markdown-it-container](https://github.com/markdown-it/markdown-it-container#api).

  This plugin uses a default `render` function. If you specify this option, the default `render` function will be replaced, and the [locales](#locales), [before](#before) and [after](#after) options will be ignored.

### validate

* Type: `(params: string) => boolean`

* Details:

  The `validate` option of [markdown-it-container](https://github.com/markdown-it/markdown-it-container#api).

### marker

* Type: `string`

* Default: `':'`

* Details:

  The `marker` option of [markdown-it-container](https://github.com/markdown-it/markdown-it-container#api).

---

---
url: /plugins/markdown/markdown-ext.md
---
# markdown-ext

Add basic GFM support to VuePress with useful features.

## Usage

```bash
npm i -D @vuepress/plugin-markdown-ext@next
```

```ts title=".vuepress/config.ts"
import { markdownExtPlugin } from '@vuepress/plugin-markdown-ext'

export default {
  plugins: [
    markdownExtPlugin({
      // options
    }),
  ],
}
```

## Syntax

### Footnote

* Use `[^Anchor text]` in Markdown to define a footnote

* Use `[^Anchor text]: ...` to describe footnote content

* If there are multiple paragraphs in footnote, the paragraph show be double indented

::: preview

Footnote 1 link\[^first].

Footnote 2 link\[^second].

Inline footnote^\[Text of inline footnote] definition.

Duplicated footnote reference\[^second].

\[^first]: Footnote **can have markup**

```
and multiple paragraphs.
```

\[^second]: Footnote text.

:::

### Task list

* Use `- [ ] some text` to render an unchecked task item.
* Use `- [x] some text` to render a checked task item. (Capital `X` is also supported)

::: preview

* \[ ] Plan A
* \[x] Plan B

:::

### Component

You can use component fence block to add a component into your markdown content. Both YAML and JSON format props data are supported:

* YAML :

  ````md
  ```component ComponentName
  # component data here
  ```
  ````

* JSON:

  ````md
  ```component ComponentName
  {
    // component data here
  }
  ```
  ````

::: preview

```component Badge
text: Mr.Hope
type: tip
```

```component Badge
{
  "text": "Mr.Hope",
  "type": "tip"
}
```

:::

### v-pre

You can use any mustache syntax as raw text in `v-pre` container:

:::: preview

::: v-pre

{{ abc }}

:::

::::

## Options

### gfm

* Type: `boolean`

* Details:

  Whether tweaks the behavior and features to be more similar to GitHub Flavored Markdown.

  `markdown-it` already supports tables and strike through by default. If this option is `true`, the following new features will be enabled:

  * Auto link (named `linkify` in `markdown-it`)
  * Hard breaks
  * Footnote
  * Task list

  Note: Not all behavior is exactly the same as GitHub Flavored Markdown.

### footnote

* Type: `boolean`
* Details: Whether to enable footnote format support.
* Enabled in GFM: Yes

### tasklist

* Type: `MarkdownItTaskListOptions | boolean`

  ```ts
  interface MarkdownItTaskListOptions {
    /**
     * Whether disable checkbox
     *
     * @default true
     */
    disabled?: boolean

    /**
     * Whether use `<label>` to wrap text
     *
     * @default true
     */
    label?: boolean
  }
  ```

* Details:

  Whether to enable tasklist format support. You can pass an object to config tasklist.

* Enabled in GFM: Yes

### breaks

* Type: `boolean`
* Details: Whether convert `\n` in paragraphs into `<br>`s.
* Enabled in GFM: Yes

### linkify

* Type: `boolean`
* Details: Whether convert URL-like text into links.
* Enabled in GFM: Yes

### component

* Type: `boolean`
* Details: Whether to enable component fence support.

### vPre

* Type: `boolean`
* Details: Whether to enable v-pre wrapper.

---

---
url: /plugins/markdown/markdown-hint.md
---
# markdown-hint

Add gfm alerts and hint containers to your VuePress site.

This plugin has been integrated into the default theme.

## Usage

```bash
npm i -D @vuepress/plugin-markdown-hint@next
```

```ts title=".vuepress/config.ts"
import { markdownHintPlugin } from '@vuepress/plugin-markdown-hint'

export default {
  plugins: [
    markdownHintPlugin({
      // Enable hint container, true by default
      hint: true,
      // Enable gfm alert
      alert: true,
    }),
  ],
}
```

## Guide

By default, we support `important`, `info`, `note`, `tip`, `warning`, `caution`, `details` containers with markdown container:

:::: preview

::: tip

A custom tip container with `code` and [links](https://example.com).

```js
const a = 1
```

:::

::::

To customize the title of the container, you can add the title after the named container:

:::: preview

::: important Custom Title

An important container with customized title.

:::

::::

The container can contain a title only:

:::: preview

::: warning A warning text
:::

::::

The plugin also provides an `alert` option to support gfm alerts:

```md
> [!note]
> This is note text

> [!important]
> This is important text

> [!tip]
> This is tip text

> [!warning]
> This is warning text

> [!caution]
> This is caution text
```

## Options

### hint

* Type: `boolean`
* Default: `true`
* Details: Whether to enable hint containers including important, info, note, tip, warning, caution, details.

### alert

* Type: `boolean`
* Details: Whether to enable GFM alert support.

### injectStyles

* Type: `boolean`
* Default: `true`
* Details: Whether to inject default styles.

### locales

* Type: `MarkdownHintPluginLocaleConfig`

  ```ts
  interface MarkdownHintPluginLocaleConfig {
    [localePath: string]: Partial<MarkdownHintPluginLocaleData>
  }

  interface MarkdownHintPluginLocaleData {
    /**
     * Default title text for important block
     */
    important: string

    /**
     * Default title text for note block
     */
    note: string

    /**
     * Default title text for tip block
     */
    tip: string

    /**
     * Default title text for warning block
     */
    warning: string

    /**
     * Default title text for caution block
     */
    caution: string

    /**
     * Default title text for info block
     */
    info: string

    /**
     * Default title text for details block
     */
    details: string
  }
  ```

* Details: Locale config for hint container titles.

---

---
url: /plugins/markdown/markdown-image.md
---
# markdown-image

Add additional features to your markdown images.

## Usage

```bash
npm i -D @vuepress/plugin-markdown-image@next
```

```ts title=".vuepress/config.ts"
import { markdownImagePlugin } from '@vuepress/plugin-markdown-image'

export default {
  plugins: [
    markdownImagePlugin({
      // Enable figure
      figure: true,
      // Enable image lazyload
      lazyload: true,
      // Enable image mark
      mark: true,
      // Enable image size
      size: true,
    }),
  ],
}
```

## Guide

### Image Lazyload

The plugin will enable image lazyload using native HTML5 features, so it's only working on browsers which [support loading=lazy attribute](https://caniuse.com/loading-lazy-attr).

### Image Mark

When you set `mark: true` in plugin options, you can mark pictures by `#light` and `#dark` suffix to let them be displayed under certain color mode.

&#x20;(Try to toggle theme mode)

::: preview

![GitHub Light](/images/icon/github-light.svg#dark)
![GitHub Dark](/images/icon/github-dark.svg#light)

:::

#### Advanced

You can pass an object to `mark` to config ID marks, available options are:

```ts
interface ImageMarkOptions {
  /** lightmode only IDs */
  light?: string[]
  /** darkmode only IDs */
  dark?: string[]
}
```

### Image Size

When you set `size: true` in plugin options, you can append `=widthxheight` to image alt text with spaces as separator.

Both `width` and `height` should be numbers as pixels and are optional.

```md
![Alt =200x300](/example.png)
![Alt =200x](/example.jpg 'Title')
![Alt =x300](/example.bmp)
```

Renders as ↓

```html
<img src="/example.png" alt="Alt" width="200" height="300" />
<img src="/example.jpg" alt="Alt" title="Title" width="200" />
<img src="/example.bmp" alt="Alt" height="300" />
```

#### Obsidian Syntax

When you set `obsidianSize: true` in plugin options, you can append `widthxheight` after image alt text and use `|` to separate.

Both `width` and `height` should be numbers as pixels and are required. Setting one of them with `0` to scale by ratio with the other.

```md
![Alt|200x200](/example.png)
![Alt|200x0](/example.jpg)
![Alt|0x300](/example.bmp)
```

Renders as ↓

```html
<img src="/example.png" alt="Alt" width="200" height="300" />
<img src="/example.jpg" alt="Alt" width="200" />
<img src="/example.bmp" alt="Alt" height="300" />
```

::: tip Choosing between 3 Grammars

* The legacy grammar breaks image rendering in environments that don't support it (e.g.: GitHub)
* Both the new grammar and the Obsidian grammar are compatible with the Markdown standard, but new grammar is more natural.

:::

#### Legacy Syntax (Deprecated)

::: warning This may cause rendering issues on platforms like GitHub.
:::

When you set `legacySize: true` in plugin options, you can append `=widthxheight` at the end of image link section with spaces as separator.

Both `width` and `height` should be numbers as pixels and are optional.

```md
![Alt](/example.png =200x300)
![Alt](/example.jpg "Title" =200x)
![Alt](/example.bmp =x300)
```

Renders as ↓

```html
<img src="/example.png" width="200" height="300" />
<img src="/example.jpg" title="Title" width="200" />
<img src="/example.bmp" height="300" />
```

### Figure Display

Sometimes, you may want to add a description with image and place it between contents, in this case you should set `figure: true` in plugin options.

If the image is standalone in a line, wrapped or not wrapped by link, it will be displayed as `<figure>` and title (or alt) will be displayed as `<figcaption>`.

::: preview

![VuePress Logo](/favicon.ico)

[![VuePress Logo](/favicon.ico)](https://vuejs.press/)

![VuePress Logo](/favicon.ico "VuePress Logo")

[![VuePress Logo](/favicon.ico "VuePress Logo")](https://vuejs.press/)

!\[VuePress Logo]\(https://vuejs.press/images/hero.png "VuePress Logo" =300x300)

:::

## Options

### figure

* Type: `MarkdownItFigureOptions | boolean`
* Details: Whether enable figure support.

### lazyload

* Type: `boolean`
* Details: Whether to lazy load every image in page in native way.

### mark

* Type: `MarkdownItImgMarkOptions | boolean`

  ```ts
  interface MarkdownItImgMarkOptions {
    /** lightmode only IDs */
    light?: string[]
    /** darkmode only IDs */
    dark?: string[]
  }
  ```

* Details: Whether enable image mark support.

### size

* Type: `boolean`
* Details: Whether enable image size support.

### obsidianSize

* Type: `boolean`
* Details: Whether enable obsidian image size support.

### legacySize

* Type: `boolean`
* Details: Whether enable legacy image size support.

---

---
url: /plugins/markdown/markdown-include.md
---
# markdown-include

Add markdown include features to your VuePress site.

## Usage

```bash
npm i -D @vuepress/plugin-markdown-include@next
```

```ts title=".vuepress/config.ts"
import { markdownIncludePlugin } from '@vuepress/plugin-markdown-include'

export default {
  plugins: [
    markdownIncludePlugin({
      // options
    }),
  ],
}
```

## Syntax

Use `<!-- @include: filename -->` to include a file.

To partially import a file, you can specify the range of lines to be included:

* `<!-- @include: filename{start-end} -->`
* `<!-- @include: filename{start-} -->`
* `<!-- @include: filename{-end} -->`

Also, you can include a file region:

* `<!-- @include: filename#region -->`

:::: info File region

File region is a concept in vscode, where the region content is surrounded by `#region` and `#endregion` comments.

Here are some examples:

::: code-tabs#language

@tab HTML

```html
<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
  </head>
  <body>
    <!-- region snippet -->
    <p>
      Lorem ipsum dolor, sit amet consectetur adipisicing elit. Eligendi,
      repellendus. Voluptatibus alias cupiditate at, fuga tenetur error officiis
      provident quisquam autem, porro facere! Neque quibusdam animi quaerat
      eligendi recusandae eaque.
    </p>
    <!-- endregion snippet -->
    <p>
      Veniam harum illum natus omnis necessitatibus numquam architecto eum
      dignissimos, quos a adipisci et non quam maxime repellendus alias ipsum,
      vero praesentium laborum commodi perferendis velit repellat? Vero,
      cupiditate sequi.
    </p>
  </body>
</html>
```

@tab Markdown

```md
## Hello world

<!-- #region snippet -->

Lorem ipsum dolor sit amet consectetur adipisicing elit. Voluptates
inventore iure quo aut doloremque, ipsum ab voluptatem ipsa, velit laborum
illo quae omnis reiciendis hic, ut dolorem non debitis in!

<!-- #endregion snippet -->

Veniam harum illum natus omnis necessitatibus numquam architecto eum
dignissimos, quos a adipisci et non quam maxime repellendus alias ipsum,
vero praesentium laborum commodi perferendis velit repellat? Vero,
cupiditate sequi.
```

@tab TS

```ts
import { include } from '@mdit/plugin-include'
import MarkdownIt from 'markdown-it'

// #region snippet
const mdIt = MarkdownIt().use(include, {
  // your options, currentPath is required
  currentPath: (env) => env.filePath,
})
// #endregion snippet

mdIt.render('<!-- @include: ./path/to/include/file.md -->', {
  filePath: 'path/to/current/file.md',
})
```

@tab JS

```js
const { include } = require('@mdit/plugin-include')
const MarkdownIt = require('markdown-it')

// #region snippet
const mdIt = MarkdownIt().use(include, {
  // your options, currentPath is required
  currentPath: (env) => env.filePath,
})
// #endregion snippet

mdIt.render('<!-- @include: ./path/to/include/file.md -->', {
  filePath: 'path/to/current/file.md',
})
```

@tab css

```css
html,
body {
  margin: 0;
  padding: 0;
}

/* #region snippet */
h1 {
  font-size: 1.5rem;
}
/* #endregion snippet */

h2 {
  font-size: 1.2rem;
}
```

@tab Less

```less
html,
body {
  margin: 0;
  padding: 0;
}

/* #region snippet */
h1 {
  font-size: 1.5rem;
}
/* #endregion snippet */

h2 {
  font-size: 1.2rem;
}
```

@tab Sass

```scss
html,
body {
  margin: 0;
  padding: 0;
}

/* #region snippet */
h1 {
  font-size: 1.5rem;
}
/* #endregion snippet */

h2 {
  font-size: 1.2rem;
}
```

@tab Java

```java
public class HelloWorld {
  // #region snippet
  public static void main(String args[]){
    System.out.println("Hello World");
  }
  // #endregion snippet
}
```

@tab Python

```py
class MyClass:
    msg = "world"

    #region snippet
    def sayHello(self):
        print("Hello " + self.msg + "!")
    #endregion snippet

    def sayBye(self):
        print("Bye " + self.msg + "!")
```

@tab Visual Basic

```vb
Imports System

Module Module1
   # Region snippet
   Sub Main()
     Console.WriteLine("Hello World!")
     Console.WriteLine("Press Enter Key to Exit.")
     Console.ReadLine()
   End Sub
   # EndRegion
End Module
```

@tab Bat

```bat
>nul 2>&1 "%SYSTEMROOT%\system32\cacls.exe" "%SYSTEMROOT%\system32\config\system"
if '%errorlevel%' NEQ '0' (
echo Requesting administrative privileges...
goto UACPrompt
) else ( goto gotAdmin )

::#region snippet
:UACPrompt
echo Set UAC = CreateObject^("Shell.Application"^) > "%temp%\getadmin.vbs"
echo UAC.ShellExecute "%~s0", "", "", "runas", 1 >> "%temp%\getadmin.vbs"
"%temp%\getadmin.vbs"
exit /B
::#endregion snippet

:gotAdmin
if exist "%temp%\getadmin.vbs" ( del "%temp%\getadmin.vbs" )
pushd "%CD%"
CD /D "%~dp0"
```

@tab C#

```cs
using System;

namespace HelloWorldApp {

    class Geeks {

        // #region snippet
        static void Main(string[] args) {

            // statement
            // printing Hello World!
            Console.WriteLine("Hello World!");

            // To prevents the screen from
            // running and closing quickly
            Console.ReadKey();
        }
        // #endregion snippet
    }
}
```

@tab C/C++

```cpp
#include <iostream>
#include <vector>

std::vector<int> v;

#pragma region snippet
int f() {
  for (int item : v) std::cout << item << std::endl;
  return v.size();
}
#pragma endregion snippet

int main() {
  int n, u;
  std::cin >> n;
  for (int i = 1; i <= n; ++i) {
    std::cin >> u;
    v.push_back(u);
  }
  std::cout << f();
  return 0;
}
```

:::

::::

## Demo

`<!-- @include: ./demo.snippet.md -->`:

`<!-- @include: ./demo.snippet.md{9-13} -->`:

`<!-- @include: ./demo.snippet.md#snippet -->`:

## Options

### resolvePath

* Type: `(path: string, cwd: string | null) => string`
* Default: `(path) => path`
* Details: Handle the include file path.

### deep

* Type: `boolean`
* Details: Whether to recursively include files referenced in included Markdown files.

### useComment

* Type: `boolean`
* Default: `true`
* Details: Whether use `<!-- @include: xxx -->` instead of `@include: xxx` to include files.

### resolveImagePath

* Type: `boolean`
* Default: `true`
* Details: Whether resolve the image related path in the included Markdown file.

### resolveLinkPath

* Type: `boolean`
* Default: `true`
* Details: Whether resolve the related file link path in the included Markdown file.

---

---
url: /plugins/markdown/markdown-math.md
---
# markdown-math

Add math support to your VuePress site.

This plugin allows you to use `mathjax` or `katex` to render $\TeX$ in your markdown content.

## Usage

```bash
npm i -D @vuepress/plugin-markdown-math@next

# install one of the following packages:
npm i -D @mathjax/src
npm i -D katex
```

```ts title=".vuepress/config.ts"
import { markdownMathPlugin } from '@vuepress/plugin-markdown-math'

export default {
  plugins: [
    markdownMathPlugin({
      // options
    }),
  ],
}
```

## Syntax

* Inline mode: `$xxx$`

  ::: preview

  Euler's identity $e^{i\pi}+1=0$ is a beautiful formula in $\mathbb{R}^2$.

  :::

* Display mode:

  ```md
  $$xxx$$

  $$
  xxx
  $$
  ```

  ::: preview

  $$
  \frac {\partial^r} {\partial \omega^r} \left(\frac {y^{\omega}} {\omega}\right)
  \= \left(\frac {y^{\omega}} {\omega}\right) \left{(\log y)^r + \sum\_{i=1}^r \frac {(-1)^ Ir \cdots (r-i+1) (\log y)^{ri}} {\omega^i} \right}
  $$

  :::

:::: tip Escaping

Escaping can be done by using `\` before the `$` character, or adding space both before and after the `$` character.

::: preview

The $a=1$ is a TeX equation, while $ a=1 $ and $a=1$ is not.

:::

::::

## Support List

TeX Tutorial:

* [TeX Tutorial](https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes)
* [TeX Cheat Sheets](https://mdit-plugins.github.io/tex.html#tex-tutorial)

Plugin tutorial and FAQs: [TeX](https://mdit-plugins.github.io/tex.html#tex-tutorial)

Katex:

* [KaTeX Support Features](https://katex.org/docs/supported.html)
* [KaTeX Support List](https://katex.org/docs/support_table.html)

Mathjax:

* [Supported TeX/LaTeX commands](https://docs.mathjax.org/en/latest/input/tex/macros/index.html#tex-commands)

## Options

### type

* Type: `'katex' | 'mathjax'`
* Details:

  The package to render $\TeX$ contents.

  * `'katex'`: use [KaTeX](https://katex.org/)
  * `'mathjax'`: use [MathJax](https://www.mathjax.org/)

  When this option is not specified, the plugin will try to detect which package is installed. If both are installed, it will use "mathjax".

### delimiters

* Type: `'brackets' | 'dollars' | 'all'`
* Default: `'dollars'`
* Details: Math delimiter syntax to enable.
  * `'brackets'`: Use `\(...\)` for inline math and `\[...\]` for display math (LaTeX style).
  * `'dollars'`: Use `$...$` for inline math and `$$...$$` for display math (common Markdown style).
  * `'all'`: Enable both bracket and dollar syntaxes.

### Using KaTeX

When using KaTeX, any other options will be passed to KaTeX as `KatexOptions`. See [KaTeX Docs](https://katex.org/docs/options.html) for all available options.

Besides, 2 special options are supported:

#### copy

* Type: `boolean`
* Details: Whether to enable copy extension.

#### mhchem

* Type: `boolean`
* Details: Whether to enable mhchem extension.

### Using MathJax

When using MathJax, you can set:

#### tex

* Type: `object`
* Details: Options passed to TeX input parser.

#### output

* Type: `'svg' | 'chtml'`
* Default: `'svg'`
* Details: Output format, either SVG or Common HTML.

#### chtml

* Type: `object`
* Details: Options passed to Common HTML output parser.

#### svg

* Type: `object`
* Details: Options passed to SVG output parser.

---

---
url: /plugins/markdown/markdown-preview.md
---
# markdown-preview

Support preview contents in VuePress site.

## Usage

```bash
npm i -D @vuepress/plugin-markdown-preview@next
```

```ts title=".vuepress/config.ts"
import { markdownPreviewPlugin } from '@vuepress/plugin-markdown-preview'

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

## Guide

The plugin provides a `preview` container and `VPPreview` component to preview contents in VuePress site.

You can use the `preview` container in markdown files like this:

```md
::: preview Optional Title

Preview Contents

:::
```

It will be rendered as a preview container in the site, showing both the content and its raw code:

::: preview Optional Title

Preview Contents

:::

Sometimes, codes for users may be different with embedding preview contents, you can use the `VPPreview` component directly to achieve this:

````md
<VPPreview title="Optional Title">
  <template #content>
    <!-- Your content here  -->

    Hello world!

  </template>
  <template #code>
    <!-- Your code here -->

```js
document.querySelector('body').innerText = 'Hello world!'
```

  </template>
</VPPreview>
````

```
Hello world!
```

```js
document.querySelector('body').innerText = 'Hello world!'
```

## Options

### locales

* Type: `Record<string, MarkdownPreviewLocaleData>`

  ```ts
  export interface MarkdownPreviewLocaleData {
    /**
     * Toggle code button text
     */
    toggle: string
  }
  ```

* Details: Locales configuration for `<VPPreview>`.

## Styles

You can customize the style via CSS variables:

@[code css](@vuepress/plugin-markdown-preview/src/client/styles/vars.css)

---

---
url: /plugins/markdown/markdown-stylize.md
---
# markdown-stylize

Stylizing content in your VuePress site.

## Usage

```bash
npm i -D @vuepress/plugin-markdown-stylize@next
```

```ts title=".vuepress/config.ts"
import { markdownStylizePlugin } from '@vuepress/plugin-markdown-stylize'

export default {
  plugins: [
    markdownStylizePlugin({
      // options
    }),
  ],
}
```

## Syntax

### Align Content

You can use `left` `center` `right` `justify` to align text.

:::: preview

::: left
Contents to align left
:::

::: center
Contents to align center
:::

::: right
Contents to align right
:::

::: justify
Contents to align justify
:::

::::

### Appending Attributes

You can use `{attrs}` to add attrs to Markdown content.

For example, if you want a heading2 "Hello World" with an id "say-hello-world", you can write:

```md
## Hello World {#say-hello-world}
```

If you want an image with class "full-width", you can write:

```md
![img](link/to/image.png) {.full-width}
```

Also, other attrs are supported, so:

```md
A paragraph with some text. {#p .a .b align=center customize-attr="content with spaces"}
```

will be rendered into:

```html
<p id="p" class="a b" align="center" customize-attr="content with spaces">
  A paragraph with some text.
</p>
```

For all demos, see [@mdit/plugin-attrs](https://mdit-plugins.github.io/attrs.html#demo).

### Highlighting Content

You can use `==` to mark text with `<mark>`.

::: preview

VuePress is ==powerful==!

:::

### Creating Spoilers

You can use `!! !!` to mark content as spoiler.

::: preview

VuePress is !!powerful!!.

:::

### Superscript and Subscript

You can use `^` for superscript and `~` for subscript.

::: preview

H~2~O is a liquid. 2^10^ is 1024.

:::

### Create your own stylize rules

The `custom` option receives an array, where each element accepts 2 options:

* `matcher`: should be `string` or `RegExp`.
* `replacer`: a function customizing the matched token.

For example, you can use the following config to transform `*Recommended*` into a Badge Recommended

```js {6-18} title=".vuepress/config.js"
import { markdownStylizePlugin } from '@vuepress/plugin-markdown-stylize'

export default {
  plugins: [
    markdownStylizePlugin({
      custom: [
        {
          matcher: 'Recommended',
          replacer: ({ tag }) => {
            if (tag === 'em')
              return {
                tag: 'Badge',
                attrs: { type: 'tip' },
                content: 'Recommended',
              }

            return null
          },
        },
      ],
    }),
  ],
}
```

Another example is you want to set all the emphasis `n't` words to red color, so that `Setting this to an invalid syntax *doesn't* have any effect.` becomes: "Setting this to an invalid syntax doesn't have any effect."

```js {6-18} title=".vuepress/config.js"
import { markdownStylizePlugin } from '@vuepress/plugin-markdown-stylize'

export default {
  plugins: [
    markdownStylizePlugin({
      custom: [
        {
          matcher: /n't$/,
          replacer: ({ tag, attrs, content }) => {
            if (tag === 'em')
              return {
                tag: 'span',
                attrs: { ...attrs, style: 'color: red' },
                content,
              }

            return null
          },
        },
      ],
    }),
  ],
}
```

Also, you can use `stylize` in frontmatter to provide extra stylize rules for content of the page.

## Options

### align

* Type: `boolean`
* Details: Whether to enable align support.

### attrs

* Type: `MarkdownItAttrsOptions | boolean`
* Details: Whether to enable attrs support. You can also pass an object to specify the options of [@mdit/plugin-attrs](https://mdit-plugins.github.io/attrs.html#advanced).

### mark

* Type: `boolean`
* Details: Whether to enable mark format support.

### spoiler

* Type: `boolean`
* Details: Whether to enable spoiler support.

### sup

* Type: `boolean`
* Details: Whether to enable superscript format support.

### sub

* Type: `boolean`
* Details: Whether to enable subscript format support.

### custom

* Type: `MarkdownItStylizeConfig[]`
* Details: Create own stylize customizations. For details, see [@mdit/plugin-stylize](https://mdit-plugins.github.io/stylize.html#usage).

---

---
url: /plugins/markdown/markdown-tab.md
---
# markdown-tab

Add tabs and code tabs to your VuePress site.

This plugin has been integrated into the default theme.

## Usage

```bash
npm i -D @vuepress/plugin-markdown-tab@next
```

```ts title=".vuepress/config.ts"
import { markdownTabPlugin } from '@vuepress/plugin-markdown-tab'

export default {
  plugins: [
    markdownTabPlugin({
      // Enable code tabs
      codeTabs: true,
      // Enable tabs
      tabs: true,
    }),
  ],
}
```

## Tabs Guide

You need to wrap your tabs in `tabs` container.

You can add an id suffix in `tabs` container, which will be used as tab id. All tabs with the same id will share the same switch event.

```md
<!-- 👇 here, fruit will be used as id, it's optional -->

::: tabs#fruit

<!-- tabs content -->

:::
```

Inside this container, you should use `@tab` marker to mark and separate tab contents.

Behind `@tab` marker, you can add text `:active` to activate the tab by default, and the text will be resolved as tab title.

```md
::: tabs

@tab title 1

<!-- tab 1 content -->

@tab title 2

<!-- tab 2 content -->

<!-- 👇 tab 3 will be activated by default -->

@tab:active title 3

<!-- tab 3 content -->

:::
```

By default, the title will be used as the value of the tab, but you can override it using an id suffix.

```md
::: tabs

<!-- 👇 here, tab 1's title "title 1" will be used as value. -->

@tab title 1

<!-- tab 1 content -->

<!-- 👇 here, tab 2's title will be "title 2", and it will bind with the value "value2" -->

@tab title 2#value2

<!-- tab 2 content -->

:::
```

You can use Vue syntax and components in each tab, and you can access `value` and `isActive`, indicating the tab's binding value and whether the tab is active.

### Switching together and persisting choice

If you want to make some tab groups switch together, you can use tab ids to bind them. Also, each tab id's choice will be stored and persisted.

:::: preview

Choose a package manager:

::: tabs#shell

@tab npm

npm should be installed with Node.js.

@tab pnpm

```bash
corepack enable
corepack use pnpm@latest
```

:::

Install `vuepress`:

::: tabs#shell

@tab Using npm#npm

```bash
npm i -D vuepress
```

@tab Using pnpm#pnpm

```bash
pnpm add -D vuepress
```

:::

::::

## Code Tabs Guide

This is the same as [tabs](#tabs-guide), but it's specially built for code blocks.

Only the first code fence after `@tab` marker is rendered inside code tabs, other Markdown content will be ignored.

## Demo

:::: preview Tabs

A tab of fruit:

::: tabs#fruit

@tab apple#apple

Apple

@tab banana#banana

Banana

:::

Another tab of fruit:

::: tabs#fruit

@tab apple

Apple

@tab banana

Banana

@tab orange

Orange

:::

A tab of fruit without id:

::: tabs

@tab apple

Apple

@tab banana

Banana

@tab orange

Orange

:::

::::

:::: preview Code Tabs

Install VuePress:

::: code-tabs#shell

@tab pnpm

```bash
pnpm add -D vuepress
```

@tab yarn

```bash
yarn add -D vuepress
```

@tab:active npm

```bash
npm i -D vuepress
```

:::

Install VuePress Tabs Plugin:

::: code-tabs#shell

@tab pnpm

```bash
pnpm add -D @vuepress/plugin-markdown-tab
```

@tab yarn

```bash
yarn add -D @vuepress/plugin-markdown-tab
```

@tab:active npm

```bash
npm i -D @vuepress/plugin-markdown-tab
```

:::

::::

## Options

### tabs

* Type: `boolean`
* Details: Whether to enable tabs.

### codeTabs

* Type: `boolean`
* Details: Whether to enable code tabs.

## Styles

You can customize the style via CSS variables:

@[code css](@vuepress/plugin-markdown-tab/src/client/styles/vars.css)

---

---
url: /plugins/markdown/prismjs.md
---
# prismjs

This plugin enables syntax highlighting for markdown code fences with [Prism.js](https://prismjs.com/).

This plugin has been integrated into the default theme.

## Usage

```bash
npm i -D @vuepress/plugin-prismjs@next
```

```ts title=".vuepress/config.ts"
import { prismjsPlugin } from '@vuepress/plugin-prismjs'

export default {
  plugins: [
    prismjsPlugin({
      // options
    }),
  ],
}
```

## Options

### theme

* Type: `PrismjsTheme`

* Default: `'nord'`

* Details: Prism.js theme that will be applied to code blocks.

### themes

* Type: `{ light: PrismjsTheme; dark: PrismjsTheme }`

* Details:

  Apply light/dark dual themes.

  Note: To use this feature, your theme must set the `data-theme="dark"` attribute on the `<html>` tag when dark mode is enabled.

::: tip Available Prism.js Light themes

* ateliersulphurpool-light
* coldark-cold
* coy
* duotone-light
* ghcolors
* gruvbox-light
* material-light
* one-light
* vs

:::

::: tip Available Prism.js Dark themes

* atom-dark
* cb
* coldark-dark
* dark
* dracula
* duotone-dark
* duotone-earth
* duotone-forest
* duotone-sea
* duotone-space
* gruvbox-dark
* holi
* hopscotch
* lucario
* material-dark
* material-oceanic
* night-owl
* nord
* one-dark
* pojoaque
* shades-of-purple
* solarized-dark-atom
* tomorrow
* vsc-dark-plus
* xonokai
* z-touch

:::

### lineNumbers

* Type: `boolean | number | 'disable'`

* Default: `true`

* Details:

  * `number`: The minimum number of lines to enable line numbers.
    For example, if you set it to 4, line numbers will only be enabled when your code block has at least 4 lines of code.
  * `true`: Enable line numbers globally.
  * `false`: Disable line numbers globally.
  * `'disable'`: Completely disable line numbers; `:line-numbers` will not take effect.

  You can add `:line-numbers` / `:no-line-numbers` markers in your fenced code blocks to override the value set in config, and customize the beginning number by adding `=` after `:line-numbers`. For example, `:line-numbers=2` means the line numbers in code blocks will start from `2`.

::: preview

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

```ts :no-line-numbers
// line-numbers is disabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts :line-numbers=2
// line-numbers is enabled and starts from 2
const line3 = 'This is line 3'
const line4 = 'This is line 4'
```

:::

### highlightLines

* Type: `boolean`

* Default: `true`

* Details:

  Whether to enable code line highlighting. You can highlight specified lines of your code blocks by adding line range markers in your fenced code blocks:

  * Line ranges: `{5-8}`
  * Multiple single lines: `{4,7,9}`
  * Combined: `{4,7-13,16,23-27,40}`

::: preview

```ts {1,7-9}
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  title: 'Hello, VuePress',

  theme: defaultTheme({
    logo: 'https://vuepress.vuejs.org/images/hero.png',
  }),
})
```

:::

### collapsedLines

* Type: `boolean | number | 'disable'`

* Default: `'disable'`

* Details: Default behavior of code block collapsing.

  * `number`: Collapse the code block starting from line `number` by default. For example, `12` means collapsing the code block starting from line 12.
  * `true`: Equivalent to `15`, collapsing the code block starting from line 15 by default.
  * `false`: Add support for code block collapsing, but disable it globally.
  * `'disable'`: Completely disable code block collapsing; `:collapsed-lines` will not take effect.

  To override global settings, you can add the `:collapsed-lines` / `:no-collapsed-lines` markers to the code block. You can also add `=` after `:collapsed-lines` to customize the starting line number being collapsed. For example, `:collapsed-lines=12` means collapsing the code block starting from line 12.

::: preview

```css :collapsed-lines
html {
  margin: 0;
  background: black;
  height: 100%;
}

body {
  margin: 0;
  width: 100%;
  height: inherit;
}

/* the three main rows going down the page */

body > div {
  height: 25%;
}

.thumb {
  float: left;
  width: 25%;
  height: 100%;
  object-fit: cover;
}

.main {
  display: none;
}
```

```css :no-collapsed-lines
html {
  margin: 0;
  background: black;
  height: 100%;
}

body {
  margin: 0;
  width: 100%;
  height: inherit;
}

/* the three main rows going down the page */

body > div {
  height: 25%;
}

.thumb {
  float: left;
  width: 25%;
  height: 100%;
  object-fit: cover;
}

.main {
  display: none;
}
```

```css :collapsed-lines=10
html {
  margin: 0;
  background: black;
  height: 100%;
}

body {
  margin: 0;
  width: 100%;
  height: inherit;
}

/* the three main rows going down the page */

body > div {
  height: 25%;
}

.thumb {
  float: left;
  width: 25%;
  height: 100%;
  object-fit: cover;
}

.main {
  display: none;
}
```

:::

### codeBlockTitle

* Type: `boolean | CodeBlockTitleRender`

  ```ts
  type CodeBlockTitleRender = (title: string, code: string) => string
  ```

* Default: `true`

* Details: Whether to enable code block title rendering. Add `title="Title"` after the code block \`\`\` to set the title.

  Pass `CodeBlockTitleRender` to customize the title rendering.

* Example:

  ::: preview

  ```ts title="foo/baz.js"
  console.log('hello')
  ```

  :::

::: tip

In the new version, some functionalities similar to [shiki](https://shiki.style/packages/transformers) have been implemented, allowing you to style code blocks using the same syntax.

:::

### notationDiff

* Type: `boolean`

* Default: `false`

* Details: Whether to enable notation diff.

* Example:

  ````md
  ```ts
  console.log('hewwo') // [\!code --]
  console.log('hello') // [\!code ++]
  console.log('goodbye')
  ```
  ````

  ```ts
  console.log('hewwo') // [!code --]
  console.log('hello') // [!code ++]
  console.log('goodbye')
  ```

* Also see:
  * [Shiki > Notation Diff](https://shiki.style/packages/transformers#transformernotationdiff)

### notationFocus

* Type: `boolean`

* Default: `false`

* Details: Whether to enable notation focus.

* Example:

  ````md
  ```ts
  console.log('Not focused')
  console.log('Focused') // [\!code focus]
  console.log('Not focused')
  ```
  ````

  ```ts
  console.log('Not focused')
  console.log('Focused') // [!code focus]
  console.log('Not focused')
  ```

* Also see:
  * [Shiki > Notation Focus](https://shiki.style/packages/transformers#transformernotationfocus)

### notationHighlight

* Type: `boolean`

* Default: `false`

* Details: Whether to enable notation highlight.

* Example:

  ````md
  ```ts
  console.log('Not highlighted')
  console.log('Highlighted') // [\!code highlight]
  console.log('Not highlighted')
  ```
  ````

  ```ts
  console.log('Not highlighted')
  console.log('Highlighted') // [!code highlight]
  console.log('Not highlighted')
  ```

* Also see:
  * [Shiki > Notation Highlight](https://shiki.style/packages/transformers#transformernotationhighlight)

### notationErrorLevel

* Type: `boolean`

* Default: `false`

* Details: Whether to enable notation error level.

* Example:

  ````md
  ```ts
  console.log('No errors or warnings')
  console.warn('Warning') // [\!code warning]
  console.error('Error') // [\!code error]
  ```
  ````

  ```ts
  console.log('No errors or warnings')
  console.warn('Warning') // [!code warning]
  console.error('Error') // [!code error]
  ```

* Also see:
  * [Shiki > Notation Error Level](https://shiki.style/packages/transformers#transformernotationerrorlevel)

### notationWordHighlight

* Type: `boolean`

* Default: `false`

* Details: Whether to enable notation word highlight.

  Word highlight must be written on a separate line.

* Example:

  Highlight words with comments

  ````md
  ```ts
  // [\!code word:Hello]
  const message = 'Hello World'
  console.log(message) // prints Hello World
  ```
  ````

  ```ts
  // [!code word:Hello]
  const message = 'Hello World'
  console.log(message) // prints Hello World
  ```

  Highlight words based on the meta string provided on the code snippet

  ::: preview

  ```js /Hello/
  const msg = 'Hello World'
  console.log(msg) // prints Hello World
  ```

  :::

* Also see:
  * [Shiki > Notation Word Highlight](https://shiki.style/packages/transformers#transformernotationwordhighlight)

### whitespace

* Type: `boolean | 'all' | 'boundary' | 'trailing'`

* Default: `false`

* Details: Whether to enable whitespace characters (Space and Tab).

  * `true`: Enable whitespace, but not render any whitespace by default.
  * `false`: Completely disable whitespace rendering; `:whitespace` will not take effect.
  * `'all'`: Render all whitespace.
  * `'boundary'`: Render leading and trailing whitespace of the line.
  * `'trailing'`: Render trailing whitespace of the line.

  You can add `:whitespace` / `:no-whitespace` markers in your fenced code blocks to override the value set in config, and customize the render type by adding `=` after `:whitespace`. For example, `:whitespace=boundary` will render leading and trailing whitespace of the line.

* Example:

  ::: preview

  ```md :whitespace
  <!-- render all whitespace -->

  A text  
  with trailing spaces

      indented text
  ```

  ```md :whitespace=boundary
  <!-- render leading and trailing whitespace of the line -->

  A text  
  with trailing spaces

      indented text
  ```

  ```md :whitespace=trailing
  <!-- render trailing whitespace of the line -->

  A text  
  with trailing spaces

      indented text
  ```

  ```md :no-whitespace
  <!-- disable render whitespace -->

  A text  
  with trailing spaces

      indented text
  ```

  :::

* Also see:
  * [Shiki > Render Whitespace](https://shiki.style/packages/transformers#transformerrenderwhitespace)

### preloadLanguages

* Type: `string[]`

* Default: `['markdown', 'jsdoc', 'yaml']`

* Details:

  Languages to preload.

  By default, languages will be loaded on demand when parsing markdown files.

  However, Prism.js has [some potential issues](https://github.com/PrismJS/prism/issues/2716) about loading languages dynamically. To avoid them, you can preload languages via this option.

### preWrapper

* Type: `boolean`

* Default: `true`

* Details:

  Whether to add an extra wrapper outside the `<pre>` tag.

  The wrapper is required by `lineNumbers` and `collapsedLines`. This means if you disable `preWrapper`, the line numbers and collapsed lines will also be disabled.

  ::: tip

  You can disable it if you want to implement them on the client side. For example, [Prismjs Line Highlight](https://prismjs.com/plugins/line-highlight/) or [Prismjs Line Numbers](https://prismjs.com/plugins/line-numbers/).

  :::

---

---
url: /plugins/markdown/revealjs/index.md
---
# revealjs

Add presentation in your VuePress site via Reveal.js.

## Usage

```bash
npm i -D @vuepress/plugin-revealjs@next
```

```js {7} title=".vuepress/config.js"
import { revealJsPlugin } from '@vuepress/plugin-revealjs'

export default {
  plugins: [
    revealJsPlugin({
      // plugin options
    }),
  ],
}
```

## Slide Syntax

* Use `---` to split slides
* Use `--` to split slides vertically

```md
@slidestart

<!-- slide1 -->

---

<!-- slide2 -->

---

<!-- slide3 -->

@slideend
```

::: preview Slide Demo

@slidestart

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

:::

By default, we use `auto` theme to render the presentation, but you can also use other themes with `@slidestart THEME_NAME`.

You can enable the following themes in reveal.js via `themes` in plugin options:

* `auto` (Default)
* `black`
* `white`
* `league`
* `beige`
* `sky`
* `night`
* `serif`
* `simple`
* `solarized`
* `blood`
* `moon`

For the appearance of each theme, see [Themes demo](themes.md).

::: important Assets Path

Since markdown content between `@slidestart` and `@slideend` is handled by Reveal.js in the browser, you can only use absolute paths for assets in slides, which must be directly accessible in the browser. Relative paths or aliases are not supported.

:::

## Slide Layout

By default, the plugin registers a layout named `SlidePage` for you to render slides pages.

In pages using this layout, you should only include a single slide syntax and no other content to avoid rendering problems.

```md
---
layout: SlidePage
---

@slidestart

<!-- slide content here -->

@slideend
```

You can customize this behavior via `layout` in plugin options with `false` to disable it or another layout name.

## Demo

Please see [Slides Demo](demo.md)

## Customize Reveal.js

### Built-in Plugins

You can enable built-in plugins in reveal.js via `plugins` in plugin options. It accepts an array of the following plugin names:

* `highlight`
* `math`
* `search`
* `notes`
* `zoom`

::: note

`markdown` plugin is enabled anyway to support markdown grammar.

:::

### Advanced Configuration

You can also import and call `defineRevealJsConfig` in [client config file][client-config] to customize reveal.js:

The `defineRevealJsConfig` function accepts a ref, getter or plain object as reveal.js options:

```js title=".vuepress/client.js"
import { defineRevealJsConfig } from '@vuepress/plugin-revealjs/client'

// plain object
const options1 = {
  // options
}

// or getter
const options2 = () => ({
  // options
})

// or ref
const options3 = ref({
  // options
})

defineRevealJsConfig(options1or2or3)
```

::: note

Reveal.js also provides [more plugins](https://github.com/hakimel/reveal.js/wiki/Plugins,-Tools-and-Hardware), you can add them via `plugins` option in `defineRevealJsConfig`. Built-in plugins you request at node side will be added automatically.

:::

### Per Page Configuration

You can also set `revealJs` to pass options to reveal.js per page in frontmatter.

For reveal.js options, see [reveal.js config](https://revealjs.com/config/). For reveal.js usage, see [reveal.js documentation](https://revealjs.com/)

## Options

### plugins

* Type: `RevealJsPlugin[]`
* Details: Built-in reveal.js plugins to enable.

  Available values: `highlight`, `math`, `search`, `notes`, `zoom`

### themes

* Type: `RevealJsTheme[]`
* Default: `['auto']`
* Details: Themes to enable.

  Available values: `auto`, `black`, `white`, `league`, `beige`, `sky`, `night`, `serif`, `simple`, `solarized`, `blood`, `moon`

### layout

* Type: `string | false`
* Default: `'SlidePage'`
* Details: Layout component name to render slides.

## Styles

You can customize the style via CSS variables:

@[code css](@vuepress/plugin-revealjs/src/client/styles/vars.css)

[client-config]: https://vuejs.press/guide/configuration.html#client-config-file

---

---
url: /plugins/markdown/revealjs/demo.md
---
# Slide Demo
@slidestart

## Slide Demo

A simple slide demo and useful hints.

> By Mr.Hope. Please scroll mouse wheel down to the next slide

***

## Marking Slides

[👇](#/1/1)

\--

## Marking Slides

Use `---` to mark horizontal slides

Use `--` to separate vertical slides in a horizontal slide.

Use `<!-- .slide: ... -->` to add attributes to slide

Use `<!-- .element: ... -->` to add attributes to the previous HTML element

***

## Markdown

You can use all kinds of markup in slides.

\--

## Markdown

You can use all kinds of markup in slides.

### This is an H3

Headings will transform to UPPERCASE by default.

Here is paragraph with some **bold**, *italic*, ~~strike-through~~ text and a [link](https://mister-hope.com), and it can auto break itself, so you don't need to worry the length.

\--

## Markdown

You can use all kinds of markup in slides.

List is `inline-block` by default.

* Item
* Item
* Item

1. Item 1
2. Item 2
3. Item 3

\--

## Markdown

You can use all kinds of markup in slides.

Code block will get auto highlight if you enable `highlight` plugin.

```js
const a = 1
```

\--

## Markdown

You can use all kinds of markup in slides.

You can also write math equation using tex syntax if you enable `math` plugin.

$$
J(\theta\_0,\theta\_1) = \sum\_{i=0}
$$

\--

## Markdown

You can use all kinds of markup in slides.

⚠**Note**: Table, hr and other nonstandard Markdown syntax is not supported.

***

## Layout

\--

## Layout

👆 The `r-fit-text` class makes text as large as possible without overflowing the slide.

\--

## Layout

![Logo](https://theme-hope-assets.vuejs.press/logo.svg)

👆 The `r-stretch` class helper lets you resize an element, like an image or video, to cover the remaining vertical space in a slide.

\--

## Layout

### Background

Custom background by adding `data-background` attribute to slide.

***

## Fragment

\--

## Fragment

Fragments are used to highlight or incrementally reveal individual elements on a slide.

Add `fragment` and animation class to element.

\--

## Fragment

### Animation class

* `fade-in`

- `fade-out`

* `fade-up`

- `fade-down`

* `fade-left`

- `fade-right`

* `fade-in-then-out`

- `fade-in-then-semi-out`

\--

## Fragment

### Animation class

* `grow`

- `shrink`

* `strike`

- `highlight-red`

* `highlight-green`

- `highlight-blue`

* `highlight-current-red`

- `highlight-current-green`

* `highlight-current-blue`

\--

## Fragment

### Multiple fragments

Multiple fragments can be applied to the same element sequentially by wrapping it

\--

## Fragment

### Order

Order can be changed using the `data-fragment-index` attribute.

Multiple elements can appear at the same index.

* Appears last

- Appears second

* Appears first

- Appears second

***

## Transition

\--

## Transition

Transition can be changed by setting the `transition` config option globally or `data-transition` attribute on slide.

Possible values:

* none
* fade
* slide

- convex
- concave
- zoom

\--

## Transition

### Auto animate

`data-auto-animate` can be added on nearby slides to make an animation on unchanged elements.

***

## Functions

\--

## Functions

### Code

By enabling `highlight` plugin, you can highlight code blocks.

You can use `[a-b|c-d]` syntax to highlight lines by steps.

```js [1-2|3|4]
const a = 1
const b = 2
const c = (x) => 1 + 2 + x
c(3)
```

\--

## Functions

### Overview

Press `Esc` or `O` to enter overview mode when the slide is active

\--

## Functions

### Full Screen

Press `F` or `F11` to enter full-screen when the slide is active

\--

## Functions

### Zoom

Hold down the `alt` key (`ctrl` in Linux) and click on any element to zoom towards it.

Click again to zoom back out.

***

## The End

@slideend

---

---
url: /plugins/markdown/revealjs/themes.md
---
# Reveal.js Themes

## `auto`

> Based on theme mode.

@slidestart

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

## `black`

@slidestart black

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

## `white`

@slidestart white

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

## `league`

@slidestart league

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

## `beige`

@slidestart beige

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

## `sky`

@slidestart sky

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

## `night`

@slidestart night

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

## `serif`

@slidestart serif

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

## `simple`

@slidestart simple

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

## `solarized`

@slidestart solarized

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

## `blood`

@slidestart blood

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

## `moon`

@slidestart moon

## Slide Title

A paragraph with some text and a [link](https://mister-hope.com)

***

## Highlight

```js [2-4|1-5]
const add = (a, b) => {
  if (typeof b === 'undefined') return a + 1

  return a + b
}
```

@slideend

---

---
url: /plugins/markdown/shiki.md
---
# shiki

This plugin enables syntax highlighting for markdown code fence with [Shiki](https://shiki.style/).

::: tip

[Shiki](https://shiki.style/) is the syntax highlighter used by VSCode. It provides higher fidelity highlighting but may be slower than [Prism.js](https://prismjs.com/), especially when processing many code blocks.

:::

## Usage

```bash
npm i -D @vuepress/plugin-shiki@next
```

```ts title=".vuepress/config.ts"
import { shikiPlugin } from '@vuepress/plugin-shiki'

export default {
  plugins: [
    shikiPlugin({
      // options
      langs: ['ts', 'json', 'vue', 'md', 'bash', 'diff'],
    }),
  ],
}
```

## Options

### langs

* Type: `ShikiLang[]`

* Details: Additional languages to be parsed by Shiki.

  ::: tip

  The plugin automatically loads languages used in your markdown files, so manual specification is not required.

  :::

* Also see:
  * [Shiki > Languages](https://shiki.style/languages)

### langAlias

* Type: `{ [lang: string]: string }`

* Details: Custom language aliases for Shiki.

* Also see:
  * [Shiki > Custom Language Aliases](https://shiki.style/guide/load-lang#custom-language-aliases)

### theme

* Type: `ShikiTheme`

* Default: `'nord'`

* Details: Shiki theme to be applied to code blocks.

* Also see:
  * [Shiki > Themes](https://shiki.style/themes)

### themes

* Type: `{ light: ShikiTheme; dark: ShikiTheme }`

* Details: Dark/light dual themes for Shiki.

  The styles of both themes will be injected as `--shiki-light` and `--shiki-dark` CSS variables to code blocks:

  ```html
  <span style="--shiki-light:lightColor;--shiki-dark:darkColor;">code</span>
  ```

* Also see:
  * [Shiki > Dual Themes](https://shiki.style/guide/dual-themes)

### lineNumbers

* Type: `boolean | number | 'disable'`
* Default: `true`
* Details: Controls the display of line numbers.

  * `number`: minimum number of lines required to enable line numbers.
    For example, setting it to 4 will only enable line numbers when your code block has at least 4 lines.
  * `true`: enable line numbers globally.
  * `false`: disable line numbers globally.
  * `'disable'`: completely disable line numbers; `:line-numbers` will not take effect.

  You can add `:line-numbers` / `:no-line-numbers` markers to your fenced code blocks to override the config setting, and customize the starting number by adding `=` after `:line-numbers`. For example, `:line-numbers=2` will start line numbers from `2`.

::: preview

```ts:line-numbers
// line-numbers are enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts :no-line-numbers
// line-numbers are disabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

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

:::

### highlightLines

* Type: `boolean`
* Default: `true`
* Details: Whether to enable code line highlighting. You can highlight specified lines by adding line range markers to your fenced code blocks:
  * Line ranges: `{5-8}`
  * Multiple single lines: `{4,7,9}`
  * Combined: `{4,7-13,16,23-27,40}`

::: preview

```ts {1,7-9}
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  title: 'Hello, VuePress',

  theme: defaultTheme({
    logo: 'https://vuepress.vuejs.org/images/hero.png',
  }),
})
```

:::

### collapsedLines

* Type: `boolean | number | 'disable'`
* Default: `'disable'`
* Details: Default behavior of code block collapsing.

  * `number`: collapse the code block starting from line `number` by default, for example, `12` means collapsing the code block starting from line 12.
  * `true`: Equivalent to `15`, collapsing the code block starting from line 15 by default.
  * `false`: Add support for code block collapsing, but disable it globally
  * `'disable'`: Completely disable code block collapsing, `:collapsed-lines` will not take effect.

  To override global settings, you can add the `:collapsed-lines` / `:no-collapsed-lines` marker to the code block. You can also add `=` after `:collapsed-lines` to customize the starting line number being collapsed, for example, `:collapsed-lines=12` means collapsing the code block starting from line 12.

::: preview

```css :collapsed-lines
html {
  margin: 0;
  background: black;
  height: 100%;
}

body {
  margin: 0;
  width: 100%;
  height: inherit;
}

/* the three main rows going down the page */

body > div {
  height: 25%;
}

.thumb {
  float: left;
  width: 25%;
  height: 100%;
  object-fit: cover;
}

.main {
  display: none;
}
```

```css :no-collapsed-lines
html {
  margin: 0;
  background: black;
  height: 100%;
}

body {
  margin: 0;
  width: 100%;
  height: inherit;
}

/* the three main rows going down the page */

body > div {
  height: 25%;
}

.thumb {
  float: left;
  width: 25%;
  height: 100%;
  object-fit: cover;
}

.main {
  display: none;
}
```

```css :collapsed-lines=10
html {
  margin: 0;
  background: black;
  height: 100%;
}

body {
  margin: 0;
  width: 100%;
  height: inherit;
}

/* the three main rows going down the page */

body > div {
  height: 25%;
}

.thumb {
  float: left;
  width: 25%;
  height: 100%;
  object-fit: cover;
}

.main {
  display: none;
}
```

:::

### codeBlockTitle

* Type: `boolean | CodeBlockTitleRender`

  ```ts
  type CodeBlockTitleRender = (title: string, code: string) => string
  ```

* Default: `true`

* Details: Whether to enable code block title rendering. Add `title="Title"` after the code block \`\`\` to set the title.

  Pass a `CodeBlockTitleRender` function to customize title rendering.

* Example:

  ::: preview

  ```ts title="foo/baz.js"
  console.log('hello')
  ```

  :::

### notationDiff

* Type: `boolean`

* Default: `false`

* Details: Whether to enable notation diff.

* Example:

  ````md
  ```ts
  console.log('hewwo') // [\!code --]
  console.log('hello') // [\!code ++]
  console.log('goodbye')
  ```
  ````

  ```ts
  console.log('hewwo') // [!code --]
  console.log('hello') // [!code ++]
  console.log('goodbye')
  ```

* Also see:
  * [Shiki > Notation Diff](https://shiki.style/packages/transformers#transformernotationdiff)

### notationFocus

* Type: `boolean`

* Default: `false`

* Details: Whether to enable notation focus.

* Example:

  ````md
  ```ts
  console.log('Not focused')
  console.log('Focused') // [\!code focus]
  console.log('Not focused')
  ```
  ````

  ```ts
  console.log('Not focused')
  console.log('Focused') // [!code focus]
  console.log('Not focused')
  ```

* Also see:
  * [Shiki > Notation Focus](https://shiki.style/packages/transformers#transformernotationfocus)

### notationHighlight

* Type: `boolean`

* Default: `false`

* Details: Whether to enable notation highlight.

* Example:

  ````md
  ```ts
  console.log('Not highlighted')
  console.log('Highlighted') // [\!code highlight]
  console.log('Not highlighted')
  ```
  ````

  ```ts
  console.log('Not highlighted')
  console.log('Highlighted') // [!code highlight]
  console.log('Not highlighted')
  ```

* Also see:
  * [Shiki > Notation Highlight](https://shiki.style/packages/transformers#transformernotationhighlight)

### notationErrorLevel

* Type: `boolean`

* Default: `false`

* Details: Whether to enable notation error level.

* Example:

  ````md
  ```ts
  console.log('No errors or warnings')
  console.warn('Warning') // [\!code warning]
  console.error('Error') // [\!code error]
  ```
  ````

  ```ts
  console.log('No errors or warnings')
  console.warn('Warning') // [!code warning]
  console.error('Error') // [!code error]
  ```

* Also see:
  * [Shiki > Notation Error Level](https://shiki.style/packages/transformers#transformernotationerrorlevel)

### notationWordHighlight

* Type: `boolean`

* Default: `false`

* Details: Whether to enable notation word highlight.

  Word highlights must be written on separate lines.

* Example:

  Highlight words with comments

  ````md
  ```ts
  // [\!code word:Hello]
  const message = 'Hello World'
  console.log(message) // prints Hello World
  ```
  ````

  ```ts
  // [!code word:Hello]
  const message = 'Hello World'
  console.log(message) // prints Hello World
  ```

  Highlight words based on the meta string provided in the code snippet

  ::: preview

  ```js /Hello/
  const msg = 'Hello World'
  console.log(msg) // prints Hello World
  ```

  :::

* Also see:
  * [Shiki > Notation Word Highlight](https://shiki.style/packages/transformers#transformernotationwordhighlight)

### whitespace

* Type: `boolean | 'all' | 'boundary' | 'trailing'`

* Default: `false`

* Details: Whether to enable whitespace characters (spaces and tabs).

  * `true`: enable whitespace rendering but don't render any whitespace by default
  * `false`: completely disable whitespace rendering; `:whitespace` will not take effect
  * `'all'`: render all whitespace characters
  * `'boundary'`: render leading and trailing whitespace on each line
  * `'trailing'`: render trailing whitespace on each line

  You can add `:whitespace` / `:no-whitespace` markers to your fenced code blocks to override the config setting, and customize the render type by adding `=` after `:whitespace`. For example, `:whitespace=boundary` will render leading and trailing whitespace on each line.

* Example:

  ::: preview

  ```md :whitespace
  <!-- render all whitespace -->

  A text  
  with trailing spaces

      indented text
  ```

  ```md :whitespace=boundary
  <!-- render leading and trailing whitespace on each line -->

  A text  
  with trailing spaces

      indented text
  ```

  ```md :whitespace=trailing
  <!-- render trailing whitespace on each line -->

  A text  
  with trailing spaces

      indented text
  ```

  ```md :no-whitespace
  <!-- disable whitespace rendering -->

  A text  
  with trailing spaces

      indented text
  ```

  :::

* Also see:
  * [Shiki > Render Whitespace](https://shiki.style/packages/transformers#transformerrenderwhitespace)

### twoslash

* Type: `boolean | ShikiTwoslashOptions`

  ```ts
  interface ShikiTwoslashOptions extends TransformerTwoslashOptions {
    /**
     * Requires adding `twoslash` to the code block explicitly to run twoslash
     * @default true
     */
    explicitTrigger?: RegExp | boolean

    /**
     * twoslash options
     */
    twoslashOptions?: TransformerTwoslashOptions['twoslashOptions'] &
      VueSpecificOptions

    /**
     * The options for caching resolved types
     * @default true
     */
    typesCache?: TwoslashTypesCache | boolean
  }
  ```

* Default: `false`

* Details: Whether to enable [twoslash](https://github.com/twoslashes/twoslash).

  ::: tip

  For size optimization, the plugin doesn't include the `@vuepress/shiki-twoslash` package by default. You need to install it manually to use this feature.

  :::

* Also see:
  * [Shiki > Twoslash](https://shiki.style/packages/twoslash)
  * [Twoslash > TransformerTwoslashOptions](https://github.com/shikijs/shiki/blob/main/packages/twoslash/src/types.ts#L30)
  * [Twoslash > VueSpecificOptions](https://github.com/twoslashes/twoslash/blob/main/packages/twoslash-vue/src/index.ts#L36)
  * [TwoslashTypesCache](https://github.com/vuepress/ecosystem/blob/main/tools/shiki-twoslash/src/node/options.ts#L47)

* Example:

  ::: preview

  ```ts twoslash
  const a = 1
  const b = 23
  console.log(a + b)
  ```

  :::

  ::: warning

  For code blocks with `twoslash` enabled:

  * Don't add the `:v-pre` marker to code blocks, as this will prevent `twoslash` from running properly.

  * To avoid layout conflicts, line numbers will not be displayed for these code blocks.

  :::

## Advanced Options

### defaultLang

* Type: `string`
* Default: `'plain'`
* Details: Fallback language to use when the specified language is not available.

### logLevel

* Type: `'warn' | 'debug' | 'silent'`
* Default: `'warn'`
* Details: Log level for Shiki language detection.
  * `warn`: warn about each unknown language once (default)
  * `debug`: log every unknown code block with its file path (default when `--debug` flag is set)
  * `silent`: no warnings

### preWrapper

* Type: `boolean`
* Default: `true`
* Details: Whether to add an extra wrapper outside the `<pre>` tag.

  This wrapper is required for `lineNumbers` and `collapsedLines` features. If you disable `preWrapper`, line numbers and collapsed lines will also be disabled.

### shikiSetup

* Type: `(shiki: Highlighter) => void | Promise<void>`
* Details: A hook function to customize the Shiki highlighter instance.

### transformers

* Type: `ShikiTransformer[]`

* Details: Shiki transformers.

  This option will be passed to the `codeToHtml()` method of Shiki.

* Also see:
  * [Shiki > Transformers](https://shiki.style/guide/transformers)

---

---
url: /plugins/pwa/index.md
---
# PWA Plugins

---

---
url: /plugins/pwa/pwa/index.md
---
# pwa

## Usage

```bash
npm i -D @vuepress/plugin-pwa@next
```

```ts title=".vuepress/config.ts"
import { pwaPlugin } from '@vuepress/plugin-pwa'

export default {
  plugins: [
    pwaPlugin({
      // options
    }),
  ],
}
```

---

---
url: /plugins/pwa/pwa/config.md
---
# Config

## Options

### serviceWorkerFilename

* Type: `string`
* Default: `"service-worker.js"`
* Details: Service Worker file path.

### showInstall

* Type: `boolean`
* Details: Whether to display install button when Service Worker is first registered successfully.

### manifest

* Type: `AppManifest`

* Reference:
  * [MDN Web Docs: Web App Manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest)
  * [W3C: Web App Manifest](https://www.w3.org/TR/appmanifest/)

* Details: You can fill with an object which will be parsed to manifest.webmanifest.

  ::: tip

  Some options have their fallback if you don't set them.

  * name: `siteConfig.title` || `siteConfig.locales['/'].title` || `"Site"`
  * short\_name: `siteConfig.title` || `siteConfig.locales['/'].title` || `"Site"`
  * description: `siteConfig.description` || `siteConfig.locales['/'].description` || `"A site built with vuepress"`
  * lang: `siteConfig.locales['/'].lang` || `"en-US"`
  * start\_url: `context.base`
  * scope: `context.base`
  * display: `"standalone"`
  * theme\_color: `"#46bd87"`
  * background\_color: `"#ffffff"`
  * orientation: `"portrait-primary"`
  * prefer\_related\_applications: `false`

  :::

### favicon

* Type: `string`
* Details: Link of favicon.ico.

  ::: warning

  We recommend setting favicon for your site.

  :::

### themeColor

* Type: `string`
* Default: `"#46bd87"`
* Details: Theme color of the PWA.

### maxSize

* Type: `number`
* Default: `2048`
* Details: Max size allowed to be cached, in KB.

  ::: warning

  This option has the highest priority, and any files exceeding this value will be excluded.

  So if you generate very large HTML or JS files, please consider increasing this value, otherwise your PWA may not work normally in offline mode.

  :::

### cacheHTML

* Type: `boolean`
* Details: Whether to cache HTML files besides home page and 404 page.

### cacheImage

* Type: `boolean`
* Details: Whether to cache pictures.

### maxImageSize

* Type: `number`
* Default: `1024`
* Details: Max picture size allowed to be cached, in KB.

  ::: tip

  The value must not be greater than maxSize option.

  :::

### update

* Type: `"disable" | "available" | "hint" | "force"`
* Default: `"available"`
* Details: Control logic when new content is found.

  * `"disable"`: Do nothing even when new service worker is available. After new service work succeeds installing and starts waiting, it will control page and provide new content in next visit.

  * `"available"`: Only display update popup when the new service worker is available.

  * `"hint"`: Display a hint to let user choose to refresh immediately. This is helpful when you want users to see new docs immediately.

    ::: tip

    If users choose to refresh, the current service worker will be unregister, and request will start coming to web. Later the new service worker will start installing and control current page after installed.

    :::

  * `"force"`: unregister current service worker immediately then refresh to get new content.

    ::: danger

    Although this ensures users are viewing the latest content, it may affect viewing experiences.

    :::

  ::: tip

  How docs are updated is controlled by a previous version, so the current option only affects the next update from this version.

  :::

### apple

* Type: `ApplePwaOptions | false`
* Details: Special settings for better supporting Safari, ignoring these options are safe.

#### apple.icon

* Type: `string`
* Details: Icon link used by Safari.

#### apple.maskIcon

* Type: `string`
* Details: Safari mask icon.

#### apple.statusBarColor

* Type: `"black-translucent" | "black" | "default"`
* Default: `"default"`
* Details: Status bar color for Safari.

### foundComponent

* Type: `string`
* Default: `"PwaFoundPopup"`
* Details: Path of custom hint popup component.

### readyComponent

* Type: `string`
* Default: `"PwaReadyPopup"`
* Details: Path of custom update popup component.

### appendBase

* Type: `boolean`
* Details: Whether append base to all absolute links in options.

### generateSwConfig

* Type: `Partial<GenerateSWOptions>`
* Details: Options passed to `workbox-build`, for details, see [Workbox documentation](https://developers.google.com/web/tools/workbox/reference-docs/latest/module-workbox-build#.generateSW).

### locales

* Type: `PwaPluginLocaleConfig`

  ```ts
  interface PwaPluginLocaleData {
    /**
     * Install button text
     */
    install: string

    /**
     * iOS install hint text
     */
    iOSInstall: string

    /**
     * Cancel button text
     */
    cancel: string

    /**
     * Close button text
     */
    close: string

    /**
     * Previous image text
     */
    prevImage: string

    /**
     * Next image text
     */
    nextImage: string

    /**
     * Install explain text
     */
    explain: string

    /**
     * Description label text
     */
    desc: string

    /**
     * Feature label text
     */
    feature: string

    /**
     * Update hint text
     */
    hint: string

    /**
     * Update available text
     */
    update: string
  }

  interface PwaPluginLocaleConfig {
    [localePath: string]: Partial<PwaPluginLocaleData>
  }
  ```

* Details: Locales config for pwa plugin.

  ::: details Built-in Supported Languages

  * **Simplified Chinese** (zh-CN)
  * **Traditional Chinese** (zh-TW)
  * **English (United States)** (en-US)
  * **German** (de-DE)
  * **Russian** (ru-RU)
  * **Ukrainian** (uk-UA)
  * **Vietnamese** (vi-VN)
  * **Portuguese** (pt)
  * **Polish** (pl-PL)
  * **French** (fr-FR)
  * **Spanish** (es-ES)
  * **Slovak** (sk-SK)
  * **Japanese** (ja-JP)
  * **Turkish** (tr-TR)
  * **Korean** (ko-KR)
  * **Finnish** (fi-FI)
  * **Indonesian** (id-ID)
  * **Dutch** (nl-NL)

  :::

## Composition API

### usePwaEvent

* Type: `() => EventEmitter`

* Returns: Event emitter of this plugin / 插件的事件发射器

* Details: Returns the event emitter of this plugin. You can add listener function to events that provided by [register-service-worker](https://github.com/yyx990803/register-service-worker).

* Example:

  ```ts
  import { usePwaEvent } from '@vuepress/plugin-pwa/client'

  export default {
    setup(): void {
      const event = usePwaEvent()
      event.on('ready', (registration) => {
        console.log('Service worker is active.')
      })
    },
  }
  ```

## Utilities

### forceUpdate

* Type: `() => void`

* Details: Force update the page when an update is found.

* Example:

  ```ts
  import { forceUpdate } from '@vuepress/plugin-pwa/client'
  import { onMounted } from 'vue'

  export default {
    setup(): void {
      onMounted(() => {
        forceUpdate()
      })
    },
  }
  ```

### registerSW

* Type: `(serviceWorkerPath: string, hooks?: Hooks, showStatus?: boolean) => void`

* Parameters:

  | Parameter         | Type      | Description                          |
  | ----------------- | --------- | ------------------------------------ |
  | serviceWorkerPath | `string`  | Path of the service worker           |
  | hooks             | `object`  | Hooks of service worker              |
  | showStatus        | `boolean` | Log service worker status in console |

  ```ts
  interface Hooks {
    registrationOptions?: RegistrationOptions
    ready?: (registration: ServiceWorkerRegistration) => void
    registered?: (registration: ServiceWorkerRegistration) => void
    cached?: (registration: ServiceWorkerRegistration) => void
    updated?: (registration: ServiceWorkerRegistration) => void
    updatefound?: (registration: ServiceWorkerRegistration) => void
    offline?: () => void
    error?: (error: Error) => void
  }
  ```

* Details: Register service worker manually.

* Example:

  ```ts
  import { registerSW } from '@vuepress/plugin-pwa/client'
  import { onMounted } from 'vue'

  export default {
    setup(): void {
      onMounted(() => {
        registerSW('/service-worker.js', {
          ready(registration) {
            console.log('Service worker is active.')
          },
        })
      })
    },
  }
  ```

### skipWaiting

* Type: `(registration: ServiceWorkerRegistration) => void`

* Parameters:

  | Parameter    | Type                        | Description                                              |
  | ------------ | --------------------------- | -------------------------------------------------------- |
  | registration | `ServiceWorkerRegistration` | The registration of the service worker you want activate |

* Details: Activate the waiting service worker.

* Example:

  ```ts
  import { skipWaiting, usePwaEvent } from '@vuepress/plugin-pwa/client'

  export default {
    setup(): void {
      const event = usePwaEvent()

      event.on('updated', (registration) => {
        console.log('The waiting service worker is available.')
        // activate the waiting service worker
        skipWaiting(registration)
      })
    },
  }
  ```

### unregisterSW

* Type: `() => void`

* Details: Unregister service worker manually.

* Example:

  ```ts
  import { unregisterSW } from '@vuepress/plugin-pwa/client'
  import { onMounted } from 'vue'

  export default {
    setup(): void {
      onMounted(() => {
        unregisterSW()
      })
    },
  }
  ```

## Styles

You can customize the style via CSS variables:

@[code css](@vuepress/plugin-pwa/src/client/styles/vars.css)

---

---
url: /plugins/pwa/pwa/guide.md
---
# Guide

## Intro

Make your VuePress site a Progressive Web Application (PWA)\[^pwa-intro].

This plugin uses [workbox-build](https://developers.google.com/web/tools/workbox/modules/workbox-build) to generate the service worker file, and uses [register-service-worker](https://github.com/yyx990803/register-service-worker) to register the service worker.

::: warning

If you have enabled this plugin once and want to disable it, you might need [`@vuepress/plugin-remove-pwa`](../remove-pwa.md) to remove the existing service worker.

:::

\[^pwa-intro]: **PWA Introduction**

```
PWA, full name Progressive Web App. PWA standard is stipulated by W3C.

It allows sites to install themselves as an App on supported platforms through browsers that support this feature.

See <https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps> for details.
```

A PWA uses a Service Worker \[^service-worker] (SW for short) to cache and proxy site content.

\[^service-worker]: **Service Worker Introduction**

```
1. The Service Worker will get and cache all the files registered in it during the registration process.

1. After the registration completes, the Service Worker is activated and starts to proxy and control all your requests.

1. Whenever you want to initiate an access request through the browser, the Service Worker will check whether it exists in its own cache list. If it exists, it will directly return the cached result; otherwise, it will call its own fetch method to get it. You can use a custom fetch method to fully control the result of requests for resources in the web page, such as providing a fallback web page when offline.

1. Every time the user reopens the site, the Service Worker will request the link where it was registered. If a new version of Service Worker is detected, it will update itself and start caching the list of resources registered in the new Service Worker. After the content update is successfully obtained, the Service Worker will trigger the `update` event. The user can be notified through this event, for example, a pop-up window will be displayed in the lower right corner, prompting the user that new content is available and allowing the user to trigger an update.
```

## Web App Manifests

To make your website fully compliant with PWA, a Web App Manifest \[^manifest] file is needed, and your PWA should satisfy the installability [^installable] specification.

\[^manifest]: **Manifest File**

```
The manifest file uses the JSON format and is responsible for declaring various information of the PWA, such as name, description, icon, and shortcut actions.

In order for your site to be registered as a PWA, you need to meet the basic specifications of the manifest to make the browser consider the site as an installable PWA and allow users to install it.

::: tip

For Manifest standards and specifications, please see [MDN Web app manifests](https://developer.mozilla.org/en-US/docs/Web/Manifest) and [W3C Manifest](https://w3c.github.io/manifest/).

:::
```

[^installable]: **Installable**

```
To let the site be registered as a PWA, the site needs to successfully register a valid service worker by itself, and declare a valid manifest file with its link in meta tag.

The manifest file should contain at least `name` (or `short_name`) `icons` `start_url`.

On safari, the maximum cache size of the service worker is 50 MB.
```

You can set the `manifest` option to customize the manifest file, or provide a `manifest.webmanifest` or `manifest.json` in the public folder. The former has higher priority.

The plugin will automatically generate `manifest.webmanifest` for you and add a manifest link declaration in each page, while **you should still at least set a valid icon through `manifest.icons` or other icon-related options in the PWA plugin.**

::: warning

The installability [^installable] specification requires at least one valid icon to be declared in the manifest.

So if you do not configure `manifest.icons`, visitors can only enjoy the offline accessibility brought by the Service Worker cache, but cannot install your site as a PWA.

:::

Besides, the plugin does not process anything in the manifest by default, but outputs them as-is. This means that if you plan to deploy to a subdirectory, you should append the URL prefix to manifest URLs yourself. If everything you need is all under the `base` directory, you can set `appendBase: true` in plugin options to let the plugin append `base` to any links in the manifest.

## Cache Control

To better control what the Service Worker can pre-cache, the plugin provides related options for cache control.

### Default Cache

By default, the plugin will pre-cache all `js` and `css` files, and only the homepage and 404 HTML are cached. The plugin will also cache font files (woff, woff2, eot, ttf, otf) and SVG icons.

### Image Cache

If your site has only a few important images and you want them displayed in offline mode, you can cache site images by setting `cacheImage: true`.

We recognize images by file extension. Any files ending with `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp` will be regarded as images.

### HTML Cache

If you have a small site and would like to make documents fully available offline, you can set `cacheHTML` to `true` to cache all HTML files.

::: tip Why are only home and 404 pages cached by default?

Though VuePress generates HTML files through SSG\[^ssg] for all pages, these files are mainly used for SEO\[^seo] and allow you to directly configure the backend without SPA\[^spa] to visit any link.

\[^ssg]: **SSG**: **S**tatic **S**ite **G**eneration

\[^seo]: **SEO**: **S**earch **E**ngine **O**ptimization

\[^spa]: **SPA**: **S**ingle **P**age **A**pplication, most of them only have the homepage and use history mode to handle routing instead of actually navigating between pages.

VuePress is essentially an SPA. This means that you only need to cache the home page and enter from the home page to access all pages normally. Therefore, not caching other HTML by default can effectively reduce the cache size (40% smaller in size) and speed up the SW update speed.

But this also has disadvantages. If the user enters the site directly from a non-home page, the HTML file for the first page still needs to be loaded from the internet. Also, in an offline environment, users can only enter through the homepage and then navigate to the corresponding page by themselves. If they directly access a link, an inaccessible prompt will appear.

:::

### Size Control

To prevent large files from being included in the pre-cache list, any files > 2 MB or images > 1 MB will be omitted. You can customize these limits with `maxSize` and `maxImageSize` options (in KB unit).

## Update Control

We provide the `update` option to control how users receive updates.

The default value of the `update` option is `"available"`, which means that when new content is available, the new SW will be installed and its resources will be fetched silently in the background. A pop-up window appears once the new SW is ready, and users can choose whether to refresh immediately to view new content. This means users are reading old content before a new SW is ready.

If your project is still in the building stage and you want to alert the user that they may be reading outdated content, you can set this to `"hint"`. This allows users to be notified that new content has been published within seconds after visiting the docs. But the negative effect of this is that if the user chooses to update before the new SW is ready, they will need to get all the resources of the page from the internet before the new SW installs and controls the page.

If your docs are stable, or you're hosting a blog and don't care much about users receiving the latest version right away, you can set this to `"disabled"`, which means that the new SW will be installed completely silently in the background and start waiting. When all pages controlled by the old SW are closed, the new SW will start to take control and provide users with new content during the next visit. This setting can prevent users from being disturbed during their visit.

To speed up user access under weak or no network conditions through SW, but also want users to always access new content, you can set this option to `"force"`. This means any old SW will be removed as soon as a new SW is detected, and all pages are refreshed to ensure the user is browsing the latest content. The biggest disadvantage is that all users will experience an unexpected sudden refresh within seconds after re-entering an updated site.

### Popups

When new content is detected (new SW detected), an update found popup appears; and when the new content is ready, an update ready popup appears.

If you are not satisfied with the default popup content, you can use your own component. Import `PwaFoundPopup` or `PwaReadyPopup` from `@vuepress/plugin-pwa/client` and use its slot to customize the popup content, then pass the component path to `foundComponent` or `readyComponent` option:

```vue
<script setup lang="ts">
import { PwaFoundPopup } from '@vuepress/plugin-pwa/client'
</script>
<template>
  <PwaFoundPopup v-slot="{ found, refresh }">
    <div v-if="found">
      New content is found.
      <button type="button" @click="refresh">Refresh</button>
    </div>
  </PwaFoundPopup>
</template>
```

```vue
<script setup lang="ts">
import { PwaReadyPopup } from '@vuepress/plugin-pwa/client'
</script>
<template>
  <PwaReadyPopup v-slot="{ isReady, reload }">
    <div v-if="isReady">
      New content is ready.
      <button type="button" @click="reload">Apply</button>
    </div>
  </PwaReadyPopup>
</template>
```

## Other Options

The plugin also provides other PWA-related options, such as Microsoft tile icon and color settings, Apple icons, and so on. If you are an advanced user, you can also set `generateSwConfig` to configure `workbox-build`. Check [Plugin options](./config.md#options) for more details.

## Further Reading

For more details, please see:

* [Google PWA](https://web.dev/progressive-web-apps/)
* [MDN PWA](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps)
* [W3C Manifest Specification](https://w3c.github.io/manifest/)

---

---
url: /plugins/pwa/remove-pwa.md
---
# remove-pwa

This plugin removes service workers from your VuePress site, ensuring users can receive updates after you remove any previously enabled PWA plugin.

::: tip Why this plugin is needed if you used PWA plugin once?

PWA plugins like [`@vuepress/plugin-pwa`](./pwa/README.md) register service workers that cache your site for offline access.

If you remove a PWA plugin, the old service worker remains but can't receive updates as there's no new service worker to update to. Users will be stuck with the old version of your site.

To solve this problem:

1. A new empty service worker is generated in the original location.
2. This service worker removes cached content from the old service worker, then unregisters itself.

:::

## Usage

```bash
npm i -D @vuepress/plugin-remove-pwa@next
```

```ts title=".vuepress/config.ts"
import { removePwaPlugin } from '@vuepress/plugin-remove-pwa'

export default {
  plugins: [
    removePwaPlugin({
      // By default, all caches will be removed
      // To target specific caches, provide regex patterns
      cachePatterns: ['\\bworkbox\\b', 'precache-v2'],
      swLocation: 'service-worker.js',
    }),
  ],
}
```

## Options

### cachePatterns

* Type: `string[]`
* Default: `[]`
* Details: Regular expression patterns to match cache names for removal. If empty, all caches will be removed.

### swLocation

* Type: `string`
* Default: `'service-worker.js'`
* Details: Original service worker location relative to dest folder.

---

---
url: /plugins/search/index.md
---
# Search Plugins

---

---
url: /plugins/search/docsearch.md
---
# docsearch

Integrate [Algolia DocSearch](https://docsearch.algolia.com/) into VuePress to provide a full-text search experience for your documentation site.

## Usage

```bash
npm i -D @vuepress/plugin-docsearch@next
```

```ts title=".vuepress/config.ts"
import { docsearchPlugin } from '@vuepress/plugin-docsearch'

export default {
  plugins: [
    docsearchPlugin({
      // options
    }),
  ],
}
```

## Get Search Index

Before using this plugin, you need to prepare your search index. There are two ways to achieve this:

1. **Join the Official Program:**

   [Submit your site URL](https://docsearch.algolia.com/apply/) to the DocSearch program. Once your site is indexed, the DocSearch team will send the [apiKey](#apikey) and name of [indices](#indices) to your email. You can then configure this plugin with those credentials.

2. **Run Your Own Crawler:**
   You can [run your own crawler](https://docsearch.algolia.com/docs/run-your-own/) to generate the index. In this case, you will use your own [appId](#appid), [apiKey](#apikey), and name of [indices](#indices) to configure the plugin.

::: details Official crawler config

```js{35-50,59}
new Crawler({
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_API_KEY',
  rateLimit: 8,
  startUrls: [
    // These are urls which Algolia starts to crawl
    // If your site is divided into multiple parts,
    // you may want to set multiple entry links
    'https://YOUR_WEBSITE_URL/',
  ],
  sitemaps: [
    // if you are using sitemap plugins (e.g.: @vuepress-plugin/sitemap), you may provide one
    'https://YOUR_WEBSITE_URL/sitemap.xml',
  ],
  ignoreCanonicalTo: false,
  exclusionPatterns: [
    // You can use this to stop algolia crawing some paths
  ],
  discoveryPatterns: [
    // These are urls which Algolia is looking for,
    'https://YOUR_WEBSITE_URL/**',
  ],
  // Crawler schedule, set it according to your docs update frequency
  schedule: 'at 02:00 every 1 day',
  actions: [
    // you may have multiple actions, especially when you are deploying multiple docs under one domain
    {
      // name the index with name you like
      indexName: 'YOUR_INDEX_NAME',
      // paths where the index take effect
      pathsToMatch: ['https://YOUR_WEBSITE_URL/**'],
      // controls how algolia extracts records from your site
      recordExtractor: ({ $, helpers }) => {
        // options for @vuepress/theme-default
        return helpers.docsearch({
          recordProps: {
            lvl0: {
              selectors: '.vp-sidebar-heading.active',
              defaultValue: 'Documentation',
            },
            lvl1: '[vp-content] h1',
            lvl2: '[vp-content] h2',
            lvl3: '[vp-content] h3',
            lvl4: '[vp-content] h4',
            lvl5: '[vp-content] h5',
            lvl6: '[vp-content] h6',
            content: '[vp-content] p, [vp-content] li',
          },
          indexHeadings: true,
        })
      },
    },
  ],
  initialIndexSettings: {
    // controls how indexes are initialized
    // only has effects before index are initialize
    // you may need to delete your index and recraw after modification
    YOUR_INDEX_NAME: {
      attributesForFaceting: ['type', 'lang'],
      attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'],
      attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'],
      attributesToSnippet: ['content:10'],
      camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'],
      searchableAttributes: [
        'unordered(hierarchy_radio_camel.lvl0)',
        'unordered(hierarchy_radio.lvl0)',
        'unordered(hierarchy_radio_camel.lvl1)',
        'unordered(hierarchy_radio.lvl1)',
        'unordered(hierarchy_radio_camel.lvl2)',
        'unordered(hierarchy_radio.lvl2)',
        'unordered(hierarchy_radio_camel.lvl3)',
        'unordered(hierarchy_radio.lvl3)',
        'unordered(hierarchy_radio_camel.lvl4)',
        'unordered(hierarchy_radio.lvl4)',
        'unordered(hierarchy_radio_camel.lvl5)',
        'unordered(hierarchy_radio.lvl5)',
        'unordered(hierarchy_radio_camel.lvl6)',
        'unordered(hierarchy_radio.lvl6)',
        'unordered(hierarchy_camel.lvl0)',
        'unordered(hierarchy.lvl0)',
        'unordered(hierarchy_camel.lvl1)',
        'unordered(hierarchy.lvl1)',
        'unordered(hierarchy_camel.lvl2)',
        'unordered(hierarchy.lvl2)',
        'unordered(hierarchy_camel.lvl3)',
        'unordered(hierarchy.lvl3)',
        'unordered(hierarchy_camel.lvl4)',
        'unordered(hierarchy.lvl4)',
        'unordered(hierarchy_camel.lvl5)',
        'unordered(hierarchy.lvl5)',
        'unordered(hierarchy_camel.lvl6)',
        'unordered(hierarchy.lvl6)',
        'content',
      ],
      distinct: true,
      attributeForDistinct: 'url',
      customRanking: [
        'desc(weight.pageRank)',
        'desc(weight.level)',
        'asc(weight.position)',
      ],
      ranking: [
        'words',
        'filters',
        'typo',
        'attribute',
        'proximity',
        'exact',
        'custom',
      ],
      highlightPreTag: '<span class="algolia-docsearch-suggestion--highlight">',
      highlightPostTag: '</span>',
      minWordSizefor1Typo: 3,
      minWordSizefor2Typos: 7,
      allowTyposOnNumericTokens: false,
      minProximity: 1,
      ignorePlurals: true,
      advancedSyntax: true,
      attributeCriteriaComputedByMinProximity: true,
      removeWordsIfNoResults: 'allOptional',
    },
  },
})
```

The `recordProps` above is configured for the default theme. You may need to adjust the selectors to match your custom theme structure.

**Note:** The `initialIndexSettings.YOUR_INDEX_NAME.attributesForFaceting` field must include `'lang'` for this plugin to function correctly with multi-language support.
:::

::: tip
If you are not using the default theme or encounter issues with search results, check the crawler configuration above. You can go to the [Algolia Crawler](https://crawler.algolia.com/admin/crawlers/), and use the 'Editor' panel in the project sidebar to debug and modify your config.
:::

## Options

### appId

* Type: `string`

* Required: Yes

* Details: The Application ID of your Algolia application.

* Also see:
  * [DocSearch > Options > appId](https://docsearch.algolia.com/docs/api#appid)

### apiKey

* Type: `string`

* Required: Yes

* Details: The Search API Key provided by the DocSearch team or generated in your Algolia dashboard.

* Also see:
  * [DocSearch > Options > apiKey](https://docsearch.algolia.com/docs/api#apikey)

### indices

* Type: `Array<string | DocSearchIndex>`

* Required: Yes

* Details: A list of indices to use for keyword search. You can also provide optional `searchParameters` for each index.

* Also see:
  * [DocSearch > Options > indices](https://docsearch.algolia.com/docs/api#indices)

::: tip indexName

`indexName` as is shorthand for `indices` if you are only querying a single index. However, this is deprecated and will be removed in future versions. See [DocSearch > Options > indexName](https://docsearch.algolia.com/docs/api#indexname) for details.

:::

### placeholder

* Type: `string`

* Default: `'Search docs'`

* Details: The placeholder text displayed in the search input field.

* Reference:
  * [DocSearch > Options > placeholder](https://docsearch.algolia.com/docs/api/#placeholder)

### disableUserPersonalization

* Type: `boolean`

* Default: `false`

* Details: Whether to disable personalized features, such as recent searches and favorite searches.

* Reference:
  * [DocSearch > Options > disableUserPersonalization](https://docsearch.algolia.com/docs/api/#disableuserpersonalization)

### initialQuery

* Type: `string`

* Details: The initial search query to pre-fill when the modal opens.

* Reference:
  * [DocSearch > Options > initialQuery](https://docsearch.algolia.com/docs/api/#initialquery)

### maxResultsPerGroup

* Type: `number`

* Default: `5`

* Details: The maximum number of search results to display per group (e.g., per hierarchy level).

* Also see:
  * [DocSearch > Options > maxResultsPerGroup](https://docsearch.algolia.com/docs/api/#maxresultspergroup)

### translations

* Type: `Partial<DocSearchTranslations>`

* Details: Allows you to override the default text and labels used in the DocSearch button or modal.

* Also see:
  * [DocSearch > Options > translations](https://docsearch.algolia.com/docs/api/#translations)

### locales

* Type: `Record<string, DocSearchPluginOptions>`

* Details: Configuration for different locales. You can override any of the options above for specific language paths.

* Example:

```ts title=".vuepress/config.ts"
export default {
  plugins: [
    docsearchPlugin({
      appId: '<APP_ID>',
      apiKey: '<API_KEY>',
      indexName: '<INDEX_NAME>',
      locales: {
        '/': {
          placeholder: 'Search Documentation',
          translations: {
            button: {
              buttonText: 'Search Documentation',
            },
          },
        },
        '/zh/': {
          placeholder: '搜索文档',
          translations: {
            button: {
              buttonText: '搜索文档',
            },
          },
        },
      },
    }),
  ],
}
```

* Also see:
  * [Guide > I18n](https://vuejs.press/guide/i18n.html)

### indexBase

* Type: `string`
* Default: [base](https://vuejs.press/reference/config.html#base)
* Details: The base path of the site that generated the search index.

  This is useful if you deploy your documentation to multiple domains (e.g., different versions or mirrors) but want to share a single search index. You don't need to crawl every deployment. Instead, designate one domain as the **index domain**, let Algolia crawl it, and reuse that index across all deployments.

  If the [base](https://vuejs.press/reference/config.html#base) paths differ between the index domain and other deployments, set this option to the `base` of the index domain. This ensures that search result links are generated correctly for the current site.

### injectStyles

* Type: `boolean`
* Default: `true`
* Details: Whether to inject the default DocSearch styles.

  If the default styles conflict with your theme or you want to fully customize the appearance, you can set this to `false`.

  **Note:** When disabled, you are responsible for importing your own styles. Customizations made via CSS variables in the [Styles](#styles) section will no longer apply.

## Client options

### defineDocSearchConfig

```ts
type DocSearchClientLocaleOptions = Partial<DocSearchProps>

interface DocSearchClientOptions extends DocSearchClientLocaleOptions {
  locales?: Record<string, DocSearchClientLocaleOptions>
}

const defineDocSearchConfig: (
  options: MaybeRefOrGetter<DocSearchClientOptions>,
) => void
```

Customize DocSearch client options. Accepts a plain object, a ref, or a getter.

::: warning

To support VuePress routing and optimizations, the internal configuration handles `transformItems`, `hitComponent`, `navigator`, and `transformSearchClient`. Overriding these options directly may break the search functionality or navigation.

If you must customize them, please review the [internal implementation](https://github.com/vuepress/ecosystem/blob/main/plugins/search/plugin-docsearch/src/client/composables/useDocSearchSlim.ts) first to ensure compatibility.

:::

## Styles

You can customize the appearance using CSS variables provided by [@docsearch/css](https://docsearch.algolia.com/docs/styling).

The plugin overrides some variables to match the VuePress default theme styles.

## Components

* SearchBox

---

---
url: /plugins/search/guidelines.md
---
# Search Plugin Guidelines

To make VuePress theme support search plugins out of box, we have a set of guidelines that should be followed when creating a search plugin.

## Component Name

* If a search plugin provides a search box that is suitable to display in navbar or sidebars, it shall be named `SearchBox` and registered globally.

* If a search plugin provides a complex search result component with input and result list that is suitable to display in a single page, it shall be named `SearchPanel` and registered globally.

  The search plugin shall automatically generate a `/search.html` page with the `SearchPanel` component in every locales, but it must not override any existing page.

---

---
url: /plugins/search/meilisearch.md
---
# meilisearch

Integrate [MeiliSearch](https://www.meilisearch.com/) into VuePress, which can provide search to your documentation site.

## Setup MeiliSearch

To use MeiliSearch for free, you need to self-host it on your own server, otherwise you need to pay for MeiliSearch Cloud.

::: info MeiliSearch Cloud

To use MeiliSearch Cloud, you need to create an account and set up a new instance. You can find the instructions in the [MeiliSearch Cloud documentation](https://www.meilisearch.com/docs/cloud/getting_started).

:::

### Starting MeiliSearch

::: tip

In this section, we use Docker to self-host Meilisearch, see [MeiliSearch Docker docs](https://www.meilisearch.com/docs/guides/misc/docker) for details.

If you don't have Docker installed, you may also [install MeiliSearch manually](https://www.meilisearch.com/docs/learn/self_hosted/getting_started_with_self_hosted_meilisearch#setup-and-installation).

:::

First pull latest MeiliSearch docker image:

```sh
docker pull getmeili/meilisearch:latest
```

Then start the docker:

```sh :no-line-numbers
docker run -it --rm \
  # set container name to "MeiliSearch"
  --name MeiliSearch \
  # set your own master key
  # replace <YOUR_MASTER_KEY> with your own master key
  -e MEILI_MASTER_KEY='<YOUR_MASTER_KEY>' \
  # switch to production mode
  -e MEILI_ENV=production \
  # disable meilisearch analytics
  -e MEILI_NO_ANALYTICS=1 \
  # mapping 7700 port to host
  -p 7700:7700 \
  # mounting index database to host
  # you can change the path to anywhere you want
  -v $(pwd)/meili_data:/meili_data \
  getmeili/meilisearch:latest
```

Here `<YOUR_MASTER_KEY>` is the master key for MeiliSearch that you should set yourself (required >= 16 bytes), which is used to access the MeiliSearch API.

::: important Never expose Master Key

Search key can be generated for public access, which only allows search operations.

Your Master Key should only be used for internal server access (including scraping), as it grants full operational permissions. Do not mix use them and **never expose this key**!

:::

### Setting up the Scraper

::: tip

If you don't have Docker installed, you can [run scraper from source code](https://github.com/jqiue/docs-scraper?tab=readme-ov-file#from-source-code-).

:::

First, pull the latest MeiliSearch Scraper image:

```sh
docker pull jqiue/docs-scraper:latest
```

Then, create a **correct configuration file** for the scraper. Here, we provide a sample, which you should save it locally and modify according to your needs:

```json :collapsed-lines=10
{
  "index_uid": "<YOUR_INDEX_NAME>",
  "start_urls": ["https://<YOUR_WEBSITE_URL>/"],
  "sitemap_urls": ["https://<YOUR_WEBSITE_URL>/sitemap.xml"],
  "selectors": {
    "lvl0": {
      "selector": ".vp-sidebar-heading.active",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": "[vp-content] h1",
    "lvl2": "[vp-content] h2",
    "lvl3": "[vp-content] h3",
    "lvl4": "[vp-content] h4",
    "lvl5": "[vp-content] h5",
    "lvl6": "[vp-content] h6",
    "content": "[vp-content] p, [vp-content] li",
    "lang": {
      "selector": "/html/@lang",
      "global": true,
      "type": "xpath"
    }
  },
  "custom_settings": {
    "filterableAttributes": ["lang"]
  }
}
```

* `index_uid` should be a unique name for your index, which will be used to search.
* `start_urls` and `sitemap_urls` (optional) shall be customized according to the website to be scraped. We recommend using it with [`@vuepress/plugin-sitemap`](../seo/sitemap/README.md) plugin and providing the corresponding `sitemap.xml` URL.
* `selectors` field can be customized according to third-party theme DOM structure.
* You can add new fields to `custom_settings` according to your needs.

::: important Requirements for the configuration file

To let the plugin work:

* `lang` selector must be kept as is in `selectors` filed
* All fields that are currently in `custom_settings` must not be removed.

:::

Make sure MeiliSearch is currently running, then start scraping the document by running the docker:

```sh
docker run -t --rm \
  --network=host \
  -e MEILISEARCH_HOST_URL='<MEILISEARCH_HOST_URL>' \
  -e MEILISEARCH_API_KEY='<MEILISEARCH_MASTER_KEY>' \
  -v <absolute-path-to-your-config-file>:/docs-scraper/config.json \
  jqiue/docs-scraper:latest pipenv run ./docs_scraper config.json
```

Here:

* `<MEILISEARCH_HOST_URL>` should be the host URL of your MeiliSearch instance
* `<MEILISEARCH_MASTER_KEY>` shall be the master key you provided.
* `<absolute-path-to-your-config-file>` is the absolute path to the configuration file you created above.

When the scraper completes, MeiliSearch will update the existing index with latest document content.

Each time the scraper deletes and recreates the index, all documents will be deleted and re-added. This can be slow for a large number of documents. Therefore, our `jqiue/docs-scraper` allows you to provide `only_urls` to only scrape the changed document content.

The plugin provides a cli helper to generate `only_urls`, so `vp-meilisearch-scrapper <docsDir> <scraperPath>` can be added in CI or Git Hooks to automatically generate `only_urls` for your scraper configuration file.

```sh
Usage: vp-meilisearch-crawler [options] <source> [scraper-path]

Generate crawler config for meilisearch

Arguments:
  source                 Source directory of VuePress project
  scraper-path           Scrapper config file path (default: .vuepress/meilisearch-config.json relative to source folder)

Options:
  -c, --config [config]  Set path to config file
  --cache [cache]        Set the directory of the cache files
  --temp [temp]          Set the directory of the temporary files
  --clean-cache          Clean the cache files before generation
  --clean-temp           Clean the temporary files before generation
  -V, --version          output the version number
  -h, --help             display help for command
```

::: note

* `vp-meilisearch-crawler` needs to be run in a Git project.
* `scraper-path` must correctly point to your scraper configuration file, which should be properly set up with all necessary fields except for `only_urls`.
* If a full scrape is required, add `[full-scrape]` in the commit msg, and the cli will remove `only_urls` from the config file to perform a full scrape.

:::

### Setting up the Plugin

A search-only access key shall be generated for the plugin to work. This key can be generated using the MeiliSearch API.
You can use the following command to create a search-only access key:

```sh
curl \
  # Replace <YOUR_HOST> with your MeiliSearch host URL
  -X POST '<YOUR_HOST>/keys' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <MASTER_KEY>' \
  # description f
  --data-binary '{
    "indexes": ["<YOUR_INDEX_NAME>"],
    "actions": ["search"],
    "expiresAt": null,
    "description": "Search key for <YOUR_INDEX_NAME>"
  }'
```

Here:

* `<YOUR_HOST>` is the host URL of your MeiliSearch instance
* `<MASTER_KEY>` is the master key generated by MeiliSearch
* `<YOUR_INDEX_NAME>` is the name of the index you created
* `actions` specifies the actions that this key can perform. In this case, it is set to `["search"]`, which means it can only perform search operations.
* `expiresAt` sets the expiration date for the key, allowing you to control how long the key remains valid, `null` means it will never expire.

If successful, the response would look like this:

```json
{
  "name": null,
  "description": "Search key for <YOUR_INDEX_NAME>",
  "key": "adaf72e2a6d6f428ec465bc786ec41de868bbd53121997e89ba2299e9566c88213",
  "uid": "b84d1be5-caa5-4752-b078-8f40be39051d",
  "actions": ["search"],
  "indexes": ["<YOUR_INDEX_NAME>"],
  "expiresAt": null,
  "createdAt": "2024-01-27T06:50:33.668329328Z",
  "updatedAt": "2024-01-27T06:50:33.668329328Z"
}
```

Now, you can use the `key` in the plugin configuration. Install the plugin in your VuePress project and then provide required options:

```bash
npm i -D @vuepress/plugin-meilisearch@next
```

```ts
import { meilisearchPlugin } from '@vuepress/plugin-meilisearch'

export default {
  plugins: [
    meilisearchPlugin({
      host: '<MEILISEARCH_HOST_URL>',
      apiKey: '<YOUR_SEARCH_ONLY_KEY>',
      indexUid: '<YOUR_INDEX_NAME>',
    }),
  ],
}
```

### Automatic Re-scraping with Github Actions

Place your scraper config file somewhere in your project.

Then go to `Settings` -> `Secrets and variables` -> `Actions` in your Github repository. Click `New repository secret` and set `MEILISEARCH_MASTER_KEY` with your meilisearch master key.

Next add a new step `scrape` in your Github Actions workflow file, which will run after the deployment step. Here is an example of how to do this:

```yml
name: Deploy and Scrape

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # deploy your documentation here
      # ...

  scrape:
    needs: deploy
    runs-on: ubuntu-latest
    name: re-scrape documentation for Meilisearch
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          # This is required for the helper to compare the current and previous commits
          fetch-depth: 2

      - name: Generate Only URLs
        # You may need to cd to the directory where `@vuepress/plugin-meilisearch` is installed first
        run: pnpm vp-meilisearch-scrapper <docsDir> <path/to/your/scraper/config.json>

      - name: Run scraper
        env:
          # replace with your own MeiliSearch host URL
          HOST_URL: <YOUR_MEILISEARCH_HOST_URL>
          API_KEY: ${{ secrets.MEILISEARCH_MASTER_KEY }}
          # replace it with the path to your config file
          CONFIG_FILE_PATH: ${{ github.workspace }}/<path/to/your/scraper/config.json>
        run: |
          docker run -t --rm \
            -e MEILISEARCH_HOST_URL=$HOST_URL \
            -e MEILISEARCH_API_KEY=$API_KEY \
            -v $CONFIG_FILE_PATH:/docs-scraper/config.json \
            jqiue/docs-scraper:latest pipenv run ./docs_scraper config.json
```

::: tip Key for Scraper

To secure your MeiliSearch instance, you can create a new key with limited permissions for the scraper. Similar to search key above, this key should only have access to these actions: `["search","indexes.create","indexes.delete","settings.update","documents.add"]`

:::

## Options

### host

* Type: `string`

* Required: `true`

* Details:

  Provide the HTTP address of the MeiliSearch API.

### apiKey

* Type: `string`

* Required: `true`

* Details:

  API key generated by MeiliSearch.

### indexUid

* Type: `string`

* Required: `true`

* Details:

  Specify the index name used for searching.

### translations

* Type: `DocSearchTranslations`

* Details:

  Allows you to replace the default text in the DocSearch button and popup.

### hotKeys

* Type: `string[] | false`

* Default: `['ctrl+k', 's', '/']`

* Details:

  An array of hotkeys to trigger the search modal. When the value is `false`, the search modal cannot be triggered with any key.

### debounceDuration

* Type: `number | false`

* Default: `200`

* Details:

  The number of milliseconds that wait between keystrokes to determine whether a search should be performed, Setting the value here to `0` or `false` is logically equivalent.

### searchParams

* Type: `SearchParams`

* Required: `false`

* Details:

  Parameters of MeiliSearch API.

* Also see:
  * [Meilisearch API docs](https://www.meilisearch.com/docs/reference/api/search#search-parameters)

## Components

* SearchBox

---

---
url: /plugins/search/search.md
---
# search

Provide local search to your documentation site.

## Usage

```bash
npm i -D @vuepress/plugin-search@next
```

```ts title=".vuepress/config.ts"
import { searchPlugin } from '@vuepress/plugin-search'

export default {
  plugins: [
    searchPlugin({
      // options
    }),
  ],
}
```

## Local Search Index

This plugin will generate search index from your pages locally, and load the search index file when users enter your site. In other words, this is a lightweight built-in search which does not require any external requests.

However, when your site has a large number of pages, the size of search index file would be very large, which could slow down the page loading speed. In this case, we recommend you to use a more professional solution - [docsearch](./docsearch.md).

## Options

### locales

* Type: `Record<string, { placeholder?: string }>`

* Details:

  The text of the search box in different locales.

* Example:

```ts title=".vuepress/config.ts"
export default {
  plugins: [
    searchPlugin({
      locales: {
        '/': {
          placeholder: 'Search',
        },
        '/zh/': {
          placeholder: '搜索',
        },
      },
    }),
  ],
}
```

* Also see:
  * [Guide > I18n](https://vuejs.press/guide/i18n.html)

### hotKeys

* Type: `(string | KeyOptions)[]`

  @[code ts](@vuepress/helper/src/shared/key.ts)

* Default: `['s', '/']`

* Details:

  Specify the [event.key](http://keycode.info/) of the hotkeys.

  When hotkeys are pressed, the search box input will be focused.

  Set to an empty array to disable hotkeys.

### maxSuggestions

* Type: `number`

* Default: `5`

* Details:

  Specify the maximum number of search results.

### isSearchable

* Type: `(page: Page) => boolean`

* Default: `() => true`

* Details:

  A function to determine whether a page should be included in the search index.

  * Return `true` to include the page.
  * Return `false` to exclude the page.

* Example:

```ts title=".vuepress/config.ts"
export default {
  plugins: [
    searchPlugin({
      // exclude the homepage
      isSearchable: (page) => page.path !== '/',
    }),
  ],
}
```

### getExtraFields

* Type: `(page: Page) => string[]`

* Default: `() => []`

* Details:

  A function to add extra fields to the search index of a page.

  By default, this plugin will use page title and headers as the search index. This option could help you to add more searchable fields.

* Example:

```ts title=".vuepress/config.ts"
export default {
  plugins: [
    searchPlugin({
      // allow searching the `tags` frontmatter
      getExtraFields: (page) => page.frontmatter.tags ?? [],
    }),
  ],
}
```

## Styles

You can customize the style of the search box via CSS variables:

@[code css](@vuepress/plugin-search/src/client/styles/vars.css)

## Components

* SearchBox

---

---
url: /plugins/search/slimsearch.md
---
# slimsearch

A powerful client-side search plugin featuring custom indexing and full-text search support.

## Usage

```bash
npm i -D @vuepress/plugin-slimsearch@next
```

```ts title=".vuepress/config.ts"
import { slimsearchPlugin } from '@vuepress/plugin-slimsearch'

export default {
  plugins: [
    slimsearchPlugin({
      // options
    }),
  ],
}
```

## Search Index

Powered by [`slimsearch`](https://mister-hope.github.io/slimsearch/), this plugin provides ultra-fast search capabilities, even for large documentation sites.

By default, the plugin indexes only headings, article excerpts, and any custom fields you configure. If you wish to index the full content of your pages, set `indexContent: true` in the plugin options.

To exclude a specific page from the index, set `search: false` in its frontmatter. For programmatic filtering (e.g., excluding pages based on paths), use the [`filter` option](#filter).

## Custom Fields

Whether you are a theme developer or a user, it is common to attach extra metadata to pages via frontmatter or the `extendsPage` lifecycle hook. You can add this data to the search index using the `customFields` option.

The `customFields` option accepts an array of configuration objects. Each object consists of two parts:

* `getter`: A function that receives the `page` object and returns the value to be indexed. It can return a string, an array of strings, or `null`/`undefined` if the field is missing.
* `formatter`: A string or object defining how the item appears in search results. The placeholder `$content` is replaced by the value returned by the `getter`. If your site supports multiple languages, you can provide an object mapping locale paths to format strings.

::: tip Example: Adding Author to Index

Suppose you define an author in your frontmatter:

```md
---
author: Your name
---

Your Markdown content...
```

You can add this author information to the search index like this:

```ts title=".vuepress/config.ts"
import { slimsearchPlugin } from '@vuepress/plugin-slimsearch'

export default {
  plugins: [
    slimsearchPlugin({
      customFields: [
        {
          name: 'author',
          getter: (page) => page.frontmatter.author,
          formatter: 'Author: $content',
        },
      ],
    }),
  ],
}
```

:::

::: tip Example: Adding Update Time

Suppose you are using the `@vuepress/plugin-git` plugin and host Chinese docs under `/zh/` and English docs under `/`.

You can index the last updated time with locale-specific formatting:

```ts title=".vuepress/config.ts"
import { slimsearchPlugin } from '@vuepress/plugin-slimsearch'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  // Assuming the following locale config
  locales: {
    '/': {
      lang: 'en-US',
    },
    '/zh/': {
      lang: 'zh-CN',
    },
  },

  plugins: [
    slimsearchPlugin({
      customFields: [
        {
          name: 'updateTime',
          getter: (page) => page.data.git?.updateTime.toLocaleString(),
          formatter: {
            '/': 'Update time: $content',
            '/zh/': '更新时间：$content',
          },
        },
      ],
    }),
  ],
})
```

:::

## Options

### indexContent

* Type: `boolean`
* Default: `false`

Whether to enable full content indexing.

::: tip

By default, only page headings, excerpts, and custom fields are indexed. Set this to `true` only if you need to search the entire body text of your pages.

:::

### suggestion

* Type: `boolean`
* Default: `true`

Whether to display search suggestions while typing.

### customFields

* Type: `CustomFieldOptions[]`

  ```ts
  interface CustomFieldOptions {
    /**
     * Custom field getter
     */
    getter: (page: Page) => string[] | string | null | undefined

    /**
     * Display content format
     *
     * @description `$content` will be replaced by the value returned by `getter`
     *
     * @default `$content`
     */
    formatter?: Record<string, string> | string
  }
  ```

Configuration for indexing custom fields.

### hotKeys

* Type: `(KeyOptions | string)[]`

  @[code ts](@vuepress/helper/src/shared/key.ts)

* Default: `[{ key: "k", ctrl: true }, { key: "/", ctrl: true }]`

Specify the [event.key](http://keycode.info/) for hotkeys.

Pressing these keys will focus the search input. Set to an empty array `[]` to disable hotkeys.

### queryHistoryCount

* Type: `number`
* Default: `5`

The maximum number of search query history items to store. Set to `0` to disable.

### resultHistoryCount

* Type: `number`
* Default: `5`

The maximum number of matched result history items to store. Set to `0` to disable.

### searchDelay

* Type: `number`
* Default: `150`

The delay (in milliseconds) before starting a search after input.

::: note

Client-side searching on sites with massive content can be resource-intensive. You may need to increase this value to ensure the user has finished typing before the search triggers.

:::

### filter

* Type: `(page: Page) => boolean`
* Default: `() => true`

A function to filter which pages are included in the index.

### sortStrategy

* Type: `"max" | "total"`
* Default: `"max"`

The strategy used to sort search results.

When multiple results match, this determines the order. `max` places pages with the highest single-match score first. `total` places pages with the highest cumulative score first.

### worker

* Type: `string`
* Default: `slimsearch.worker.js`

The filename for the output Worker script.

### hotReload

* Type: `boolean`
* Default: Same as the `--debug` flag status

Whether to enable hot reloading of the search index in the development server.

::: note

This is disabled by default because rebuilding the index on every file change can severely impact performance on large sites.

:::

### indexOptions

* Type: `SlimSearchIndexOptions`

  ```ts
  interface SlimSearchIndexOptions {
    /**
     * Function to tokenize the index field item.
     */
    tokenize?: (text: string, fieldName?: string) => string[]
    /**
     * Function to process or normalize terms in the index field.
     */
    processTerm?: (term: string) => string[] | string | false | null | undefined
  }
  ```

Options passed to `slimsearch` during index creation.

### indexLocaleOptions

* Type: `Record<string, SlimSearchIndexOptions>`

Options for index creation per locale. The object keys should correspond to the locale path.

### locales

* Type: `SlimSearchLocaleConfig`

  ```ts
  interface SlimSearchLocaleData {
    /**
     * Search box placeholder
     */
    placeholder: string

    /**
     * Search text label
     */
    search: string

    /**
     * Clear search text label
     */
    clear: string

    /**
     * Remove current item label
     */
    remove: string

    /**
     * Searching status text
     */
    searching: string

    /**
     * Cancel text label
     */
    cancel: string

    /**
     * Default title
     */
    defaultTitle: string

    /**
     * Select hint
     */
    select: string

    /**
     * Navigate hint
     */
    navigate: string

    /**
     * Autocomplete hint
     */
    autocomplete: string

    /**
     * Close hint
     */
    exit: string

    /**
     * Loading hint
     */
    loading: string

    /**
     * Search query history title
     */
    queryHistory: string

    /**
     * Search result history title
     */
    resultHistory: string

    /**
     * Empty history hint
     */
    emptyHistory: string

    /**
     * Empty result hint
     */
    emptyResult: string
  }

  interface SlimSearchLocaleConfig {
    [localePath: string]: SlimSearchLocaleData
  }
  ```

Multilingual configuration for the search UI.

::: details Built-in Supported Languages

* **Simplified Chinese** (zh-CN)
* **Traditional Chinese** (zh-TW)
* **English (United States)** (en-US)
* **German** (de-DE)
* **Russian** (ru-RU)
* **Ukrainian** (uk-UA)
* **Vietnamese** (vi-VN)
* **Portuguese** (pt)
* **Polish** (pl-PL)
* **French** (fr-FR)
* **Spanish** (es-ES)
* **Slovak** (sk-SK)
* **Japanese** (ja-JP)
* **Turkish** (tr-TR)
* **Korean** (ko-KR)
* **Finnish** (fi-FI)
* **Indonesian** (id-ID)
* **Dutch** (nl-NL)

:::

## Frontmatter

### search

* Type: `boolean`
* Default: `true`

Whether to include this page in the search index.

## Advanced

### Customize Index Generation

You can customize the index generation process using `indexOptions` and `indexLocaleOptions`. This allows you to fine-tune indexing results globally or for specific locales.

We use the `Intl.Segmenter` API for tokenization (word-splitting) by default. While this works well for most languages, you might want to provide a custom `tokenize` function for specific languages to improve search accuracy.

### Using with API

To access the search functionality programmatically, import the `createSearchWorker` function from `@vuepress/plugin-slimsearch/client`:

```ts
import { createSearchWorker } from '@vuepress/plugin-slimsearch/client'
import { defineClientConfig } from 'vuepress/client'

const { all, suggest, search, terminate } = createSearchWorker()

// Suggest terms based on input
suggest('key').then((suggestions) => {
  // Handle search suggestions
})

// Search for content
search('keyword').then((results) => {
  // Handle search results
})

// Get both suggestions and results
all('key').then(({ suggestions, results }) => {
  // Handle suggestions and results
})

// Terminate the worker when no longer needed
terminate()
```

### Limitations in DevServer

The search service runs in a Web Worker. In development mode, we cannot bundle the worker file like in production.

To load search indexes in the dev server, we use a modern Service Worker with `type: "module"`. If you want to test search functionality locally, please ensure your browser supports ES Module Workers (see [CanIUse](https://caniuse.com/mdn-api_worker_worker_ecmascript_modules)).

For performance reasons, adding, editing, or deleting Markdown content will **not** trigger a search index update in development mode by default. If you are refining search results, you can enable hot reloading by setting `hotReload: true`.

### Comparing with Server-Search

Client-side search offers benefits like zero backend dependencies and ease of integration, but it also comes with trade-offs.

::: warning Disadvantages

1. **Build Time:** Indexes are generated during the build, which increases deployment time and the size of the output bundle.
2. **Bandwidth:** Users must download the search index before they can search. The more content you have, the larger the index file, which consumes more bandwidth.
3. **Latency:** Users must wait for the index to be downloaded and parsed locally. This initial load can be slower than a direct API request to a server-side search engine.
4. **Device Performance:** Since the search logic runs on the user's device, speed is dependent on their hardware capabilities.

:::

If you are building a very large site, it is recommended to use a dedicated search service provider like [Algolia](https://www.algolia.com/), or host an open-source search crawler on your own server. This approach is more scalable as users only send search queries over the network rather than downloading the entire dataset.

Notably, [DocSearch](https://docsearch.algolia.com/) is a free service by Algolia for open-source projects. If you maintain open-source documentation or a technical blog, you can [apply for it](https://docsearch.algolia.com/apply/) and use the [`@vuepress/plugin-docsearch`](./docsearch.md) plugin.

## Client Config

### defineSearchConfig

Customize [search options](https://mister-hope.github.io/slimsearch/interfaces/SearchOptions.html). Accepts a plain object, a ref, or a getter function.

Since searching is performed inside a Web Worker, you cannot pass function-typed options directly to `slimsearch`.

However, to provide more accurate queries, suggestions, and results, we expose `querySplitter`, `suggestionsFilter`, and `resultsFilter` options in the client config. You can set these for specific languages or globally:

```ts
interface SearchLocaleOptions extends Omit<
  SearchOptions,
  'boostDocument' | 'fields' | 'filter' | 'processTerm' | 'tokenize'
> {
  /** A function to split words */
  querySplitter?: (query: string) => Promise<string[]>

  /** A function to filter suggestions */
  suggestionsFilter?: (
    suggestions: string[],
    query: string,
    locale: string,
    pageData: PageData,
  ) => string[]

  /** A function to filter search results */
  resultsFilter?: (
    results: SearchResult[],
    query: string,
    locale: string,
    pageData: PageData,
  ) => SearchResult[]
}

interface SearchOptions extends SearchLocaleOptions {
  /** Setting different options per locale */
  locales?: Record<string, SearchLocaleOptions>
}

export const defineSearchConfig: (
  options: MaybeRefOrGetter<SearchOptions>,
) => void
```

```ts title=".vuepress/client.ts"
import { defineSearchConfig } from '@vuepress/plugin-slimsearch/client'

defineSearchConfig({
  // global search options here

  locales: {
    '/zh/': {
      // set different options for Chinese
    },
  },
})
```

## Components

* SearchBox

---

---
url: /plugins/seo/index.md
---
# SEO Plugins

---

---
url: /plugins/seo/seo/index.md
---
# seo

## Usage

```bash
npm i -D @vuepress/plugin-seo@next
```

```ts title=".vuepress/config.ts"
import { seoPlugin } from '@vuepress/plugin-seo'

export default {
  plugins: [
    seoPlugin({
      // options
    }),
  ],
}
```

---

---
url: /plugins/seo/seo/config.md
---
# Config

## hostname

* Type: `string`
* Required: Yes
* Details:

  Deploy hostname.

## author

* Type: `Author`

  ```ts
  type AuthorName = string

  interface AuthorInfo {
    /**
     * Author name
     */
    name: string

    /**
     * Author website
     */
    url?: string

    /**
     * Author email
     */
    email?: string
  }

  type Author = AuthorInfo | AuthorInfo[] | AuthorName | AuthorName[]
  ```

* Details:

  Default author.

## autoDescription

* Type: `boolean`
* Default: `true`
* Details:

  Whether generate description automatically

## canonical

* Type: `string | ((page: Page) => string | null)`
* Details:

  Canonical link

## fallBackImage

* Type: `string`
* Details:

  Fallback Image link when no image are found

## restrictions

* Type: `string`
* Details:

  The age rating of the content, the format is `[int]+`, such as `"13+"`.

## twitterID

* Type: `string`
* Details:

  Fill in your twitter username.

## isArticle

* Type: `(page: Page) => boolean`
* Details:

  Use this option to judge whether the page is an article.

## ogp

* Type:

  ```ts
  function ogp(
    /** OGP info inferred by plugin */
    ogpInfo: SeoContent,
    /** Page Object */
    page: Page,
    /** VuePress App */
    app: App,
  ): SeoContent
  ```

* Details:

  Custom OPG Generator.

  You can use this options to edit OGP tags.

## jsonLd

* Type:

  ```ts
  function jsonLd(
    /** JSON-LD Object inferred by plugin */
    jsonLD: ArticleSchema | BlogPostingSchema | WebPageSchema,
    /** Page Object */
    page: Page,
    /** VuePress App */
    app: App,
  ): ArticleSchema | BlogPostingSchema | WebPageSchema
  ```

* Details:

  Custom JSON-LD Generator.

  You can use this options to edit JSON-LD properties.

## customHead

* Type:

  ```ts
  function customHead(
    /** Head tag config */
    head: HeadConfig[],
    /** Page Object */
    page: Page,
    /** VuePress App */
    app: App,
  ): void
  ```

* Details:

  You can use this options to edit tags injected to `<head>`.

---

---
url: /plugins/seo/seo/guide.md
---
# Guide

This plugin will make your site fully support [Open Content Protocol OGP](https://ogp.me/) and [JSON-LD 1.1](https://www.w3.org/TR/json-ld-api/) to enhance the SEO of the site.

## Out of Box

The plugin works out of the box. Without any config, it will extract information from the page content as much as possible to complete the necessary tags required by OGP and JSON-LD.

By default, the plugin will read the site config and page frontmatter to automatically generate tags as much as possible. Such as site name, page title, page type, writing date, last update date, and article tags are all automatically generated.

The following are the `<meta>` tags and their values that will be injected into `<head>` by default:

### Default OGP Generation

The following are the `<meta>` tags and their value injected into `<head>` by default to satisfy OGP:

|        Meta Name         |                                                          Value                                                          |
| :----------------------: | :---------------------------------------------------------------------------------------------------------------------: |
|         `og:url`         |                                               `options.hostname` + `path`                                               |
|      `og:site_name`      |                                                   `siteConfig.title`                                                    |
|        `og:title`        |                                                      `page.title`                                                       |
|     `og:description`     |         `page.frontmatter.description` || auto generated (when `autoDescription` is `true` in plugin options)         |
|        `og:type`         |                                                       `"article"`                                                       |
|        `og:image`        | `page.frontmatter.banner` || `page.frontmatter.cover` || first image in page || `fallbackImage` in plugin options |
|    `og:updated_time`     |                                                 `page.git.updatedTime`                                                  |
|       `og:locale`        |                                                       `page.lang`                                                       |
|  `og:locale:alternate`   |                                          Other languages in `siteData.locales`                                          |
|      `twitter:card`      |                                `"summary_large_image"` (only available when image found)                                |
|   `twitter:image:alt`    |                                     `page.title` (only available when image found)                                      |
|     `article:author`     |                                     `page.frontmatter.author` || `options.author`                                     |
|      `article:tag`       |                                   `page.frontmatter.tags` || `page.frontmatter.tag`                                   |
| `article:published_time` |                                   `page.frontmatter.date` || `page.git.createdTime`                                   |
| `article:modified_time`  |                                                 `page.git.updatedTime`                                                  |

### Default JSON-LD Generation

|  Property Name  |                                                 Value                                                 |
| :-------------: | :---------------------------------------------------------------------------------------------------: |
|   `@context`    |                                        `"https://schema.org"`                                         |
|     `@type`     |                                            `"NewsArticle"`                                            |
|   `headline`    |                                             `page.title`                                              |
|     `image`     | image in page || `options.hostname` + `page.frontmatter.image` || `siteFavIcon` in plugin options |
| `datePublished` |                          `page.frontmatter.date` || `page.git.createdTime`                          |
| `dateModified`  |                                        `page.git.updatedTime`                                         |
|    `author`     |                            `page.frontmatter.author` || `options.author`                            |

## Setting Tags Directly

You can configure the `head` option in the page's frontmatter to add specific tags to the page `<head>` to enhance SEO.
For example:

```md
---
head:
  - - meta
    - name: keywords
      content: SEO plugin
---
```

Will automatically inject `<meta name="keywords" content="SEO plugin" />`.

## Customize Generation

The plugin also gives you full control over the build logic.

### Page Type

For most pages, there are basically only two types: articles and website, so the plugin provides the `isArticle` option to allow you to provide logic for identifying articles.

The option accepts a function in the format `(page: Page) => boolean`, by default all non-home pages generated from Markdown files are treated as articles.

::: tip

If a page does fit into the "unpopular" genre like books, music, etc., you can handle them by setting the three options below.

:::

### OGP

You can use the plugin options `ogp` to pass in a function to modify the default OGP object to your needs and return it.

```ts
function ogp(
  /** OGP Object inferred by plugin */
  ogpInfo: SeoContent,
  /** Page Object */
  page: Page,
  /** VuePress App */
  app: App,
): SeoContent
```

For detailed parameter structure, see [Config](./config.md).

For example, if you are using a third-party theme and set a `banner` in frontmatter for each article according to the theme requirements, then you can pass in the following `ogp`:

```ts
seoPlugin({
  ogp: (ogp, page) => ({
    ...ogp,
    'og:image': page.frontmatter.banner || ogp['og:image'],
  }),
})
```

### JSON-LD

Like OGP, you can use the plugin options `jsonLd` to pass in a function to modify the default JSON-LD object to your needs and return it.

```ts
function jsonLd(
  /** JSON-LD Object inferred by plugin */
  jsonLD: ArticleSchema | BlogPostingSchema | WebPageSchema,
  /** Page Object */
  page: Page,
  /** VuePress App */
  app: App,
): ArticleSchema | BlogPostingSchema | WebPageSchema
```

## Canonical Link

If you are deploying your content to different sites, or same content under different URLs, you may need to set `canonical` option to provide a "Canonical Link" for your page. You can either set a string which will be appended before page route link, or adding a custom function `(page: Page) => string | null` to return a canonical link if necessary.

::: tip Example

If your sites are deployed under docs directory in `example.com`, but available in:

* `http://example.com/docs/xxx`
* `https://example.com/docs/xxx`
* `http://www.example.com/docs/xxx`
* `https://www.example.com/docs/xxx` (primary)

To let search engine results always be the primary choice, you may need to set `canonical` to `https://www.example.com/docs/`, so that search engine will know that the fourth URL is preferred to be indexed.

:::

### Customize head Tags

Sometimes you may need to fit other protocols or provide the corresponding SEO tags in the format provided by other search engines. In this case, you can use the `customHead` option, whose type is:

```ts
function customHead(
  /** Head tag config */
  head: HeadConfig[],
  /** Page Object */
  page: Page,
  /** VuePress App */
  app: App,
): void
```

You should modify the `head` array in this function directly.

## SEO Introduction

**S**earch **e**ngine **optimization** (SEO) is the process of improving the quality and quantity of site traffic to a site or a web page from search engines. SEO targets unpaid traffic (known as "natural" or "organic" results) rather than direct traffic or paid traffic. Unpaid traffic may originate from different kinds of searches, including image search, video search, academic search, news search, and industry-specific vertical search engines.

As an internet marketing strategy, SEO considers how search engines work, the computer-programmed algorithms that dictate search engine behavior, what people search for, the actual search terms or keywords typed into search engines, and which search engines are preferred by their targeted audience. SEO is performed because a site will receive more visitors from a search engine when sites rank higher on the search engine results page (SERP). These visitors can then potentially be converted into customers.

## Related Documents

* [Open Content Protocol OGP](https://ogp.me/) (**O**pen **G**raph **Pr**otocol)

  This plugin perfectly supports this protocol and will automatically generate `<meta>` tags that conform to the protocol.

* [JSON-LD 1.1](https://www.w3.org/TR/json-ld-api/)

  This plugin will generate "NewsArticle" scheme for article pages.

* [RDFa 1.1](https://www.w3.org/TR/rdfa-primer/)

  RDFa mainly marks HTML structure. This is what the plugin cannot support. vuepress-theme-hope uses this feature to pass Google's rich media structure test. You can consider using it.

* [Schema.Org](https://schema.org/)

  Schema definition site for structural markup

## Related Tools

You can use [Google Rich Media Structure Test Tool](https://search.google.com/test/rich-results) to test this site.

---

---
url: /plugins/seo/sitemap/index.md
---
# sitemap

## Usage

```bash
npm i -D @vuepress/plugin-sitemap@next
```

```ts title=".vuepress/config.ts"
import { sitemapPlugin } from '@vuepress/plugin-sitemap'

export default {
  plugins: [
    sitemapPlugin({
      // options
    }),
  ],
}
```

---

---
url: /plugins/seo/sitemap/config.md
---
# Config

## hostname

* Type: `string`

* Required: Yes

* Details:

  The domain name where the current site is deployed, the plugin needs this option to work.

## extraUrls

* Type: `string[]`

* Details:

  Extra link to be included.

  If you have some links not including in VuePress Router (normally in public directory or generated by other tools directly), you may need this option.

* Example: `['/about.html', '/api/']`

## excludePaths

* Type: `string[]`

* Default: `['/404.html']`

* Details:

  Urls excluding from sitemap, starting with absolute path.

  By default, all the urls generated by VuePress (excluding 404 page) will be added into sitemap.

## devServer

* Type: `boolean`
* Default: `false`
* Details:

  Whether enabled in devServer.

::: tip

For performance reasons, we do not provide hot reload. Reboot your devServer to sync your changes.

:::

## devHostname

* Type: `string`
* Default: `"http://localhost:${port}"`
* Details:

  Hostname to use in devServer

## sitemapFilename

* Type: `string`
* Default value: `"sitemap.xml"`
* Details:

  The output filename, relative to output directory.

## sitemapXSLFilename

* Type: `string`
* Default value: `"sitemap.xsl"`
* Details:

  Output xsl filename, relative to dest folder.

## sitemapXSLTemplate

* Type: `string`
* Default value: `"@vuepress/plugin-sitemap/templates/sitemap.xsl"`
* Details:

  XSL content used as template.

## changefreq

* Type: `"always" | "hourly" | "daily" | "weekly" |"monthly" | "yearly" | "never"`
* Default value: `"daily"`
* Details:

  Page default update frequency, will be overridden by [sitemap.changefreq](./frontmatter.md#sitemap-changefreq) in Frontmatter.

## priority

* Type: `number`

* Default: `0.5`

* Details:

  Page priority, from `0` to `1`.

## modifyTimeGetter

* Type: `(page: Page, app: App) => string`

* Details:

  Last modify time getter. By default, the plugin will use the timestamp generated by git plugin.

---

---
url: /plugins/seo/sitemap/frontmatter.md
---
# Frontmatter

## sitemap

* Type: `SitemapFrontmatterOptions | false`
* Details:

  `false` means exclude the page from sitemap.

### sitemap.changefreq

* Type: `"always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never"`
* Default: `"daily"`
* Details:

  Page default update frequency. This will override [changefreq](./config.md#changefreq) in Plugin Options.

### sitemap.priority

* Type: `number`
* Default: `0.5`
* Details:

  Page priority, range from `0` to `1`.

---

---
url: /plugins/seo/sitemap/guide.md
---
# Guide

This plugin will automatically generate a Sitemap for your site. To let this plugin work, you need to pass the deployed domain name to the `hostname` option of the plugin. If you want to preview in devServer, set `devServer` options.

The plugin will automatically generate the last update time of the page based on the Git timestamp of the page, and will also declare the alternative links of the page in other languages according to the locales' config.

## Control Sitemap Link

By default, all site links except 404 page will be added to the Sitemap.

To add other pages to the Sitemap outside the VuePress project page, please turn them into an array and pass to the `extraUrls` plugin option.

If you don't want certain pages to appear in the sitemap, you can turn their paths into an array and pass to the `excludePaths` plugin option, or set `sitemap` to `false` in the frontmatter of the corresponding page.

## Output Location

You can also control the output link through the `sitemapFilename` option of the plugin, the link is relative to output directory. By default, the plugin will use `sitemap.xml`.

## Change Frequency

The default update cycle of the page is `daily` (every day). To modify the entire page cycle, please set `changefreq` in the plugin options. You can also set `sitemap.changefreq` in the frontmatter of the page. Note that page has a higher priority.

The legal frequencies are:

* `"always"`
* `"hourly"`
* `"daily"`
* `"weekly"`
* `"monthly"`
* `"yearly"`
* `"never"`

## Priority

You can set `priority` in the plugin to provide a default value. At the same time you can set the priority for each page through `sitemap.priority` in frontmatter. Acceptable values are floating point numbers from `0` to `1`.

## Modify Time

You can use option `modifyTimeGetter` to return a time in ISO string format, which is generated by the Git plugin by default.

The following is an example based on the last modification time of a file.

```ts
// Based on file last modified time
;({
  modifyTimeGetter: (page, app) =>
    fs.statSync(app.dir.source(page.filePathRelative)).mtime.toISOString(),
})
```

## Sitemap Intro

Sitemaps provide SEO (Search Engine Optimization):

* Provide search engine spiders with links of the entire site;
* Provide some links for search engine spiders to dynamic pages or pages that are difficult to reach by other methods;
* If a visitor attempts to access a URL that does not exist within the site's domain, the visitor will be directed to a "file not found" error page, and the sitemap can be used as a navigation page.

A sitemap enhances SEO by making all pages findable.

Most search engines only follow a limited number of links within a page, so when the site is very large, a sitemap becomes essential to make everything on the site accessible to search engines and visitors.

Sitemaps is a protocol for site administrators to publish pages that can be crawled on a site to search engine spiders. The content of sitemap files must follow the definition in XML format. Each URL can contain the update period and last update time, the priority of the URL across the site. This allows search engines to crawl site content better and more efficiently.

::: warning Together with robots.txt

Sitemap is basically used by search engines, when using this plugin, you'd better ensure that you have a valid `robots.txt` in the `.vuepress/public` directory to allow search engines spiders to visit your site. The simplest robots.txt is as follows (allow all search engines to access all paths)

```txt
User-agent: *

Allow: /
```

:::

---

---
url: /plugins/tools/index.md
---
# Tool Plugins

---

---
url: /plugins/tools/auto-frontmatter.md
---
# auto-frontmatter

Automatically insert frontmatter at the beginning of markdown files.

When VuePress starts, locate markdown files based on **matching rules**, use the `handle(data [,context])` function to generate frontmatter, and then add the frontmatter to the beginning of the markdown file.

::: tip The plugin only processes markdown files under the [source directory](https://v2.vuepress.vuejs.org/guide/getting-started.html#directory-structure) that meet the [config.pagePatterns](https://v2.vuepress.vuejs.org/reference/config.html#pagepatterns) rules.
:::

## Usage

```bash
npm i -D @vuepress/plugin-auto-frontmatter@next
```

```ts title=".vuepress/config.ts"
import { autoFrontmatterPlugin } from '@vuepress/plugin-auto-frontmatter'

export default {
  plugins: [
    autoFrontmatterPlugin({
      // options
    }),
  ],
}
```

## Options

```ts
export type AutoFrontmatterData = Record<string, unknown>

/**
 * The context of the markdown file
 */
export interface AutoFrontmatterContext {
  /**
   * The absolute path to the file
   */
  filepath: string
  /**
   * The relative path to the file
   */
  relativePath: string
  /**
   * The markdown content of the file
   */
  content: string
}

/**
 * The function to handle the frontmatter data
 */
export type AutoFrontmatterHandle<
  D extends AutoFrontmatterData = AutoFrontmatterData,
> = (data: D, context: AutoFrontmatterContext) => D | Promise<D>

export interface AutoFrontmatterRule {
  /**
   * File filter, matches the relative path of the file
   *
   * Uses [picomatch](https://github.com/micromatch/picomatch) for pattern matching
   */
  filter: string[] | string | ((filepath: string) => boolean)
  /**
   * The function to handle the frontmatter data
   */
  handle: AutoFrontmatterHandle
}

export type AutoFrontmatterPluginOptions =
  | AutoFrontmatterHandle
  | AutoFrontmatterRule
  | AutoFrontmatterRule[]
```

### Process all markdown files

Pass directly to the `AutoFrontmatterHandle` function, indicating processing for all markdown files:

```ts title=".vuepress/config.ts"
import path from 'node:path'
import { autoFrontmatterPlugin } from '@vuepress/plugin-auto-frontmatter'

export default {
  plugins: [
    autoFrontmatterPlugin((data, context) => {
      // automatically add title
      data.title = data.title || path.basename(context.relativePath, '.md')
      return data
    }),
  ],
}
```

### Configuring General Rules

Use `AutoFrontmatterRule` to configure filter rules and handle functions, matching the relative paths of files.

The `filter` parameter accepts one or more glob strings, using [picomatch](https://github.com/micromatch/picomatch) for pattern matching:

```ts title=".vuepress/config.ts"
import path from 'node:path'
import { autoFrontmatterPlugin } from '@vuepress/plugin-auto-frontmatter'

export default {
  plugins: [
    autoFrontmatterPlugin({
      filter: ['posts/**/*.md'], // [!code hl]
      handle: (data, context) => {
        data.title = data.title || path.basename(context.relativePath, '.md')
        return data
      },
    }),
  ],
}
```

If you need to exclude files, you can pass a glob string starting with `!` to the `filter`:

```ts title=".vuepress/config.ts"
import path from 'node:path'
import { autoFrontmatterPlugin } from '@vuepress/plugin-auto-frontmatter'

export default {
  plugins: [
    autoFrontmatterPlugin({
      // Match all files under `posts`, but exclude the `posts/foo` directory
      filter: ['posts/**/*.md', '!posts/foo'], // [!code hl]
      handle: (data, context) => {
        data.title = data.title || path.basename(context.relativePath, '.md')
        return data
      },
    }),
  ],
}
```

`filter` can also accept a function, where returning `true` indicates a match and returning `false` indicates no match:

```ts title=".vuepress/config.ts"
import path from 'node:path'
import { autoFrontmatterPlugin } from '@vuepress/plugin-auto-frontmatter'

export default {
  plugins: [
    autoFrontmatterPlugin({
      // 匹配 posts 下的所有文件
      filter: (relativePath) => relativePath.startsWith('posts'), // [!code hl]
      handle: (data, context) => {
        data.title = data.title || path.basename(context.relativePath, '.md')
        return data
      },
    }),
  ],
}
```

### Multiple General Rules

You can configure multiple filter rules and handle functions, allowing different processing for files in different directories:

```ts title=".vuepress/config.ts"
import path from 'node:path'
import { autoFrontmatterPlugin } from '@vuepress/plugin-auto-frontmatter'

export default {
  plugins: [
    autoFrontmatterPlugin([
      {
        // Match all files under `posts`
        filter: ['posts/**/*.md'], // [!code hl]
        handle: (data, context) => {
          data.title = data.title || path.basename(context.relativePath, '.md')
          return data
        },
      },
      {
        // Match all files under `others`
        filter: ['others/**/*.md'], // [!code hl]
        handle: (data, context) => {
          data.title = data.title || path.basename(context.relativePath, '.md')
          data.foo = 'foo'
          return data
        },
      },
    ]),
  ],
}
```

## Helper Functions

The plugin provides some built-in helper functions that can be used to add new fields to the `frontmatter`:

### `addTitleByFilename(data, context)`

```ts
function addTitleByFilename(
  data: AutoFrontmatterData,
  context: AutoFrontmatterContext,
): void
```

Add title based on filename:

```ts title=".vuepress/config.ts"
import path from 'node:path'
import {
  addTitleByFilename,
  autoFrontmatterPlugin,
} from '@vuepress/plugin-auto-frontmatter'

export default {
  plugins: [
    autoFrontmatterPlugin((data, context) => {
      addTitleByFilename(data, context) // [!code ++]
      return data
    }),
  ],
}
```

**Output**:

```md title="docs/guide.md"
---
title: guide
---
```

### `addCreateDate(data, context, options)`

```ts
interface AddCreateDateOptions {
  /**
   * The frontmatter key name used when adding time
   * @default "date"
   */
  key?: string

  /**
   * Date format used when adding time
   * @default "date"
   */
  format?: 'date' | 'full' | 'time'
}

function addCreateDate(
  data: AutoFrontmatterData,
  context: AutoFrontmatterContext,
  options?: AddCreateDateOptions,
): void
```

Add date based on file creation time. This function will first attempt to read the creation time from `git` records, and if unavailable, it will use `fs.stats` to obtain the creation time.

```ts title=".vuepress/config.ts"
import path from 'node:path'
import {
  addCreateDate,
  autoFrontmatterPlugin,
} from '@vuepress/plugin-auto-frontmatter'

export default {
  plugins: [
    autoFrontmatterPlugin((data, context) => {
      addCreateDate(data, context, { format: 'full' }) // [!code ++]
      return data
    }),
  ],
}
```

**Output**:

```md title="docs/guide.md"
---
date: 2025-01-01 11:11:11
---
```

### `addShortPermalink(data, options)`

```ts
interface AddShortPermalinkOptions {
  /**
   * Use `nanoid` to generate a random character length
   * @default 8
   */
  length?: number
  /**
   * add a prefix
   * @default `/`
   */
  prefix?: string
  /**
   * add a suffix
   * @default `.html`
   */
  suffix?: string
}

function addShortPermalink(
  data: AutoFrontmatterData,
  options: AddShortPermalinkOptions,
): void
```

Using `nanoid` to generate random characters as permalink:

```ts title=".vuepress/config.ts"
import path from 'node:path'
import {
  addShortPermalink,
  autoFrontmatterPlugin,
} from '@vuepress/plugin-auto-frontmatter'

export default {
  plugins: [
    autoFrontmatterPlugin((data, context) => {
      addShortPermalink(data, { length: 8, prefix: '/', suffix: '.html' }) // [!code ++]
      return data
    }),
  ],
}
```

**Output**:

```md title="docs/guide.md"
---
permalink: /abcd1234.html
---
```

---

---
url: /plugins/tools/cache.md
---
# cache

This plugin is used to solve the issue of long startup times in VuePress.

By caching the `markdown render` during the initial startup of the VuePress development server, the plugin skips unnecessary `markdown render` on subsequent startups, thus speeding up the startup process.

## Usage

```bash
npm i -D @vuepress/plugin-cache@next
```

::: tip Using it as last plugin

It is recommended to place `cachePlugin` as the last item in the `plugins` configuration, as this can ensure maximum utilization of caching.

:::

```ts title=".vuepress/config.ts"
import { cachePlugin } from '@vuepress/plugin-cache'

export default {
  plugins: [
    // ... other plugins

    // using as the last plugin
    cachePlugin({
      // options
    }),
  ],
}
```

## Options

### type

* Type: `'memory'` | `'filesystem'`

* Default: `'memory'`

* Details:

  Cache Types

  * `'memory'` is for memory cache, using memory cache can achieve optimal optimization effects, but as the project scales up, it occupies more memory, suitable for projects with fewer pages.
  * `'filesystem'` is for file system cache, for complex projects with many pages, file cache is recommended.

### enableInCi

* Type: `boolean`

* Default: `false`

* Details:

  Whether to enable the cache in CI environment.

  In most cases, the cache plugin could slow down the speed in ci.

---

---
url: /plugins/tools/google-tag-manager.md
---
# google-tag-manager

Integrate [Google Tag Manager](https://tagmanager.google.com/) into VuePress.

This plugin will import [Google Tag Manager](https://developers.google.com/tag-platform/tag-manager).

## Usage

```bash
npm i -D @vuepress/plugin-google-tag-manager@next
```

```ts title=".vuepress/config.ts"
import { googleTagManagerPlugin } from '@vuepress/plugin-google-tag-manager'

export default {
  plugins: [
    googleTagManagerPlugin({
      // options
    }),
  ],
}
```

::: tip Working with Javascript Disabled

If you want Google Tag Manager to work properly when javascript is disabled, you should add the following content to the body part of build template via `templateBuild`:

```html
<!-- Google Tag Manager (noscript) -->
<noscript
  ><iframe
    src="https://www.googletagmanager.com/ns.html?id=GTM-ABCDEFGH"
    height="0"
    width="0"
    style="display:none;visibility:hidden"
  ></iframe
></noscript>
<!-- End Google Tag Manager (noscript) -->
```

:::

## Options

### id

* Type: `string`

* Details:

  The container ID of Google Tag Manager 4, which should start with `'GTM-'`.

  You add your container and find its ID [here](https://tagmanager.google.com/#/home).

* Example:

```ts title=".vuepress/config.ts"
export default {
  plugins: [
    googleTagManagerPlugin({
      id: 'GTM-XXXXXXXXXX',
    }),
  ],
}
```

---

---
url: /plugins/tools/redirect.md
---
# redirect

This plugin can automatically handle redirects for your site.

## Usage

```bash
npm i -D @vuepress/plugin-redirect@next
```

```ts title=".vuepress/config.ts"
import { redirectPlugin } from '@vuepress/plugin-redirect'

export default {
  plugins: [
    redirectPlugin({
      // options
    }),
  ],
}
```

### Control Page Redirection

If you change the address of an existing page, you can use the `redirectFrom` option in Frontmatter to redirect to the address of this page, which ensures that users are redirected to the new address when they visit the old link.

If you need to redirect an existing page to a new page, you can use the `redirectTo` option in Frontmatter to set the address to redirect to. This way the page will redirect to the new address when accessed.

You can also set `config` with a redirect map in plugin options, see [config](#config) for more details.

### Auto Locales

The plugin can automatically redirect non-multilingual links to the multilingual pages the user needs based on the user's language preference.

To achieve this, you need to leave the default language directory (`/`) blank and set `autoLocale: true` in plugin options. The plugin will automatically redirect to the correct page according to the user's language.

I.E.: you need to set the following directory structure:

```
.
├── en
│   ├── ...
│   ├── page.md
│   └── README.md
├── zh
│   ├── ...
│   ├── page.md
│   └── README.md
└── other_languages
    ├── ...
    ├── page.md
    └── README.md
```

And set `locales` in theme options with:

```js
export default {
  locales: {
    '/en/': {
      lang: 'en-US',
      // ...
    },
    '/zh/': {
      lang: 'zh-CN',
      // ...
    },
    // other languages
  },
  // ...
}
```

So when a user accesses `/` or `/page.html`, they are automatically redirected to `/en/` `/en/page.html` and `/en/` `/en/page.html` based on current browser language.

::: tip Customizing fallback behavior

Sometimes, users may add more than one language to the system settings. By default, when a site supports a preferred language, but the page not exists for the preferred language, the plugin attempts to match the alternate language set by the user.

If you don't need to fall back to the user's alternate language, but directly match the user's preferred language, set `localeFallback: false` in the plugin options.

:::

::: tip Customizing missing behavior

Sometimes, when a user visits a page, the document does not yet contain the language version the user needs (a common case is that the current page has not been localized in the relevant language), so the plugin needs to perform a default action, which you can customize by `defaultBehavior` in the plugin options:

* `"defaultLocale"`: Redirect to default language or first available language page (default behavior)
* `"homepage"`: redirect to the home page in the current language (only available if the document contains the user's language)
* `"404"`: Redirect to page 404 in current language (only available if the document contains the user's language)

:::

::: tip Customizing default locale path

You can customize the default locale path by setting `defaultLocale` in the plugin options. By default, the plugin uses the first locale key in `locales` as the default language.

:::

### Automatically switch languages

The plugin supports automatically switching the link to the multilingual page that the user needs according to the user's language preference when opening a multilingual document. In order to achieve this, you need to set `switchLocale` in the plugin options, which can be the following two values:

* `direct`: switch directly to the user language preference page without asking
* `modal`: When the user's language preference is different from the current page language, show a modal asking whether to switch language

### Customizing Locale Settings

By default, the plugin generates a locale setting by reading `locale path` and `lang` from the site's `locales` option. Sometimes, you may want multiple languages to hit the same path, in which case you should set `localeConfig` in plugin options.

For example, you might want all English users to match to `/en/` and Chinese Traditional users to `/zh/`, then you can set:

```js
redirect({
  localeConfig: {
    '/en/': ['en-US', 'en-UK', 'en'],
    '/zh/': ['zh-CN', 'zh-TW', 'zh'],
  },
})
```

### Redirecting Sites

Sometimes you may change `base` or use new domain for your site, so you may want the original site automatically redirects to the new one.

To solve this, the plugin provide `vp-redirect` cli.

```plain
Usage: vp-redirect [options] <source> [output]

Generate redirect site for current VuePress project

Arguments:
  source                 Source directory of VuePress project
  output                 Output folder (default: .vuepress/redirect relative to source folder)

Options:
  --hostname <hostname>  Hostname to redirect to (E.g.: https://new.example.com/) (default: "/")
  -c, --config [config]  Set path to config file
  --cache [cache]        Set the directory of the cache files
  --temp [temp]          Set the directory of the temporary files
  --clean-cache          Clean the cache files before generation
  --clean-temp           Clean the temporary files before generation
  -V, --version          output the version number
  -h, --help             display help for command
```

You need to pass in VuePress project source dir and also set the `hostname` option. The redirect helper cli will initialize your VuePress project to get pages, then generate and output the redirect html files to the output directory.

By default, the plugin will output to `.vuepress/redirect` directory under source directory. And you should upload it to your original site to provide redirection.

## Options

### config

* Type: `Record<string, string> | ((app: App) => Record<string, string>)`
* Details: Redirect map.
* Example:

  When base is set to `/base/`:

  * redirect `/base/foo.html` to `/base/bar.html`
  * `/base/baz.html` to `https://example.com/qux.html`.

  ```js
  redirect({
    config: {
      '/foo.html': '/bar.html',
      '/baz.html': 'https://example.com/qux.html',
    },
  })
  ```

  Redirect post folder to posts folder:

  ```js
  redirect({
    hostname: 'https://example.com',
    config: (app) =>
      Object.fromEntries(
        app.pages
          .filter(({ path }) => path.startsWith('/posts/'))
          .map(({ path }) => [path.replace(/^\/posts\//, '/post/'), path]),
      ),
  })
  ```

### autoLocale

* Type: `boolean`
* Default: `false`
* Details: Whether enable locales redirection.

### switchLocale

* Type: `"direct" | "modal" | false`
* Default: `false`
* Details:

  Whether switch to a new locale based on user preference.

  * `"direct"`: redirect to the new locale directly without asking
  * `"modal"`: show a modal to let user choose whether to switch to the new locale

### localeConfig

* Type: `Record<string, string | string[]>`

* Details: Locale language config

### localeFallback

* Type: `boolean`
* Default: `true`
* Details: Whether fallback to other locales user defined

### defaultBehavior

* Type: `"defaultLocale" | "homepage" | "404"`
* Default: `"defaultLocale"`
* Details: Behavior when a locale version is not available for current link.

### defaultLocale

* Type: `string`

* Default: the first locale

* Details: Default locale path.

* Type: `RedirectPluginLocaleConfig`

  ```ts
  interface RedirectPluginLocaleData {
    /**
     * Language name
     */
    name: string

    /**
     * Switch hint
     */
    hint: string

    /**
     * Switch button text
     */
    switch: string

    /**
     * Cancel button text
     */
    cancel: string

    /**
     * remember hint text
     */
    remember: string
  }

  interface RedirectPluginLocaleConfig {
    [localePath: string]: Partial<RedirectPluginLocaleData>
  }
  ```

* Details:

  Locales config for redirect plugin.

::: details Built-in Supported Languages

* **Simplified Chinese** (zh-CN)
* **Traditional Chinese** (zh-TW)
* **English (United States)** (en-US)
* **German** (de-DE)
* **German (Australia)** (de-AT)
* **Russian** (ru-RU)
* **Ukrainian** (uk-UA)
* **Vietnamese** (vi-VN)
* **Portuguese** (pt)
* **Polish** (pl-PL)
* **French** (fr-FR)
* **Spanish** (es-ES)
* **Slovak** (sk-SK)
* **Japanese** (ja-JP)
* **Turkish** (tr-TR)
* **Korean** (ko-KR)
* **Finnish** (fi-FI)
* **Indonesian** (id-ID)
* **Dutch** (nl-NL)

:::

## Frontmatter

### redirectFrom

* Type: `string | string[]`
* Details: The link which this page redirects from.

### redirectTo

* Type: `string`
* Details: The link which this page redirects to.

## Styles

You can customize the style of the redirect popup via CSS variables:

@[code css](@vuepress/plugin-redirect/src/client/styles/vars.css)

---

---
url: /plugins/tools/register-components.md
---
# register-components

Register Vue components from component files or directory automatically.

## Usage

```bash
npm i -D @vuepress/plugin-register-components@next
```

```ts title=".vuepress/config.ts"
import { registerComponentsPlugin } from '@vuepress/plugin-register-components'

export default {
  plugins: [
    registerComponentsPlugin({
      // options
    }),
  ],
}
```

## Options

### components

* Type: `Record<string, string>`

* Default: `{}`

* Details:

  An object that defines name of components and their corresponding file path.

  The key will be used as the component name, and the value is an absolute path of the component file.

  If the component name from this option conflicts with [componentsDir](#componentsdir) option, this option will have a higher priority.

* Example:

```ts title=".vuepress/config.ts"
import { getDirname, path } from 'vuepress/utils'

const __dirname = import.meta.dirname || getDirname(import.meta.url)

export default {
  plugins: [
    registerComponentsPlugin({
      components: {
        FooBar: path.resolve(__dirname, './components/FooBar.vue'),
      },
    }),
  ],
}
```

### componentsDir

* Type: `string | null`

* Default: `null`

* Details:

  Absolute path to the components directory.

  Files in this directory which are matched with [componentsPatterns](#componentspatterns) will be registered as Vue components automatically.

* Example:

```ts title=".vuepress/config.ts"
import { getDirname, path } from 'vuepress/utils'

const __dirname = import.meta.dirname || getDirname(import.meta.url)

export default {
  plugins: [
    registerComponentsPlugin({
      componentsDir: path.resolve(__dirname, './components'),
    }),
  ],
}
```

Components directory:

```bash
components
├─ FooBar.vue
└─ Baz.vue
```

Components will be registered like this:

```ts
import { defineAsyncComponent } from 'vue'

app.component(
  'FooBar',
  defineAsyncComponent(() => import('/path/to/components/FooBar.vue')),
)

app.component(
  'Baz',
  defineAsyncComponent(() => import('/path/to/components/Baz.vue')),
)
```

### componentsPatterns

* Type: `string[]`

* Default: `['**/*.vue']`

* Details:

  Patterns to match component files using [tinyglobby](https://github.com/SuperchupuDev/tinyglobby).

  The patterns are relative to [componentsDir](#componentsdir).

### getComponentName

* Type: `(filename: string) => string`

* Default: `(filename) => path.trimExt(filename.replace(/\/|\\/g, '-'))`

* Details:

  A function to get component name from the filename.

  It will only take effect on the files in the [componentsDir](#componentsdir) which are matched with the [componentsPatterns](#componentspatterns).

  Notice that the `filename` is a filepath relative to [componentsDir](#componentsdir).

---

---
url: /plugins/tools/replace-assets.md
---
# replace-assets

Replace local assets links within the site, such as links to images, videos, audio, PDF, and other assets, by rewriting the local assets addresses to new ones.

## Why is this feature needed? {#why-need-this}

Many users choose to store their site's assets on CDN services to accelerate site access speed and improve site availability.

In this process, it is usually necessary to first upload the assets to the CDN service, then obtain the asset links from the CDN service, and finally use them in the site content.

This may seem fine at first glance, but in actual usage, it often requires repeatedly performing the following steps:

```txt
Upload assets -> Obtain asset links -> Use full asset links in content
```

During this process, content creation is frequently interrupted.

This plugin aims to solve this problem. During content creation, you only need to directly use local asset addresses, and the plugin will handle the replacement of asset addresses at the appropriate stage.

::: important The plugin does not modify the source files; it only performs replacements in the compiled content.
:::

## Usage

### Install

```sh
npm i -D @vuepress/plugin-replace-assets@next
```

### Configuration

```ts title=".vuepress/config.ts"
import { replaceAssetsPlugin } from '@vuepress/plugin-replace-assets'

export default {
  plugins: [
    replaceAssetsPlugin('https://cnd.example.com'), // ReplaceAssetsPluginOptions
  ],
}
```

### Assets Management

**You should store the assets in the [.vuepress/public](https://v2.vuepress.vuejs.org/guide/assets.html#public-files) directory**:

```sh
./docs
├── .vuepress
│ └── public  # [!code hl:6]
│     ├── images
│     │   ├── foo.jpg
│     │   └── bar.jpg
│     └── medias
│         └── foo.mp4
└── README.md
```

::: tip Why is it necessary to store files in this directory?

Before the site is compiled and ready for deployment, we can easily upload the files from this directory directly to a CDN.

:::

In markdown, use local resource paths directly:

```md
![foo](/images/foo.jpg)

<img src="/images/foo.jpg">
```

In `javascript`:

```js
const foo = '/images/foo.jpg'

const img = document.createElement('img')
img.src = '/images/foo.jpg'
```

In `css`:

```css
.foo {
  background: url('/images/foo.jpg');
}
```

The plugin will correctly identify these resources and replace them in the compiled content.

:::warning The plugin does not support recognizing concatenated paths like `'/images/' + 'foo.jpg'`.

:::

## Options

```ts
/**
 * Assets Replacement Target Path
 * - `string`: Directly concatenated before the original path
 * - `(url) => string`: Custom replacement method, returns the new path
 */
export type Replacement = string | ((url: string) => string)

/**
 * Assets Replacement Rule
 */
export interface ReplacementRule {
  /**
   * Assets Matching
   *
   * - `RegExp`: Match using regular expression
   * - `string`: Match using string
   *   - Strings starting with `^` or ending with `$` are automatically converted to regular expressions
   *   - For ordinary strings, checks if they appear at the start or end
   */
  find: RegExp | string

  /**
   * Assets Replacement Target Path
   */
  replacement: Replacement
}

export interface ReplaceAssetsOptions {
  /**
   * Custom Assets Replacement Rules
   */
  rules?: ReplacementRule | ReplacementRule[]
  /**
   * Built-in image matching rules, designed to match and find common image paths starting with `^/images/`
   */
  image?: Replacement
  /**
   * Built-in media matching rules, designed to match and locate common media paths such as videos and audio that start with `^/medias/`.
   */
  media?: Replacement
  /**
   * Equivalent to setting both `image` and `media` simultaneously.
   */
  all?: Replacement
}

/**
 * Assets Replacement Plugin Options
 */
export type ReplaceAssetsPluginOptions =
  | ReplaceAssetsOptions
  | Replacement
  | ReplacementRule
  | ReplacementRule[]
```

### Built-in Asset Matching Rules

For ease of use, the plugin provides built-in assets matching rules that you can directly utilize.

* `image`: Find image assets in the `.vuepress/public/images` directory, including local image asset links in formats such as `['apng','bmp','png','jpg','jpeg','jfif','pjpeg','pjp','gif','svg','ico','webp','avif','cur','jxl']`:

  ```md
  ![](/images/foo.jpg)
  <img src="/images/bar/baz.png">
  ```

* `media`: Find media assets in the `.vuepress/public/medias` directory, including local media asset links in formats such as `['mp4','webm','ogg','mp3','wav','flac','aac','opus','mov','m4a','vtt','pdf']`:

  ```md
  <video src="/medias/foo.mp4">
  <audio src="/medias/bar.mp3">
  ```

* `all`: Locates both image and media assets, combining the rules of `image` and `media`.

When directly passing a **asset link prefix** or a **asset link replacement function**, the plugin uses the `all` rule to replace asset links.

```ts title=".vuepress/config.ts"
import { replaceAssetsPlugin } from '@vuepress/plugin-replace-assets'

export default {
  plugins: [
    // replaceAssetsPlugin('https://cnd.example.com') // [!code hl]
    replaceAssetsPlugin((url) => `https://cnd.example.com${url}`), // [!code ++]
  ],
}
```

It is also possible to apply different asset link prefixes or asset link replacement functions for different built-in rules:

```ts title=".vuepress/config.ts"
import { replaceAssetsPlugin } from '@vuepress/plugin-replace-assets'

export default {
  plugins: [
    // replaceAssetsPlugin({  // [!code hl:4]
    //   image: 'https://image.cdn.com',
    //   media: 'https://media.cdn.com'
    // }),
    replaceAssetsPlugin({
      // [!code ++:4]
      image: (url) => `https://image.cdn.com${url}`,
      media: (url) => `https://media.cdn.com${url}`,
    }),
  ],
}
```

### Custom Asset Matching Rules

You can also customize asset matching rules:

```ts title=".vuepress/config.ts"
import { replaceAssetsPlugin } from '@vuepress/plugin-replace-assets'

export default {
  plugins: [
    replaceAssetsPlugin({
      // [!code ++:4]
      find: /^\/images\/.*\.(jpg|jpeg|png|gif|svg|webp|avif)$/,
      replacement: (url) => `https://image.cdn.com${url}`,
    }),
  ],
}
```

You can also customize multiple matching rules:

```ts title=".vuepress/config.ts"
import { replaceAssetsPlugin } from '@vuepress/plugin-replace-assets'

export default {
  plugins: [
    replaceAssetsPlugin([
      // [!code ++:12]
      // 查找图片资源
      {
        find: /^\/images\/.*\.(jpg|jpeg|png|gif|svg|webp|avif)$/,
        replacement: 'https://image.cdn.com',
      },
      // 查找媒体资源
      {
        find: /^\/medias\/.*\.(mp4|webm|ogg|mp3|wav|flac|aac|m3u8|m3u|flv|pdf)$/,
        replacement: (url) => `https://media.cdn.com${url}`,
      },
    ]),
  ],
}
```

**`find` Field Description**

The `find` field is used to match asset links and can be either a **regular expression** or a **string**.

When the input is a `string`:

* If it starts with `^` or ends with `$`, it will automatically be converted into a **regular expression**.
* Otherwise, it will check whether the asset link starts with `find` or ends with `find`.

```txt
'^/images/foo.jpg' -> /^\/images\/foo.jpg/
'/images/foo.jpg$' -> /^\/images\/foo.jpg$/
```

::: important All matching asset paths start with `/`.
:::

---

---
url: /themes/index.md
---
# Themes

---

---
url: /themes/default/index.md
---
# theme-default

## Usage

Install `@vuepress/theme-default` :

```bash
npm install @vuepress/theme-default@next
```

```ts title=".vuepress/config.ts"
import { defaultTheme } from '@vuepress/theme-default'

export default {
  theme: defaultTheme({
    // set theme config here
  }),
}
```

---

---
url: /themes/default/components.md
---
# Built-in Components

## Badge&#x20;

* Props:
  * type
    * Type： `'tip' | 'warning' | 'danger' | 'important' | 'info' | 'note'`
    * Default: `'tip'`
  * text
    * Type: `string`
    * Default: `''`
  * vertical
    * Type: `'top' | 'middle' | 'bottom' | undefined`
    * Default: `undefined`

* Example:

**Input**

```md
- VuePress - <Badge type="tip" text="v2" vertical="top" />
- VuePress - <Badge type="warning" text="v2" vertical="middle" />
- VuePress - <Badge type="danger" text="v2" vertical="bottom" />
- VuePress - <Badge type="important" text="v2" vertical="middle" />
- VuePress - <Badge type="info" text="v2" vertical="middle" />
- VuePress - <Badge type="note" text="v2" vertical="middle" />
```

**Output**

* VuePress -&#x20;
* VuePress -&#x20;
* VuePress -&#x20;
* VuePress -&#x20;
* VuePress -&#x20;
* VuePress -&#x20;

---

---
url: /themes/default/config.md
---
# Config

## Basic Config

### hostname

* Type: `string`

* Details:

  Hostname to be deployed, e.g.: `https://example.com`

### locales

* Type: `{ [path: string]: Partial<DefaultThemeLocaleData> }`

* Default: `{}`

* Details:

  Specify locales for i18n support.

  All the options inside the [Locale Config](#locale-config) section can be used in locales.

  This option will only take effect in default theme, so don't confuse with `locales` in [Site Config](./config.md#locales).

* Also see:
  * [Guide > I18n](https://v2.vuepress.vuejs.org/guide/i18n.html)

## Locale Config

Config of this section can be used as normal config, and can also be used in the [locales](#locales) option.

### colorMode

* Type: `'auto' | 'light' | 'dark'`

* Default: `'auto'`

* Details:

  Default color mode.

  If set to `'auto'`, the initial color mode will be automatically set according to [prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme).

* Also see:
  * [Default Theme > Config > colorModeSwitch](#colormodeswitch)

### colorModeSwitch

* Type: `boolean`

* Default: `true`

* Details:

  Enable color mode switching or not.

  If set to `true`, a button to switch color mode will be displayed in the navbar.

* Also see:
  * [Default Theme > Config > colorMode](#colormode)
  * [Default Theme > Locale Config > toggleColorMode](./locale.md#togglecolormode)

### externalLinkIcon

* Type: `boolean`

* Default: `true`

* Details:

  Show external link icon on external links or not.

### home

* Type: `string`

* Default: `/`

* Details:

  Specify the path of the homepage.

  This will be used for:

  * the logo link of the navbar
  * the *back to home* link of the 404 page

### navbar

* Type: `false | NavbarOptions`

* Default: `[]`

* Details:

  Configuration of navbar.

  Set to `false` to disable navbar.

  To configure the navbar items, you can set it to a *navbar array*, each item of which could be a `NavbarLink` object, a `NavbarGroup` object, or a string:

  * A `NavbarLink` object should have a `text` field and a `link` field, could have an optional `activeMatch` field.
  * A `NavbarGroup` object should have a `text` field and a `children` field, could have an optional `prefix` field. The `children` field should be a *navbar array* too, and `prefix` will be prepended before every link inside it.
  * A string should be the path to the target page file. It will be converted to a `NavbarLink` object, using the page title as `text`, and the page route path as `link`.

* Example 1:

```ts title=".vuepress/config.ts"
export default {
  theme: defaultTheme({
    navbar: [
      // NavbarLink
      {
        text: 'Foo',
        link: '/foo/',
      },
      // NavbarGroup
      {
        text: 'Group',
        prefix: '/group/',
        children: ['foo.md', 'bar.md'],
      },
      // string - page file path
      '/bar/README.md',
    ],
  }),
}
```

* Example 2:

```ts title=".vuepress/config.ts"
export default {
  theme: defaultTheme({
    navbar: [
      // nested group - max depth is 2
      {
        text: 'Group',
        children: [
          {
            text: 'SubGroup1',
            prefix: 'sub1/',
            children: [
              'foo.md', // resolved as `/guide/group/sub1/bar.md`
              'bar.md', // resolved as `/guide/group/sub1/bar.md`

              // an external link
              {
                text: 'Example',
                link: 'https://example.com',
              },
            ],
          },
          {
            text: 'SubGroup2',
            prefix: 'sub2/',
            // for project links, .md or .html suffix is optional
            children: [
              'foo', // resolved as `/guide/group/sub2/foo.md`
              'bar', // resolved as `/guide/group/sub2/bar.md`

              // link not inside SubGroup2
              '/baz/', // resolved as `/baz/README.md`
            ],
          },
        ],
      },
      // control when should the item be active
      {
        text: 'Group 2',
        children: [
          {
            text: 'Always active',
            link: '/',
            // this item will always be active
            activeMatch: '/',
          },
          {
            text: 'Active on /foo/',
            link: '/not-foo/',
            // this item will be active when current route path starts with /foo/
            // regular expression is supported
            activeMatch: '^/foo/',
          },
        ],
      },
    ],
  }),
}
```

### logo

* Type: `null | string`

* Details:

  Specify the url of logo image.

  The logo image will be displayed at the left end of the navbar.

  Set to `null` to disable logo.

* Example:

```ts title=".vuepress/config.ts"
export default {
  theme: defaultTheme({
    // public file path
    logo: '/hero.png',
    // url
    logo: 'https://vuepress.vuejs.org/images/hero.png',
  }),
}
```

* Also see:
  * [Guide > Assets > Public Files](https://v2.vuepress.vuejs.org/guide/assets.html#public-files)

### logoDark

* Type: `null | string`

* Details:

  Specify the url of logo image to be used in dark mode.

  You can make use of this option if you want to use different logo config in dark mode.

  Set to `null` to disable logo in dark mode. Omit this option to use [logo](#logo) in dark mode.

* Also see:
  * [Default Theme > Config > logo](#logo)
  * [Default Theme > Config > colorMode](#colormode)

### logoAlt

* Type: `null | string`

* Details:

  Specify the alt text of the logo image.

  If not specified, defaults to be the same as the site title.

### repo

* Type: `string`

* Details:

  Specify the repository url of your project.

  This will be used as the link of the *repository link*, which will be displayed as the last item of the navbar.

```ts title=".vuepress/config.ts"
export default {
  theme: defaultTheme({
    // If you set it in the form of `organization/repository`
    // we will take it as a GitHub repo
    repo: 'vuepress/ecosystem',
    // You can also set it to a URL directly
    repo: 'https://gitlab.com/foo/bar',
  }),
}
```

### sidebar

* Type: `false | SidebarOptions`

* Default: `'heading'`

* Details:

  Configuration of sidebar.

  You can override this global option via [sidebar](./frontmatter.md#sidebar) frontmatter in your pages.

  Set to `false` to disable sidebar.

  If you set it to `'heading'`, the sidebar will be automatically generated from the page headers.

  To configure the sidebar items manually, you can set this option to a *sidebar array*, each item of which could be a `SidebarItem` object or a string:

  * A `SidebarItem` object should have a `text` field, could have an optional `link` field, an optional `children` field, an optional `collapsible` field and an optional `prefix` field. The `children` field should be a *sidebar array*, where `prefix` will be prepended to every link inside it. The `collapsible` field controls whether the item is collapsible.
  * A string should be the path to the target page file. It will be converted to a `SidebarItem` object, whose `text` is the page title, `link` is the page route path, and `children` is automatically generated from the page headers.

  If you want to set different sidebar for different sub paths, you can set this option to a *sidebar object*:

  * The key should be the path prefix.
  * The value should be a *sidebar array* or set to `'heading'` to automatically generate the sidebar from the page headers for just the corresponding path.

* Example 1:

```ts title=".vuepress/config.ts"
export default {
  theme: defaultTheme({
    // sidebar array
    // all pages will use the same sidebar
    sidebar: [
      // SidebarItem
      {
        text: 'Foo',
        prefix: '/foo/',
        link: '/foo/',
        children: [
          // SidebarItem
          {
            text: 'github',
            link: 'https://github.com',
            children: [],
          },
          // string - page file path
          'bar.md', // resolved to `/foo/bar.md`
          '/ray.md', // resolved to `/ray.md`
        ],
      },
      // string - page file path
      '/bar/README.md',
    ],
  }),
}
```

* Example 2:

```ts title=".vuepress/config.ts"
export default {
  theme: defaultTheme({
    // sidebar object
    // pages under different sub paths will use different sidebar
    sidebar: {
      '/guide/': [
        {
          text: 'Guide',
          // prefix will be prepended to relative paths
          children: [
            'introduction.md', // resolved to `/guide/introduction.md`
            'getting-started.md', // resolved to `/guide/getting-started.md`
          ],
        },
      ],
      '/reference/': 'heading',
    },
  }),
}
```

* Example 3:

```ts title=".vuepress/config.ts"
export default {
  theme: defaultTheme({
    // collapsible sidebar
    sidebar: {
      '/reference/': [
        {
          text: 'VuePress Reference',
          collapsible: true,
          // for project links, .md or .html suffix is optional
          children: ['cli', 'config'],
        },
        {
          text: 'Bundlers Reference',
          collapsible: true,
          // prefix can be a relative path, which is equivalent to `prefix: /reference/bundler/`
          prefix: 'bundler/',
          children: ['vite', 'webpack'],
        },
      ],
    },
  }),
}
```

### sidebarDepth

* Type: `number`

* Default: `2`

* Details:

  Set the maximum depth of the sidebar children which are automatically generated from the page headers.

  * Set to `0` to disable all levels of headers.
  * Set to `1` to include `<h2>` headers.
  * Set to `2` to include `<h2>` and `<h3>` headers.
  * ...

  You can override this global option via [sidebarDepth](./frontmatter.md#sidebardepth) frontmatter in your pages.

### editLink

* Type: `boolean`

* Default: `true`

* Details:

  Enable the *edit this page* link or not.

  You can override this global option via [editLink](./frontmatter.md#editlink) frontmatter in your pages.

### editLinkPattern

* Type: `string`

* Details:

  Specify the pattern of the *edit this page* link.

  This will be used for generating the *edit this page* link.

  If you don't set this option, the pattern will be inferred from the [docsRepo](#docsrepo) option. But if your documentation repository is not hosted on a common platform, for example, GitHub, GitLab, Bitbucket, Gitee, etc., you have to set this option explicitly to make the *edit this page* link work.

* Usage:

  | Pattern   | Description                                                                                         |
  | --------- | --------------------------------------------------------------------------------------------------- |
  | `:repo`   | The docs repo url, i.e. [docsRepo](#docsrepo)                                                       |
  | `:branch` | The docs repo branch, i.e. [docsBranch](#docsbranch)                                                |
  | `:path`   | The path of the page source file, i.e. [docsDir](#docsdir) joins the relative path of the page file |

* Example:

```ts title=".vuepress/config.ts"
export default {
  theme: defaultTheme({
    docsRepo: 'https://gitlab.com/owner/name',
    docsBranch: 'master',
    docsDir: 'docs',
    editLinkPattern: ':repo/-/edit/:branch/:path',
  }),
}
```

The generated link will look like `'https://gitlab.com/owner/name/-/edit/master/docs/path/to/file.md'`.

### docsRepo

* Type: `string`

* Details:

  Specify the repository url of your documentation source files.

  This will be used for generating the *edit this page* link.

  If you don't set this option, it will use the [repo](#repo) option by default. But if your documentation source files are in a different repository, you will need to set this option.

### docsBranch

* Type: `string`

* Default: `'main'`

* Details:

  Specify the repository branch of your documentation source files.

  This will be used for generating the *edit this page* link.

### docsDir

* Type: `string`

* Default: `''`

* Details:

  Specify the directory of your documentation source files in the repository.

  This will be used for generating the *edit this page* link.

### lastUpdated

* Type: `boolean`

* Default: `true`

* Details:

  Enable the *last updated timestamp* or not.

  You can override this global option via [lastUpdated](./frontmatter.md#lastupdated) frontmatter in your pages. Notice that if you have already set this option to `false`, this feature will be disabled totally and could not be enabled in locales nor page frontmatter.

### contributors

* Type: `boolean`

* Default: `true`

* Details:

  Enable the *contributors list* or not.

  You can override this global option via [contributors](./frontmatter.md#contributors) frontmatter in your pages. Notice that if you have already set this option to `false`, this feature will be disabled totally and could not be enabled in locales nor page frontmatter.

---

---
url: /themes/default/extending.md
---
# Extending

VuePress default theme is widely used by users, so it is designed to be extendable, allowing users to make their own customization with ease.

## Layout Slots

Default theme's `Layout` provides some slots:

* `navbar`
* `navbar-before`
* `navbar-after`
* `sidebar`
* `sidebar-top`
* `sidebar-bottom`
* `page`
* `page-top`
* `page-bottom`
* `page-content-top`
* `page-content-bottom`

With the help of them, you can add or replace content easily. Here comes an example to introduce how to extend default theme with layout slots.

Firstly, create a client config file `.vuepress/client.ts`:

```ts title=".vuepress/client.ts"
import { defineClientConfig } from 'vuepress/client'
import Layout from './layouts/Layout.vue'

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

Next, create the `.vuepress/layouts/Layout.vue`, and make use of the slots that provided by the `Layout` of default theme:

```vue
<script setup>
import ParentLayout from '@vuepress/theme-default/layouts/Layout.vue'
</script>

<template>
  <ParentLayout>
    <template #page-bottom>
      <div class="my-footer">This is my custom page footer</div>
    </template>
  </ParentLayout>
</template>

<style lang="css">
.my-footer {
  text-align: center;
}
</style>
```

Then the default `Layout` layout has been overridden by your own local layout, which will add a custom footer to every normal pages in default theme (excluding homepage):

![extending-a-theme](/images/cookbook/extending-a-theme-01.png)

## Components Replacement

The layout slots are useful, but sometimes you might find it's not flexible enough. Default theme also provides the ability to replace a single component.

Default theme has registered [alias](https://v2.vuepress.vuejs.org/plugin-api.html#alias) for every [non-global components](https://github.com/vuepress/ecosystem/tree/main/themes/theme-default/src/client/components) with a `@theme` prefix. For example, the alias of `HomeFooter.vue` is `@theme/HomeFooter.vue`.

Then, if you want to replace the `HomeFooter.vue` component, just override the alias in your config file `.vuepress/config.ts`:

```ts title=".vuepress/config.ts"
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'
import { getDirname, path } from 'vuepress/utils'

const __dirname = import.meta.dirname || getDirname(import.meta.url)

export default defineUserConfig({
  theme: defaultTheme(),
  alias: {
    '@theme/HomeFooter.vue': path.resolve(
      __dirname,
      './components/MyHomeFooter.vue',
    ),
  },
})
```

## Modifying Behavior

Most of the core behaviors of the default theme have been extracted into a composable API or util function, and also provide [aliases](https://v2.vuepress.vuejs.org/zh/reference/plugin-api.html#alias) with the `@theme` prefix.

For example, if you want to add some default values ​​to the theme data of the default theme, you can override the `useThemeData` function of `@theme/useThemeData`.

## Developing a Child Theme

Instead of extending the default theme directly in `.vuepress/config.ts` and `.vuepress/client.ts`, you can also develop your own theme extending the default theme:

```ts title=".vuepress/config.ts"
import type { DefaultThemeOptions } from '@vuepress/theme-default'
import { defaultTheme } from '@vuepress/theme-default'
import type { Theme } from 'vuepress/core'
import { getDirname, path } from 'vuepress/utils'

const __dirname = import.meta.dirname || getDirname(import.meta.url)

export const childTheme = (options: DefaultThemeOptions): Theme => ({
  name: 'vuepress-theme-child',
  extends: defaultTheme(options),

  // override layouts in child theme's client config file
  // notice that you would build ts to js before publishing to npm,
  // so this should be the path to the js file
  clientConfigFile: path.resolve(__dirname, './client.js'),

  // override component alias
  alias: {
    '@theme/HomeFooter.vue': path.resolve(
      __dirname,
      './components/MyHomeFooter.vue',
    ),
  },
})
```

---

---
url: /themes/default/frontmatter.md
---
# Frontmatter

## All Pages

Frontmatter in this section will take effect in all types of pages.

### externalLinkIcon

* Type: `boolean`

* Details:

  Show external link icon on external links or not.

* Also see:
  * [Default Theme > Config > externalLinkIcon](./config.md#externallinkicon)

### navbar

* Type: `boolean`

* Details:

  Show navbar on this page or not.

  If you disable navbar in theme config, this frontmatter will not take effect.

* Also see:
  * [Default Theme > Config > navbar](./config.md#navbar)

### pageClass

* Type: `string`

* Details:

  Add extra class name to this page.

* Example:

```md
---
pageClass: custom-page-class
---
```

Then you can customize styles of this page in `.vuepress/styles/index.scss` file:

```scss
[vp-container].custom-page-class {
  /* page styles */
}
```

* Also see:
  * [Default Theme > Styles > Style File](./styles.md#style-file)

## Home Page

Frontmatter in this section will only take effect in home pages.

### home

* Type: `boolean`

* Details:

  Specify whether the page is homepage or a normal page.

  If you don't set this frontmatter or set it to `false`, the page would be a [normal page](#normal-page).

* Example:

```md
---
home: true
---
```

### heroImage

* Type: `string`

* Details:

  Specify the url of the hero image.

* Example:

```md
---
# public file path
heroImage: /images/hero.png
# url
heroImage: https://vuepress.vuejs.org/images/hero.png
---
```

* Also see:
  * [Guide > Assets > Public Files](https://v2.vuepress.vuejs.org/guide/assets.html#public-files)

### heroImageDark

* Type: `string`

* Details:

  Specify the url of hero image to be used in dark mode.

  You can make use of this option if you want to use different heroImage config in dark mode.

* Also see:
  * [Default Theme > Frontmatter > heroImage](#heroimage)
  * [Default Theme > Config > colorMode](./config.md#colormode)

### heroAlt

* Type: `string`

* Details:

  Specify the `alt` attribute of the hero image.

  This will fallback to the [heroText](#herotext).

### heroHeight

* Type: `number`

* Default: `280`

* Details:

  Specify the `height` attribute of the hero `<img>` tag.

  You may need to reduce this value if the height of your hero image is less than the default value.

  Notice that the height is also constrained by CSS. This attribute is to reduce [Cumulative Layout Shift (CLS)](https://web.dev/cls/) that caused by the loading of the hero image.

### heroText

* Type: `string | null`

* Details:

  Specify the the hero text.

  This will fallback to the site [title](https://v2.vuepress.vuejs.org/reference/config.html#title).

  Set to `null` to disable hero text.

### tagline

* Type: `string | null`

* Details:

  Specify the the tagline.

  This will fallback to the site [description](https://v2.vuepress.vuejs.org/reference/config.html#description).

  Set to `null` to disable tagline.

### actions

* Type:

```ts
Array<{
  text: string
  link: string
  type?: 'primary' | 'secondary'
}>
```

* Details:

  Configuration of the action buttons.

* Example:

```md
---
actions:
  - text: Get Started
    link: /guide/getting-started.html
    type: primary
  - text: Introduction
    link: /guide/introduction.html
    type: secondary
---
```

### features

* Type:

```ts
Array<{
  title: string
  details: string
}>
```

* Details:

  Configuration of the features list.

* Example:

```md
---
features:
  - title: Simplicity First
    details: Minimal setup with markdown-centered project structure helps you focus on writing.
  - title: Vue-Powered
    details: Enjoy the dev experience of Vue, use Vue components in markdown, and develop custom themes with Vue.
  - title: Performant
    details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
---
```

### footer

* Type: `string`

* Details:

  Specify the content of the footer.

### footerHtml

* Type: `boolean`

* Details:

  Allow HTML in footer or not.

  If you set it to `true`, the [footer](#footer) will be treated as HTML code.

## Normal Page

Frontmatter in this section will only take effect in normal pages.

### editLink

* Type: `boolean`

* Details:

  Enable the *edit this page* link in this page or not.

* Also see:
  * [Default Theme > Config > editLink](./config.md#editlink)

### editLinkPattern

* Type: `string`

* Details:

  Specify the pattern of the *edit this page* link of this page.

* Also see:
  * [Default Theme > Config > editLinkPattern](./config.md#editlinkpattern)

### lastUpdated

* Type: `boolean`

* Details:

  Enable the *last updated timestamp* in this page or not.

* Also see:
  * [Default Theme > Config > lastUpdated](./config.md#lastupdated)

### contributors

* Type: `boolean`

* Details:

  Enable the *contributors list* in this page or not.

* Also see:
  * [Default Theme > Config > contributors](./config.md#contributors)

### sidebar

* Type: `false | SidebarOptions`

* Details:

  Configure the sidebar of this page.

* Also see:
  * [Default Theme > Config > sidebar](./config.md#sidebar)

### sidebarDepth

* Type: `number`

* Details:

  Configure the sidebar depth of this page.

* Also see:
  * [Default Theme > Config > sidebarDepth](./config.md#sidebardepth)

### prev

* Type: `AutoLinkConfig | string | false`

* Details:

  Specify the link of the previous page.

  If you don't set this frontmatter, the link will be inferred from the sidebar config.

  To configure the prev link manually, you can set this frontmatter to a `AutoLinkConfig` object or a string:

  * A `AutoLinkConfig` object should have a `text` field and a `link` field.
  * A string should be the path to the target page file. It will be converted to a `AutoLinkConfig` object, whose `text` is the page title, and `link` is the page route path.
  * Set to `false` to disable the prev link.

* Example:

```md
---
# AutoLinkConfig
prev:
  text: Get Started
  link: /guide/getting-started.html

# AutoLinkConfig - external url
prev:
  text: GitHub
  link: https://github.com

# string - page file path
prev: /guide/getting-started.md

# string - page file relative path
prev: ../../guide/getting-started.md
---
```

### next

* Type: `AutoLinkConfig | string | false`

* Details:

  Specify the link of the next page.

  If you don't set this frontmatter, the link will be inferred from the sidebar config.

  The type is the same as [prev](#prev) frontmatter.

---

---
url: /themes/default/locale.md
---
# Locale Config

These options configure locale-related texts.

If your site is served in a different language besides English, you should set these options per locale to provide translations.

## repoLabel

* Type: `string`

* Details:

  Specify the repository label of your project.

  This will be used as the text of the *repository link*, which will be displayed as the last item of the navbar.

  If you don't set this option explicitly, it will be automatically inferred from the [repo](./config.md#repo) option.

## selectLanguageText

* Type: `string`

* Details:

  Specify the text of the *select language menu*.

  The *select language menu* will appear next to the repository button in the navbar when you set multiple [locales](./config.md#locales) in your site config.

## selectLanguageAriaLabel

* Type: `string`

* Details:

  Specify the `aria-label` attribute of the *select language menu*.

  This is mainly for a11y purpose.

## selectLanguageName

* Type: `string`

* Details:

  Specify the name of the language of a locale.

  This option will **only take effect inside** the [locales](./config.md#locales) of your theme config. It will be used as the language name of the locale, which will be displayed in the *select language menu*.

* Example:

```ts title=".vuepress/config.ts"
export default {
  locales: {
    '/': {
      lang: 'en-US',
    },
    '/zh/': {
      lang: 'zh-CN',
    },
  },
  theme: defaultTheme({
    locales: {
      '/': {
        selectLanguageName: 'English',
      },
      '/zh/': {
        selectLanguageName: '简体中文',
      },
    },
  }),
}
```

## navbarLabel

* Type: `null | string`

* Details:

  `aria-label` value for main navigation in navbar.

## pageNavbarLabel

* Type: `null | string`

* Details:

  `aria-label` value for next/previous page navigation.

## editLinkText

* Type: `string`

* Default: `'Edit this page'`

* Details:

  Specify the text of the *edit this page* link.

## lastUpdatedText

* Type: `string`

* Default: `'Last Updated'`

* Details:

  Specify the text of the *last updated timestamp* label.

## contributorsText

* Type: `string`

* Default: `'Contributors'`

* Details:

  Specify the text of the *contributors list* label.

## tip

* Type: `string`

* Default: `'TIP'`

* Details:

  Specify the default title of the tip [custom containers](./markdown.md#custom-containers).

## warning

* Type: `string`

* Default: `'WARNING'`

* Details:

  Specify the default title of the warning [custom containers](./markdown.md#custom-containers).

## danger

* Type: `string`

* Default: `'DANGER'`

* Details:

  Specify the default title of the danger [custom containers](./markdown.md#custom-containers).

## notFound

* Type: `string[]`

* Default: `['Not Found']`

* Details:

  Specify the messages of the 404 page.

  The message will be randomly picked from the array when users enter the 404 page.

## backToHome

* Type: `string`

* Default: `'Back to home'`

* Details:

  Specify the text of the *back to home* link in the 404 page.

## toggleColorMode

* Type: `string`

* Default: `'toggle color mode'`

* Details:

  Title text for the color mode toggle button.

  This is mainly for a11y purpose.

* Also see:
  * [Default Theme > Config > colorModeSwitch](./config.md#colormodeswitch)

## toggleSidebar

* Type: `string`

* Default: `'toggle sidebar'`

* Details:

  Title text for sidebar toggle button.

  This is mainly for a11y purpose.

## prev

* Type: `string | false`

* Default: `'Prev'`

* Details:

  Text for the previous page navigation button.

  Set to `false` to disable the previous page navigation button.

## next

* Type: `string | false`
* Default: `'Next'`
* Details:

  Text for the next page navigation button.

  Set to `false` to disable the next page navigation button.

---

---
url: /themes/default/markdown.md
---
# Markdown

## Hint Containers

* Example 1 (default title):

**Input**

```md
::: tip
This is a tip
:::

::: warning
This is a warning
:::

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

::: info
This is an information.
:::

::: important
This is an important message
:::

::: note
This is a note
:::

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

**Output**

::: tip
This is a tip
:::

::: warning
This is a warning
:::

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

::: info
This is an information.
:::

::: important
This is an important message
:::

::: note
This is a note
:::

::: details
This is a details block
:::

* Example 2 (custom title):

**Input**

````md
::: danger STOP
Danger zone, do not proceed
:::

::: details Click me to view the code

```ts
console.log('Hello, VuePress!')
```

:::
````

**Output**

::: danger STOP
Danger zone, do not proceed
:::

::: details Click me to view the code

```ts
console.log('Hello, VuePress!')
```

:::

## Code Tabs

**Input**

````md
::: code-tabs

@tab JavaScript

```js
const name = 'VuePress'
console.log(`Hello, ${name}!`)
```

@tab TypeScript

```ts
const name: string = 'VuePress'

console.log(`Hello, ${name}!`)
```

:::
````

**Output**

::: code-tabs

@tab JavaScript

```js
const name = 'VuePress'
console.log(`Hello, ${name}!`)
```

@tab TypeScript

```ts
const name: string = 'VuePress'

console.log(`Hello, ${name}!`)
```

:::

## Tabs

**Input**

````md
::: tabs

@tab Tab1

This is the content of Tab1.

```js
console.log('Hello, VuePress!')
```

@tab Tab2

This is the content of Tab2.

- List item 1
- List item 2
- List item 3

:::
````

**Output**

::: tabs

@tab Tab1

This is the content of Tab1.

```js
console.log('Hello, VuePress!')
```

@tab Tab2

This is the content of Tab2.

* List item 1
* List item 2
* List item 3

:::

---

---
url: /themes/default/plugin.md
---
# Plugins Config

You can configure the plugins that used by default theme with `themePlugins`.

Default theme is using some plugins by default. You can disable a plugin if you really do not want to use it. Make sure you understand what the plugin is for before disabling it.

```ts title=".vuepress/config.ts"
import { defaultTheme } from '@vuepress/theme-default'

export default {
  theme: defaultTheme({
    themePlugins: {
      // customize theme plugins here
    },
  }),
}
```

## themePlugins.activeHeaderLinks

* Type: `boolean`

* Default: `true`

* Details:

  Enable [@vuepress/plugin-active-header-links](../../plugins/development/active-header-links.md) or not.

## themePlugins.backToTop

* Type: `BackToTopPluginOptions | boolean`

* Default: `true`

* Details:

  Enable [@vuepress/plugin-back-to-top](../../plugins/features/back-to-top.md) or not.

  Object value is supported as plugin options.

## themePlugins.container

* Type: `Record<ContainerType, boolean>`

* Details:

  Enable custom containers that powered by [@vuepress/plugin-markdown-container](../../plugins/markdown/markdown-container.md) or not.

  `ContainerType` type is:

  * `codeGroup`
  * `codeGroupItem`

* Also see:
  * [Default Theme > Markdown > Custom Containers](./markdown.md#custom-containers)

## themePlugins.copyCode

* Type: `CopyCodePluginOptions | boolean`

* Default: `true`

* Details:

  Enable [@vuepress/plugin-copy-code](../../plugins/features/copy-code.md) or not.

  Object value is supported as plugin options.

## themePlugins.git

* Type: `boolean`

* Default: `true`

* Details:

  Enable [@vuepress/plugin-git](../../plugins/development/git.md) or not.

## themePlugins.hint

* Type: `MarkdownHintPluginOptions | boolean`

* Default: `true`

* Details:

  Enable [@vuepress/plugin-markdown-hint](../../plugins/markdown/markdown-hint.md) or not.

* Also see:
  * [Default Theme > Markdown > Hint Containers](./markdown.md#hint-containers)

## themePlugins.linksCheck

* Type: `LinksCheckPluginOptions | boolean`

* Default: `true`

* Details:

  Enable [@vuepress/plugin-links-check](../../plugins/markdown/links-check.md) or not.

  Object value is supported as plugin options.

## themePlugins.mediumZoom

* Type: `boolean`

* Default: `true`

* Details:

  Enable [@vuepress/plugin-medium-zoom](../../plugins/features/medium-zoom.md) or not.

## themePlugins.nprogress

* Type: `boolean`

* Default: `true`

* Details:

  Enable [@vuepress/plugin-nprogress](../../plugins/features/nprogress.md) or not.

## themePlugins.prismjs

* Type: `boolean`

* Default: `true`

* Details:

  Enable [@vuepress/plugin-prismjs](../../plugins/markdown/prismjs.md) or not.

## themePlugins.seo

* Type: `SeoPluginOptions | boolean`

* Default: `true`

* Details:

  Enable [@vuepress/plugin-seo](../../plugins/seo/seo/README.md) or not.

  Object value is supported as plugin options.

## themePlugins.sitemap

* Type: `SitemapPluginOptions | boolean`

* Default: `true`

* Details:

  Enable [@vuepress/plugin-sitemap](../../plugins/seo/sitemap/README.md) or not.

  Object value is supported as plugin options.

## themePlugins.tab

* Type: `MarkdownTabPluginOptions | boolean`

* Default: `true`

* Details:

  Enable [@vuepress/plugin-markdown-tab](../../plugins/markdown/markdown-tab.md) or not.

* Also see:
  * [Default Theme > Markdown > Code Tabs](./markdown.md#code-tabs)
  * [Default Theme > Markdown > Tabs](./markdown.md#tabs)

---

---
url: /themes/default/styles.md
---
# Styles

The default theme uses [SASS](https://sass-lang.com/) as the CSS pre-processor.

Users can customize style variables via a [palette file](#palette-file),
and add extra styles via a [style file](#style-file).

## Palette File

The path of the palette file is `.vuepress/styles/palette.scss`.

You can make use of it to override predefined SASS variables of the default theme.

::: details Click to expand SASS variables
@[code{3-} scss](@vuepress/theme-default/src/client/styles/_variables.scss)
:::

## Style File

The path of the style file is `.vuepress/styles/index.scss`.

You can add extra styles here, or override the default styles:

```scss
:root {
  scroll-behavior: smooth;
}
```

You can also make use of it to override predefined CSS variables of the default theme.

::: details Click to expand CSS variables
@[code scss](@vuepress/theme-default/src/client/styles/vars.scss)
:::

::: details Click to expand dark mode CSS variables
@[code scss](@vuepress/theme-default/src/client/styles/vars-dark.scss)
:::

---

---
url: /themes/guidelines.md
---
# Theme Guidelines

To avoid theme developers and users setting unneeded options, we have a set of guidelines that should be followed when creating a theme.

## DOM Structure

A theme must implement the following DOM structure:

* Container: An element which contains the entire theme. This element should have an attribute `vp-container`.
* Content: An element which holds markdown render results. This element should have an attribute `vp-content`.

A theme may have the following optional elements:

* Navbar: Navbar of the site. This element should have an attribute `vp-navbar`.
* Sidebar: Sidebar of the site. This element should have an attribute `vp-sidebar`.
* Outline: Headings or outline of the main content. This element should have an attribute `vp-outline`.
* Comment: Comment service (comment box and comment list). This element should have an attribute `vp-comment`.
* Footer: Footer of the site. This element should have an attribute `vp-footer`.

A theme must:

* Set `data-theme` to `dark` on html in darkmode.
* Set `data-theme` to `light` on html in lightmode.

If it only have one color scheme, it still needs to set `data-theme` to `light` or `dark` to indicate the default color scheme.

## Components

To support search plugins, a theme shall check whether `<SearchBox />` is globally registered and render it in it's own navbar or sidebar if it is available.

## Color Variables

A theme must implement the following color variables:

### Text

* `--vp-c-text`: Default text color.
* `--vp-c-text-mute`: Colors for muted texts, such as "inactive menu" or "info texts".
* `--vp-c-text-subtle`: Color for subtle text, such as as "placeholders" or "caret icon".

### Background

* `--vp-c-bg`: The bg color used for main screen.
* `--vp-c-bg-alt`: The alternative bg color used in places such as "sidebar", or "code block".
* `--vp-c-bg-elv`: The elevated bg color. This is used at parts where it "floats", such as "dialog".

### Shadow

* `--vp-c-shadow`: Shadow color

### Accent

Accent color and brand colors which used for interactive components.

* `--vp-c-accent`: The most solid color used mainly for colored text. It must satisfy the contrast ratio against when used on top of `--vp-c-accent-soft`.
* `--vp-c-accent-hover`: Color used for hover state.
* `--vp-c-accent-bg`: Color used for solid background. It must satisfy the contrast ratio with `--vp-c-accent-text` on top of it.
* `--vp-c-accent-text`: Color used for text with `--vp-c-accent-bg` background. It must satisfy the contrast ratio with `--vp-c-accent-bg`.
* `--vp-c-accent-soft`: The color used for subtle background such as custom container or badges. It must satisfy the contrast ratio when putting `--vp-c-accent` colors on top of it.

  The soft color must be semi transparent alpha channel. This is crucial because it allows adding multiple "soft" colors on top of each other to create a accent, such as when having inline code block inside custom containers.

### Borders

* `--vp-c-border`: Border color for interactive components. For example this should be used for a button outline.
* `--vp-c-border-hard`: Darker border colors, which is used for "hard" borders closed to text, such as table and kbd.
* `--vp-c-divider`: Color for separators, used to divide sections within the same components, such as having separator on "h2" heading.

### Controls

* `--vp-c-control`: Background color for interactive controls, such as buttons or checkboxes.
* `--vp-c-control-hover`: Background color for hover state of interactive controls.
* `--vp-c-control-disabled`: Color for disabled state of interactive controls.

## Transition timing

* `--vp-t-color`: Color transition timing.
* `--vp-t-transform`: Transform transition timing.

## Demo

---

---
url: /tools/index.md
---
# Tool Packages

---

---
url: /tools/helper/index.md
---
# @vuepress/helper

This package is a helper utility for VuePress developers.

* `@vuepress/helper`: Node.js side helper utilities.
  * [Bundler Related](node/bundler.md)
  * [Locales Related](node/locales.md)
  * [Page Related](node/page.md)

* [`@vuepress/helper/client`](client.md): Client side helper utilities.

* [`@vuepress/helper/shared`](shared.md): Utilities that are both available at Node.js side or Client.

---

---
url: /tools/helper/client.md
---
# Client Related

These functions are only available in `@vuepress/helper/client`.

## Composables APIs

### hasGlobalComponent

Check if a global component with the given name exists.

```ts
export const hasGlobalComponent: (name: string, app?: App) => boolean
```

::: tip

1. Local import of the component does not affect the result.
2. When calling outside `setup` scope, you need to pass the `app` instance as the second parameter.

:::

::: details Example

```ts
// if you globally register `<my-component>`
hasGlobalComponent('MyComponent') // true
hasGlobalComponent('my-component') // true

hasGlobalComponent('MyComponent2') // false
```

:::

### useLocaleConfig

Get current locale config from locales settings.

```ts
export const useLocaleConfig: <T extends LocaleData>(
  localesConfig: RequiredLocaleConfig<T>,
) => ComputedRef<T>
```

::: details Example

```ts
const localesConfig = {
  '/': 'Title',
  '/zh/': '标题',
}

const locale = useLocaleConfig(localesConfig)

// under `/page`
locale.value // 'Title'

// under `/zh/page`
locale.value // '标题'
```

:::

## Utils

### env

Accept user agent and check if the current environment satisfies the given condition:

```ts
export const isMobile: (ua: string) => boolean
export const isSafari: (ua: string) => boolean
export const isiPhone: (ua: string) => boolean
export const isiPad: (ua: string) => boolean
export const isWindows: (ua: string) => boolean
export const isIOS: (ua: string) => boolean
export const isMacOS: (ua: string) => boolean
```

**Params:**

* `ua`: User agent string to check against

**Returns:**

* `boolean`: Whether the condition is satisfied

::: details Example

```ts
import { isIOS, isMobile, isSafari } from '@vuepress/helper/client'

// Get user agent string
const userAgent = navigator.userAgent

// Check environment
if (isMobile(userAgent)) {
  console.log('User is on a mobile device')
}

if (isSafari(userAgent)) {
  console.log('User is using Safari browser')
}

if (isIOS(userAgent)) {
  console.log('User is on an iOS device')
}
```

:::

### getHeaders

Get headers from current page.

```ts
export const getHeaders: (options: GetHeadersOptions) => HeaderItem[]
```

**Params:**

```ts
export interface GetHeadersOptions {
  /**
   * The selector of the headers.
   *
   * It will be passed as an argument to `document.querySelectorAll(selector)`,
   * so you should pass a `CSS Selector` string.
   *
   * @default '[vp-content] h1, [vp-content] h2, [vp-content] h3, [vp-content] h4, [vp-content] h5, [vp-content] h6'
   */
  selector?: string
  /**
   * Ignore specific elements within the header.
   *
   * The Array of `CSS Selector`
   *
   * @default []
   */
  ignore?: string[]
  /**
   * The levels of the headers
   *
   * - `false`: No headers.
   * - `number`: only headings of that level will be displayed.
   * - `[number, number]: headings level tuple, where the first number should be less than the second number, for example, `[2, 4]` which means all headings from `<h2>` to `<h4>` will be displayed.
   * - `deep`: same as `[2, 6]`, which means all headings from `<h2>` to `<h6>` will be displayed.
   *
   * @default 2
   */
  levels?: HeaderLevels
}
```

**Result:**

```ts
interface PageHeader {
  /**
   * The level of the header
   *
   * `1` to `6` for `<h1>` to `<h6>`
   */
  level: number
  /**
   * The title of the header
   */
  title: string
  /**
   * The slug of the header
   *
   * Typically the `id` attr of the header anchor
   */
  slug: string
  /**
   * Link of the header
   *
   * Typically using `#${slug}` as the anchor hash
   */
  link: string
  /**
   * The children of the header
   */
  children: MarkdownItHeader[]
}

export type HeaderLevels = number | 'deep' | false | [number, number]

export type HeaderItem = Omit<PageHeader, 'children'> & {
  element: HTMLHeadingElement
  children?: HeaderItem[]
}
```

::: details Examples

```ts
onMounted(() => {
  const headers = getHeaders({
    selector: '[vp-content] :where(h1,h2,h3,h4,h5,h6)',
    levels: [2, 3], // only h2 and h3
    ignore: ['.badge'], // ignore the <Badge /> within the header
  })
  console.log(headers)
})
```

:::

### isKeyMatched

Check if a keyboard event matches the specified hotkeys.

```ts
export const isKeyMatched: (
  event: KeyboardEvent,
  hotKeys: (KeyOptions | string)[],
) => boolean
```

**Params:**

* `event`: The keyboard event to check
* `hotKeys`: An array of hotkey definitions, which can be either a string (just the key) or a `KeyOptions` object

**KeyOptions Interface:**

```ts
interface KeyOptions {
  key: string
  ctrl?: boolean
  shift?: boolean
  alt?: boolean
}
```

**Returns:**

* `boolean`: Whether any of the hotkeys match the event

::: details Example

```ts
import { isKeyMatched } from '@vuepress/helper/client'

document.addEventListener('keydown', (event) => {
  // Check if Escape key is pressed
  if (isKeyMatched(event, ['Escape'])) {
    console.log('Escape key pressed')
  }

  // Check if Ctrl+S is pressed
  if (isKeyMatched(event, [{ key: 's', ctrl: true }])) {
    console.log('Ctrl+S pressed')
    event.preventDefault()
  }

  // Check for multiple possible hotkeys
  if (isKeyMatched(event, ['Enter', { key: ' ', shift: true }])) {
    console.log('Either Enter or Shift+Space was pressed')
  }
})
```

:::

### isSlotContentEmpty

Check whether a slot's content is currently empty.

```ts
export const isSlotContentEmpty: (normalizedSlotContent: SlotContent) => boolean
```

**Params:**

* `normalizedSlotContent`: The normalized slot content, which should be the result of the slot function

**Returns:**

* `boolean`: `true` if the slot content is empty, `false` otherwise

::: details Example

```ts
import { isSlotContentEmpty } from '@vuepress/helper/client'
import { useSlots } from 'vue'

const slots = useSlots()

// Check if default slot is empty
const isDefaultSlotEmpty = isSlotContentEmpty(slots.default?.())

// Conditionally render based on slot content
const renderContent = () => {
  if (!isSlotContentEmpty(slots.header?.())) {
    // Render header content
  }

  // Rest of the component
}
```

:::

### wait

Wait for a given time.

```ts
export const wait: (ms: number) => Promise<void>
```

**Params:**

* `ms`: Wait time in milliseconds

**Returns:**

* `Promise<void>`: A promise that resolves after the given time

::: details Example

```ts
import { wait } from '@vuepress/helper/client'

const handleOperation = async () => {
  // Do something
  console.log('Operation started')

  // Wait for 1 second
  await wait(1000)

  // Continue after waiting
  console.log('Operation continued after 1 second')
}

// Using in an animation sequence
const animateSequence = async () => {
  element1.classList.add('animate')
  await wait(500)

  element2.classList.add('animate')
  await wait(300)

  element3.classList.add('animate')
}
```

:::

## Component

### FadeInExpandTransition

Provides fade-in transition effects when block-level elements expand, supporting both `height` or `width` properties.

**Props:**

```ts
interface FadeInExpandTransitionProps {
  /**
   * Whether to group transitions
   */
  group?: boolean
  /**
   * Transition mode
   */
  mode?: 'default' | 'in-out' | 'out-in'

  /**
   * Whether to switch to the transition of `width`
   *
   * @default false
   */
  width?: boolean

  appear?: boolean
  onLeave?: () => void
  onAfterEnter?: () => void
  onAfterLeave?: () => void
}
```

**Import Styles:**

Transition animations require importing the following CSS files as needed:

* `@vuepress/helper/transition/fade-in-height-expand.css` - `height` transition animation

* `@vuepress/helper/transition/fade-in-width-expand.css` - `width` transition animation

::: tip Only one CSS file needs to be imported

:::

**Usage:**

```vue
<script setup lang="ts">
import { FadeInExpandTransition } from '@vuepress/helper/client'
import { ref } from 'vue'

import '@vuepress/helper/transition/fade-in-height-expand.css'
// import '@vuepress/helper/transition/fade-in-width-expand.css'

const expand = ref(false)
</script>

<template>
  <button type="button" @click="expand = !expand">
    {{ expand ? 'Collapse' : 'Expand' }}
  </button>

  <FadeInExpandTransition>
    <div v-show="expand">
      <p>Content</p>
    </div>
  </FadeInExpandTransition>
</template>
```

---

---
url: /tools/helper/node/bundler.md
---
# Bundler Related

Bundler functions for appending or modifying bundler options in theme and plugins.

These functions are only available via `@vuepress/helper`.

::: tip

All functions should be called in `extendsBundlerOptions` lifecycle hook.

We are omitting that in examples. The actual code should be like this:

```js
// import functions you need
import { addCustomElement } from '@vuepress/helper'

export const yourPlugin = {
  // ...
  extendsBundlerOptions: (bundlerOptions, app) => {
    // add them here
    addCustomElement(bundlerOptions, app, 'my-custom-element')
  },
}
```

:::

## Common methods

### getBundlerName

Get current bundler name.

```ts
export const getBundlerName: (app: App) => string
```

::: details Example

```ts
// @vuepress/bundler-vite
getBundlerName(app) === 'vite' // true
// @vuepress/bundler-webpack
getBundlerName(app) === 'webpack' // true
```

:::

### addCustomElement

Add a custom element declaration to the current bundler.

```ts
/**
 * Add tags as customElement
 *
 * @param bundlerOptions VuePress Bundler config
 * @param app VuePress Node App
 * @param customElements tags recognized as custom element
 */
export const addCustomElement: (
  bundlerOptions: unknown,
  app: App,
  customElement: RegExp | string[] | string,
) => void
```

::: details Example

```ts
import { addCustomElement } from '@vuepress/helper'

addCustomElement(bundlerConfig, app, 'my-custom-element')
addCustomElement(bundlerOptions, app, [
  'custom-element1',
  'custom-element2',
  // all tags start with `math-`
  /^math-/,
])
```

:::

### customizeDevServer

Provides contents for specific path in dev server.

```ts
export interface DevServerOptions {
  /**
   * Path to be responded
   */
  path: string
  /**
   * Respond function
   */
  response: (request?: IncomingMessage) => Promise<Buffer | string>

  /**
   * error msg
   */
  errMsg?: string
}

/**
 * Handle specific path when running VuePress Dev Server
 *
 * @param bundlerOptions VuePress Bundler config
 * @param app VuePress Node App
 * @param path Path to be responded
 * @param response respond function
 * @param errMsg error msg
 */
export const customizeDevServer: (
  bundlerOptions: unknown,
  app: App,
  {
    errMsg = 'The server encountered an error',
    response,
    path,
  }: CustomServerOptions,
) => void
```

::: details Example

```ts
import { useCustomDevServer } from '@vuepress/helper'

// handle `/api/` path
useCustomDevServer(bundlerOptions, app, {
  path: '/api/',
  response: async () => getData(),
  errMsg: 'Unexpected api error',
})
```

:::

## Vite Related

* addViteOptimizeDepsInclude

  Add modules to Vite `optimizeDeps.include` list

  ::: tip

  If a package meets one of the following conditions, you should consider adding it here.

  * It's in CJS format
  * It's dependencies include CJS package
  * It's dynamically imported via `import()`

  :::

* addViteOptimizeDepsExclude

  Add modules to Vite `optimizeDeps.exclude` list

  ::: tip If a package and its dependencies are all pure ESM packages, you should consider adding it here.

  :::

* addViteSsrExternal

  Add modules to Vite `ssr.external` list

  ::: tip If a package is a pure ESM package and does not use aliases or define variables, you should consider adding it here.

  :::

* addViteSsrNoExternal

  Add modules to Vite `ssr.noExternal` list

  ::: warning If an alias or define is used within a package, you must add it here.

  :::

  ```ts
  /**
   * Add modules to Vite `optimizeDeps.include` list
   */
  export const addViteOptimizeDepsInclude: (
    bundlerOptions: unknown,
    app: App,
    module: string[] | string,
  ) => void

  /**
   * Add modules to Vite `optimizeDeps.exclude` list
   */
  export const addViteOptimizeDepsExclude: (
    bundlerOptions: unknown,
    app: App,
    module: string[] | string,
  ) => void

  /**
   * Add modules to Vite `ssr.external` list
   */
  export const addViteSsrExternal: (
    bundlerOptions: unknown,
    app: App,
    module: string[] | string,
  ) => void

  /**
   * Add modules to Vite `ssr.noExternal` list
   */
  export const addViteSsrNoExternal: (
    bundlerOptions: unknown,
    app: App,
    module: string[] | string,
  ) => void
  ```

  ::: details Examples

  ```ts
  import {
    addViteOptimizeDepsExclude,
    addViteOptimizeDepsInclude,
    addViteSsrExternal,
    addViteSsrNoExternal,
  } from '@vuepress/helper'

  addViteOptimizeDepsInclude(bundlerOptions, app, ['vue', 'vue-router'])
  addViteOptimizeDepsExclude(bundlerOptions, app, 'packageA')
  addViteSsrNoExternal(bundlerOptions, app, ['vue', 'vue-router'])
  addViteSsrExternal(bundlerOptions, app, 'packageA')
  ```

  :::

* addViteConfig

  A function for you to add vite config

  ```ts
  export const addViteConfig: (
    bundlerOptions: unknown,
    app: App,
    config: Record<string, unknown>,
  ) => void
  ```

  ::: details Example

  ```ts
  import { addViteConfig } from '@vuepress/helper'

  addViteConfig(bundlerOptions, app, {
    build: {
      charset: 'utf8',
    },
  })
  ```

  :::

* mergeViteConfig

  A function for you to merge vite config.

  ::: warning

  Your users may choose to use other bundler so it's pretty bad to declare vite as deps!

  :::

  ```ts
  export const mergeViteConfig: (
    defaults: Record<string, any>,
    overrides: Record<string, any>,
  ) => Record<string, any>
  ```

  ::: details Example

  ```ts
  import { mergeViteConfig } from '@vuepress/helper'

  config.viteOptions = mergeViteConfig(config.viteOptions, {
    build: {
      charset: 'utf8',
    },
  })
  ```

  :::

## Webpack Related

* chainWebpack

  Chain webpack config.

  ```ts
  export const chainWebpack: (
    bundlerOptions: unknown,
    app: App,
    chainWebpack: (
      config: WebpackChainConfig,
      isServer: boolean,
      isBuild: boolean,
    ) => void,
  ) => void
  ```

  ::: details Example

  ```ts
  import { chainWebpack } from '@vuepress/helper'

  chainWebpack(bundlerOptions, app, (config, isServer, isBuild) => {
    // do some customize here
  })
  ```

  :::

* configWebpack

  Config Webpack

  ```ts
  export const configWebpack: (
    bundlerOptions: unknown,
    app: App,
    configureWebpack: (
      config: WebpackConfiguration,
      isServer: boolean,
      isBuild: boolean,
    ) => void,
  ) => void
  ```

  ::: details Example

  ```ts
  import { configWebpack } from '@vuepress/helper'

  configWebpack(bundlerOptions, app, (config, isServer, isBuild) => {
    // do some customize here
  })
  ```

  :::

---

---
url: /tools/helper/node/locales.md
---
# Locales Related

These functions are only available in `@vuepress/helper`.

## getFullLocaleConfig

A helper function to get full locale config from built-in locale info and user configuration.

```ts
export interface GetLocaleConfigOption<T extends LocaleData> {
  app: App
  default: DefaultLocaleInfo<T>
  config?: LocaleConfig<T> | undefined
  name?: string
}

export const getFullLocaleConfig: <T extends LocaleData>(
  options: GetLocaleConfigOption<T>,
) => ExactLocaleConfig<T>
```

* The `app` parameter is the VuePress Node app instance.

* The `default` parameter is the default locale info, where this should be an array of locale info settings.

  Each locale info setting should be an tuple with two elements:

  * The first element are an array of lang code that the locale info setting belongs to.
  * The second element are the locale info setting.

  An example of `default` parameter:

  ```ts
  const defaultLocaleInfo = [
    [
      ['en'],
      { title: 'VuePress', description: 'Vue-powered Static Site Generator' },
    ],
    [
      ['zh', 'zh-CN'],
      { title: 'VuePress', description: 'Vue 驱动的静态网站生成器' },
    ],
    [['zh-TW'], { title: 'VuePress', description: 'Vue 驅動的靜態網站生成器' }],
  ]
  ```

* The `config` parameter is the user locale config, which is optional.

  It should be an object with localePath as key and partial locale info setting as value.

  An example of `config` parameter:

  ```ts
  const userLocaleConfig = {
    '/zh/': { description: '由 Vue 驱动的静态网站生成器' },
    '/zh-TW/': { description: '由 Vue 驅動的靜態網站生成器' },
  }
  ```

* The `name` parameter is the plugin name, which is optional, only used for logging.

The function will automatically merge the default locale info and user locale config, and return the final locale config, where the user locale config will override the default locale info.

The default locale info will be chosen based on the current language of each locale in site config, and when a locale's lang code is not found in the default locale info, it will fallback to the first one of the following that exists:

* locale info of `en-US`
* locale info of `en`
* locale info of first element in the default locale info

---

---
url: /tools/helper/node/page.md
---
# Page Related

Common information generator for pages.

These functions are only available via `@vuepress/helper`.

## getPageExcerpt

Get the excerpt of the page.

```ts
export interface PageExcerptOptions {
  /**
   * Excerpt separator
   *
   * @default "<!-- more -->"
   */
  separator?: string

  /**
   * Length of excerpt
   *
   * @description Excerpt length will be the minimal possible length reaching this value
   *
   * @default 300
   */
  length?: number

  /**
   * Tags which is considered as custom elements
   *
   * @description This is used to determine whether a tag is a custom element since all unknown tags are removed in excerpt.
   */
  isCustomElement?: (tagName: string) => boolean

  /**
   * Whether keep page title (first h1) in excerpt
   *
   * @default false
   */
  keepPageTitle?: boolean

  /**
   * Whether preserve tags like line numbers and highlight lines for code blocks
   *
   * @default false
   */
  keepFenceDom?: boolean
}

export const getPageExcerpt: (
  app: App,
  page: Page,
  options?: PageExcerptOptions,
) => string
```

## getPageText

Get plain text of the page.

```ts
export interface PageTextOptions {
  /**
   * Whether convert text to single line content
   *
   * @default false
   */
  singleLine?: boolean

  /**
   * Length of text
   *
   * @description Text length will be the minimal possible length reaching this value
   *
   * @default 300
   */
  length?: number

  /**
   * Tags to be removed
   *
   * @description Table and code blocks are removed by default.
   *
   * @default ['table', 'pre']
   */
  removedTags?: string[]
}

export const getPageText: (
  app: App,
  page: Page,
  options?: PageTextOptions,
) => string
```

---

---
url: /tools/helper/shared.md
---
# Shared Methods

The following functions are available on both Node.js and Client.

These functions are available in `@vuepress/helper`, `@vuepress/helper/client`, and `@vuepress/helper/shared`.

## Data Related

Encode/decode and zip/unzip data.

This is useful in markdown plugins when you want to encode string content and pass it to the component through props.

You may simply achieve this with `encodeURIComponent` and `decodeURIComponent`, but it can be very large if the content contains lots of special characters.

So we provide `encodeData` and `decodeData` to zip and encode content.

```ts
export const encodeData: (
  data: string,
  level: DeflateOptions['level'] = 6,
) => string

export const decodeData: (compressed: string) => string
```

::: details

```ts
const content = `
{
  "type": "bar",
  "data": {
    "labels": ["Red", "Blue", "Yellow", "Green", "Purple", "Orange"],
    "datasets": [
      {
        "label": "# of Votes",
        "data": [12, 19, 3, 5, 2, 3],
        "backgroundColor": [
          "rgba(255, 99, 132, 0.2)",
          "rgba(54, 162, 235, 0.2)",
          "rgba(255, 206, 86, 0.2)",
          "rgba(75, 192, 192, 0.2)",
          "rgba(153, 102, 255, 0.2)",
          "rgba(255, 159, 64, 0.2)"
        ],
        "borderColor": [
          "rgba(255, 99, 132, 1)",
          "rgba(54, 162, 235, 1)",
          "rgba(255, 206, 86, 1)",
          "rgba(75, 192, 192, 1)",
          "rgba(153, 102, 255, 1)",
          "rgba(255, 159, 64, 1)"
        ],
        "borderWidth": 1
      }
    ]
  },
  "options": {
    "scales": {
      "y": {
        "beginAtZero": true
      }
    }
  }
}
`

const prop = encodeData(content) // "eJyNUsFOwzAMve8rrHABKZqWlg5WxAE4cARxAMHEIV1NmQhNlaaCCe3fcdKtW0sLWGpjxy/v+UV512mlcIyfhTa2hHP4GgHYVYExsEQaxqlMpZWxbwAomaAqY5izO0wZB3apKnTrIyqlP1x2bRBzl9xWplC+eWNkniF7dmw1X4nWsfgaNtwNP2kfgH6Be22x9CPUUQ8yFwEHMeMQcog4UBFuiF0kcvGWGV3l6ZVW2uw0XDCTJfIwiOjYjAhESIcn4+BoT2MLio6pP6V+EBJ6AOSZgsmUwyl9A6ATwoiZn3lYTkTkRkycnuP8TU9ENPqUxuuA9i9BmxTNPy9A/G2/F9I23wtpW++FdIwPKzW2W5Afph+WqX2NQWz313XicT7XhV3qnB5f/ejKhVTYVACrXUqUmC3zC/uERsdgTYUdVr/Qb302+gZxe7S/"

decodeData(prop) // will be the original content

// if you use `encodeURIComponent`, it will be much longer
encodeURIComponent(content) // '%0A%7B%0A%20%20%22type%22%3A%20%22bar%22%2C%0A%20%20%22data%22%3A%20%7B%0A%20%20%20%20%22labels%22%3A%20%5B%22Red%22%2C%20%22Blue%22%2C%20%22Yellow%22%2C%20%22Green%22%2C%20%22Purple%22%2C%20%22Orange%22%5D%2C%0A%20%20%20%20%22datasets%22%3A%20%5B%0A%20%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%22label%22%3A%20%22%23%20of%20Votes%22%2C%0A%20%20%20%20%20%20%20%20%22data%22%3A%20%5B12%2C%2019%2C%203%2C%205%2C%202%2C%203%5D%2C%0A%20%20%20%20%20%20%20%20%22backgroundColor%22%3A%20%5B%0A%20%20%20%20%20%20%20%20%20%20%22rgba(255%2C%2099%2C%20132%2C%200.2)%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22rgba(54%2C%20162%2C%20235%2C%200.2)%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22rgba(255%2C%20206%2C%2086%2C%200.2)%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22rgba(75%2C%20192%2C%20192%2C%200.2)%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22rgba(153%2C%20102%2C%20255%2C%200.2)%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22rgba(255%2C%20159%2C%2064%2C%200.2)%22%0A%20%20%20%20%20%20%20%20%5D%2C%0A%20%20%20%20%20%20%20%20%22borderColor%22%3A%20%5B%0A%20%20%20%20%20%20%20%20%20%20%22rgba(255%2C%2099%2C%20132%2C%201)%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22rgba(54%2C%20162%2C%20235%2C%201)%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22rgba(255%2C%20206%2C%2086%2C%201)%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22rgba(75%2C%20192%2C%20192%2C%201)%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22rgba(153%2C%20102%2C%20255%2C%201)%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22rgba(255%2C%20159%2C%2064%2C%201)%22%0A%20%20%20%20%20%20%20%20%5D%2C%0A%20%20%20%20%20%20%20%20%22borderWidth%22%3A%201%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%5D%0A%20%20%7D%2C%0A%20%20%22options%22%3A%20%7B%0A%20%20%20%20%22scales%22%3A%20%7B%0A%20%20%20%20%20%20%22y%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%22beginAtZero%22%3A%20true%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A'
```

:::

## Type Helper

* `isDef(x)`: Check if `x` is defined.
* `isBoolean(x)`: Check if `x` is a boolean.
* `isString(x)`: Check if `x` is a string.
* `isNumber(x)`: Check if `x` is a number.
* `isPlainObject(x)`: Check if `x` is a plain object.
* `isArray(x)`: Check if `x` is an array.
* `isFunction(x)`: Check if `x` is a function.
* `isRegExp(x)`: Check if `x` is a regular expression.

## String Related

* `startsWith(a, b)`: Check if string `a` starts with string `b`.
* `endsWith(a, b)`: Check if string `a` ends with string `b`.

Return `false` if `a` is not a string.

## Object Related

* `keys(x)`: Return an array of keys of object `x`.
* `values(x)`: Return an array of values of object `x`.
* `entries(x)`: Convert object `x` to an array of key-value pairs.
* `fromEntries(x)`: Convert an array of key-value pairs `x` to an object.
* `deepAssign(x, y, ...)`: A deep version of `Object.assign`.

  ::: details Example

  ```ts
  // or @vuepress/helper/client
  import { deepAssign } from '@vuepress/helper'

  const defaultOptions = {
    optionA: {
      optionA1: 'defaultOptionA1',
      optionA2: 'defaultOptionA2',
      optionA3: 'defaultOptionA3',
    },
    optionB: true,
    optionC: 'optionC',
  }

  const userOptions = {
    optionA: {
      optionA1: 'optionA1',
      optionA2: 'optionA2',
    },
    optionB: false,
  }

  deepAssign(defaultOptions, userOptions)
  // {
  //   optionA: {
  //     optionA1: "optionA1",
  //     optionA2: "optionA2",
  //     optionA3: "defaultOptionA3",
  //   },
  //   optionB: false,
  //   optionC: "optionC",
  // }
  ```

  :::

## Date Related

* `getDate(x)`: Convert input `x` to a date. It can support `Date`, timestamp, and date string. The support range of date string depends on the `Date.parse` support range of the environment. Return `null` when it cannot be converted to a date.

  ::: details Example

  ```ts
  getDate('2021-01-01') // a Date object represents 2021-01-01
  getDate(1609459200000) // a Date object represents 2021-01-01
  getDate('2021-01-01T00:00:00.000Z') // a Date object represents 2021-01-01
  getDate('2021/01/01') // a Date object represents 2021-01-01 (might be null in some browsers)
  getDate('invalid date') // null
  getDate(undefined) // null
  getDate(-32) // null
  ```

  :::

* `dateSorter`: Sort the values that can be converted to dates from new to old, and the values that cannot be converted to dates will be at the end.

  ::: details Example

  ```ts
  const arr = [
    '2020-01-01',
    1609459200000,
    '2022-01-01T00:00:00.000Z',
    '2023/01/01',
    'invalid date',
    undefined,
    -32,
  ]

  arr.sort(dateSorter)
  // [
  //   '2023/01/01',
  //   '2022-01-01T00:00:00.000Z',
  //   1609459200000,
  //   '2020-01-01',
  //   'invalid date',
  //   undefined,
  //   -32,
  // ]
  ```

## Link Related

* `isLinkHttp(x)`: Check if `x` is a valid HTTP URL.
* `isLinkWithProtocol(x)`: Check if `x` is a valid URL with protocol.
* `isLinkExternal(x)`: Check if `x` is a valid external URL.
* `isLinkAbsolute(x)`: Check if `x` is a valid absolute URL.
* `isLinkRelative(x)`: Check if `x` is not absolute or external URL.
* `ensureEndingSlash(x)`: Ensure `x` ends with a slash.
* `ensureLeadingSlash(x)`: Ensure `x` starts with a slash.
* `removeEndingSlash(x)`: Ensure `x` does not end with a slash.
* `removeLeadingSlash(x)`: Ensure `x` does not start with a slash.

---

---
url: /tools/helper/style.md
---
# Styles

The following styles are provided.

## Normalize

`@vuepress/helper/normalize.css` is a CSS file that normalizes the default styles of the browser. It is recommended to import it in community themes.

## Transitions

`@vuepress/helper/transition/*.css` is a collection of CSS files that provide transitions for elements. It is recommended to import for use as needed in community themes.

* `fade-in.css`
* `fade-in-up.css`
* `fade-in-down.css`
* `fade-in-left.css`
* `fade-in-right.css`
* `fade-in-scale-up.css`
* `slide-in-up.css`
* `slide-in-down.css`
* `slide-in-left.css`
* `slide-in-right.css`

**Usage:**

```vue
<script setup>
import { ref } from 'vue'
import '@vuepress/helper/transition/fade-in.css'

const show = ref(true)
</script>

<template>
  <Transition name="fade-in">
    <div v-show="show">...</div>
  </Transition>
</template>
```

**CSS Variables:**

```css
:root {
  /* general transitions variables */

  --transition-ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
  --transition-ease-out: cubic-bezier(0, 0, 0.2, 1);
  --transition-ease-in: cubic-bezier(0.4, 0, 1, 1);
  --transition-duration: 0.3s;
  --transition-enter-duration: var(--transition-duration);
  --transition-leave-duration: 0.2s;
  --transition-delay: 0.1s;

  /* specific transitions variables */

  --transition-fade-in-up-offset: 10px;
  --transition-fade-in-down-offset: -10px;
  --transition-fade-in-left-offset: 10px;
  --transition-fade-in-right-offset: -10px;

  --transition-fade-in-scale-up-scale: 0.9;
  --transition-fade-in-scale-up-duration: 0.2s;
  --transition-fade-in-scale-up-origin: inherit;

  --transition-slide-in-up-offset: 100%;
  --transition-slide-in-down-offset: -100%;
  --transition-slide-in-left-offset: 100%;
  --transition-slide-in-right-offset: -100%;
}
```