# Plugins

---

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

---

---
url: /ecosystem/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 increasingly rely on website information, but face a critical limitation: context windows are too small to handle most websites in their entirety. Converting complex HTML pages with navigation, ads, and JavaScript into LLM-friendly plain text is both difficult and imprecise.

While websites serve both human readers and LLMs, the latter benefit from more concise, expert-level information gathered in a single, accessible location. This is particularly important for use cases like development environments, where LLMs need quick access to programming documentation and APIs.

Add a `/llms.txt` Markdown file to the website to provide LLM-friendly content. This file includes brief background information, guidelines, and links to detailed Markdown files.

### Plugin Features

The plugin retrieves all Markdown files from your document source directory and converts them into LLM-friendly plain text files.

```txt
📂 .vuepress/dist
├── ...
├── llms.txt
├── llms-full.txt
├── markdown-examples.html
└── markdown-examples.md
```

Click the link below to view the `llms.txt` file of this documentation site:

* llms.txt
* llms-full.txt

::: tip

The plugin only generates the `llms.txt` file, along with other LLM-friendly documentation files, during the production build—that is, when the `vuepress build` command is executed—and outputs them to the `.vuepress/dist` directory.

:::

### `llms.txt`

The `llms.txt` file contains the **title**, **description**, **details (optional)**, and **Table of Contents (TOC)** for the site.

The default format is as follows:

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

> Description

Details (Optional)

## Table of Contents

- [title](url): description
- [title](url): description
- …
```

* **Site Title**: Values are determined in the following order:
  1. `llmsTxtTemplateGetter.title`
  2. `heroText` in homepage frontmatter
  3. Current locale's [title](https://v2.vuepress.vuejs.org/reference/config.html#locales) in VuePress config file
  4. [title](https://v2.vuepress.vuejs.org/reference/config.html#title) in VuePress config file
  5. Page title of locale homepage (locale `README.md`)

* **Site Description**: Values are determined in the following order:
  1. `llmsTxtTemplateGetter.description`
  2. `tagline` in locale homepage frontmatter
  3. Current locale's [description](https://v2.vuepress.vuejs.org/reference/config.html#locales) in VuePress config file
  4. [description](https://v2.vuepress.vuejs.org/reference/config.html#description) in VuePress config file
  5. `frontmatter.description` in locale homepage (locale `README.md`)

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

* **Table of Contents (TOC)**: Formatted as `- [title](url): description`, where `description` is taken from `frontmatter.description`. If it does not exist, only `- [title](url)` is displayed.

  By default, the plugin only generates first-level TOC, and the default getter function is as follows:

  ```ts
  import { generateTOCLink } from '@vuepress/plugin-llms'

  const defaultTOCGetter = (pages, state) =>
    pages.map((page) => generateTOCLink(page, state)).join('\n')
  ```

  You can customize it to generate a multi-level TOC by setting a custom function with the [`llmsTxtTemplateGetter`](#llmstxttemplategetter) option.

### `llms-full.txt`

`llms-full.txt` contains **links**, **descriptions**, and **Markdown-formatted content** for each page.

Its format is as follows:

```txt title="llms-full.txt"
---
url: url
description: optional description
---

page's Markdown-formatted content

---

---
url: url
description: optional description
---

page's Markdown-formatted content

…
```

The plugin directly merges the content of the Markdown files in the document source directory into `llms-full.txt` so that LLMs can read and analyze it.

### Page Contents

The plugin generates accessible Markdown files for each page in the format `${url}.md`. For example, `/guide/quick-start.html` will produce a corresponding `/guide/quick-start.md` file.

## Options

### llmsTxt

* Type: `boolean`

* Default: `true`

* Details: Whether to generate the `llms.txt` file, which contains a list of sections with corresponding links.

### llmsFullTxt

* Type: `boolean`

* Default: `true`

* Details: Whether to generate the `llms-full.txt` file which contains all the documentation in one file.

### llmsPageTxt

* Type: `boolean`

* Default: `true`

* Details: Whether to generate an LLM-friendly version of the documentation for each page on the website.

### stripHTML

* Type: `boolean`

* Default: `true`

* Details: Whether to strip HTML tags from Markdown files.

### filter

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

* Default: `() => true`

* Details:

  Page filter function. When it returns `true`, the page will be included in `llms.txt`, otherwise it will be excluded.

  Pages that are disabled by `frontmatter.llmstxt` or not generated from Markdown files will be excluded anyway.

### domain

* Type: `string`

* Default: `''`

* Details:

  The domain that will be prepended to URLs in `llms.txt` and other files.

  Domain attachment is not yet standardized (since it depends on whether the AI can resolve the relative paths that are currently there), but you can add it if needed.

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

### locale

* Types: `string | 'all'`

* Default: `'/'`

* Details:

  The locale of the site to generate. If not set, the plugin will use the default locale of the VuePress site. If you set it to `'all'`, the plugin will generate `llms.txt` for all locales.

  This option is useful when you have multiple locales and want to generate `llms.txt` for a specific locale, which should have the best documentation quality.

  Also, if you have many self-defined concepts that LLMs cannot understand or translate correctly, you should consider generating `llms.txt` for each locale to avoid confusion with different representations coming from LLM translation and the original documentation.

### llmsTxtTemplate

* Types: `string`

* Default:

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

  {description}

  {details}

  ## Table of Contents

  {toc}`
  ```

* Details:

  A custom template for the `llms.txt` file, allowing for a personalized order of elements.

  By default, `{title}`, `{description}`, `{details}`, and `{toc}` are available.

### 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:

  Custom variables for the [`llmsTxtTemplate`](#llmstxttemplate).

  With this option you can add and override template variables.

  For example, setting a customized title for `llms.txt`:

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

  Or adding a custom variable `foo` to the template:

  ```ts
  llmsPlugin({
    llmsTxtTemplate: '# {title}\n\n{foo}',
    llmsTxtTemplateGetter: {
      foo: 'My foo',
    },
  })
  ```

  You can also add getter functions to the template:

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

## Frontmatter

The following `frontmatter` will be used in the plugin.

### title {#frontmatter-title}

* Types: `string`
* Details:

  On the homepage (`README.md`), it serves as an alternative title for `llms.txt`.

  On other pages, it functions as the page title.

### description {#frontmatter-description}

* Types: `string`
* Details:

  On the homepage (`README.md`), as an alternative description for `llms.txt`.

  On other pages, as the page description.

  It is recommended to add concise and clear descriptions to the page, providing key information for LLMs to understand it.

### heroText {#frontmatter-herotext}

* Types: `string`

* Details:

  Being read from homepage (locale `README.md`) only, as title of `llms.txt`.

### tagline {#frontmatter-tagline}

* Types: `string`

* Details:

  Being read from homepage (locale `README.md`) only, as description of `llms.txt`.

### details {#frontmatter-details}

* Types: `string`
* Details:

  Being read from homepage (locale `README.md`) only, as details of `llms.txt`.

### llmstxt

* Types: `boolean`

* Default: `true`

* Details: Whether the current page should be included in `llms.txt`.

## Others

It is recommended to configure redirects so that AI can use addresses with `.md` and `.txt` extensions.

For example, in `Netlify`, configure the following in `public/_redirects`:

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

Options syntax documentation: <https://docs.netlify.com/routing/redirects>

---

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

---

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

Integrate [Baidu Analytics](https://tongji.baidu.com/) into VuePress.

::: tip

Do not enable [SPA mode in Baidu Analytics](https://tongji.baidu.com/web/help/article?id=324\&type=0). The plugin will report page view events correctly.

:::

## 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
    }),
  ],
}
```

### Reporting Events

The plugin automatically reports page view events on page visits and route changes.

A global `_hmt` array is available on the `window` object for [custom event reporting](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).

## Options

### id

* Type: `string`
* Required: Yes
* Details: Baidu Analytics tracking ID, which is the query parameter in the `hm.js` URL.

---

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

Integrate [Google Analytics](https://analytics.google.com/) into VuePress.

This plugin imports [gtag.js](https://developers.google.com/analytics/devguides/collection/gtagjs) to enable [Google Analytics 4](https://support.google.com/analytics/answer/10089681) 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 [automatically collects some events](https://support.google.com/analytics/answer/9234069), such as `page_view`, `first_visit`, etc.

If you only need to collect basic site data, simply set the [Measurement ID](#id) correctly.

After using this plugin, the global `gtag()` function is available on the `window` object for [custom event reporting](https://developers.google.com/analytics/devguides/collection/ga4/events).

## Options

### id

* Type: `string`

* Required: Yes

* Details:

  Google Analytics 4 Measurement ID, which should start with `'G-'`.

  You can follow the instructions [here](https://support.google.com/analytics/answer/9539598) to find your Measurement ID. Note the difference between Google Analytics 4 Measurement ID ("G-" ID) and Universal Analytics Tracking ID ("UA-" ID).

* Example:

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

### debug

* Type: `boolean`

* Details:
  Set to `true` to enable sending events to DebugView. [See more information on DebugView](https://support.google.com/analytics/answer/7201382).

* Example:

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

---

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

Integrate [Umami Analytics](https://umami.is/) into VuePress.

## 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
    }),
  ],
}
```

You can use [Umami Cloud](https://cloud.umami.is/login) or [Self-host Umami](https://umami.is/docs/install).

### Reporting Events

The plugin automatically reports page view events on page visits and route changes.

A global `umami` object is available on the `window` object, and you can call `umami.track` for [custom tracking](https://umami.is/docs/tracker-functions).

## Options

### id

* Type: `string`
* Required: Yes
* Details: The website ID from Umami Analytics

### link

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

### autoTrack

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

  By default, Umami tracks all pageviews and events automatically.

  Set to `false` to disable automatic tracking and use manual tracking functions.

### cache

* Type: `boolean`
* Details:

  Cache data to improve tracking script performance.

  Note: This will use session storage so you may need to inform your users.

### domains

* Type: `string[]`
* Details: Restrict tracking to specific domains only.

### hostUrl

* Type: `string`
* Default: `link`
* Details: Custom endpoint for sending tracking data.

---

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

---

---
url: /ecosystem/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: /ecosystem/plugins/blog/blog/config.md
---
# Config

## Plugin Options

### getInfo

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

  Function to extract article information from pages.

  Article info will be injected into route meta, making it available in client composables.

### filter

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

  Function to filter pages for blog articles.

  By default, all pages generated from Markdown files except homepage are included.

### 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: Function to convert strings to URL-friendly slugs for route registration.

### excerpt

* Type: `boolean`
* Default: `true`
* Reference: [Guide → Excerpt Generation](./guide.md#generating-excerpt)
* Details: Whether to generate excerpt for pages.

### excerptSeparator

* Type: `string`
* Default: `<!-- more -->`
* Reference:
  * [Guide → Excerpt Generation](./guide.md#generating-excerpt)
* Details: Separator for manual excerpt in content.

### excerptLength

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

  Target length for auto-generated excerpts.

  ::: tip

  Excerpt length will be the minimal possible length reaching this value.

  Set to `0` to disable auto excerpt generation.

  :::

### excerptFilter

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

  Function to filter pages for excerpt generation.

  ::: tip

  Use this to skip pages that don't need excerpt generation. For example, if users set `excerpt` or `description` in frontmatter, you may want to use them directly.

  :::

### isCustomElement

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

  Tags which is considered as custom elements.

  This is used to determine whether a tag is a custom element since all unknown tags are removed in excerpt.

### metaScope

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

  Key used when injecting info to route meta.

  ::: tip

  Setting to an empty key will inject to route meta directly instead of a field.

  :::

### hotReload

* Type: `boolean`
* Default: Whether using `--debug` flag
* Details:

  Whether enable hotReload in devServer.

  ::: tip To theme developers

  It's disabled by default because it does have performance impact in sites with a lot of categories and types. And it can slow down hotReload speed when editing Markdown.

  If users are adding or organizing your categories or tags, you may tell them to enable this, for the rest it's better to keep it disabled.

  Also, you can try to detect number of pages in users project and decide whether to enable it.

  :::

## Blog Category Config

Blog category config should be an array, while each item is controlling a "category" rule.

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

  /**
   * Function getting category from page
   */
  getter: (page: Page) => string[]

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

  /**
   * Path pattern of page to be registered
   *
   * @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
   */
  frontmatter?: (localePath: string) => Record<string, string>

  /**
   * Item page path pattern or custom function to be registered
   *
   * @description When filling in 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

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

## Blog Type Config

Blog type config should be an array, while each item is controlling a "type" rule.

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

  /**
   * A filter function to determine whether a page should be the type
   */
  filter: (page: Page) => boolean

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

  /**
   * Page path to be registered
   *
   * @default '/:key/'
   */
  path?: string

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

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

## Composition API

You can import the following API from `@vuepress/plugin-blog/client`.

* Blog category

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

  Argument `key` should be the category unique key.

  If no key is passed, the plugin will try to use the key in current path.

* Blog category

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

  Argument `key` should be the type unique key.

  If no key is passed, the plugin will try to use the key in current path.

Returning 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

  /**
   * Only available when current route matches an 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: /ecosystem/plugins/blog/blog/guide.md
---
# Guide

Adds blog functionality to VuePress themes with article collection, categorization, and excerpt generation.

## Article Collection

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

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

## Gathering Info

Set the `getInfo` option with a function that extracts article information from pages.

The plugin injects collected information into the `routeMeta` field, making it available through 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 }) => {
        // drop those pages which is NOT generated from file
        if (!filePathRelative) return false

        // drop those pages in `archives` directory
        if (filePathRelative.startsWith('archives/')) return false

        // drop those pages which do not use default layout
        if (frontmatter.home || frontmatter.layout) return false

        return true
      },

      getInfo: ({ frontmatter, title, git = {}, data = {} }) => {
        // get 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

Basically, you would want 2 types of collections in your blog:

* Category:

  "Category" means grouping articles with their labels.

  For example, each article may have "categories" and "tags".

* Type:

  "Type" means identifying articles with conditions.

  For example, you may want to describe some of your articles as diary.

After understanding the description of these 2 types, you can set the `category` and `type` options, each accepts an array, and each element represents a configuration.

Let's start with 2 examples here.

Imagine you are setting tags for each article with the `tag` field in page frontmatter. You want a tag mapping page in `/tag/` with `TagMap` layout, and group each tag list with tagName in `/tag/tagName` with `TagList` layout, you probably need a configuration like this:

```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 ...
  ],
}
```

Also, you may want to star some of your articles and display them to visitors. When you are setting `star: true` in frontmatter to mark them, you probably need a configuration like this to display them in the `/star/` path with `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 ...
  ],
}
```

See, setting these 2 types is easy. For full options, please see [Category Config](./config.md#blog-category-config) and [Type Config](./config.md#blog-type-config).

## Using Composition API in Client-side

When generating each page, the plugin will set the following information under `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
}
```

So you can invoke `useBlogCategory()` and `useBlogType()` directly, and the result will be the category or type bound to the current route.

Also, you can pass the `key` you want as an argument, then you will get information bound to that key.

So with the node side settings above, you can get information about "tag" and "star" in 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">
          
          <span class="category-num">
            
          </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"
      >
        
        <span class="category-num">
          
        </span>
      </RouteLink>
    </div>
    <div v-if="categoryMap.currentItems" class="article-wrapper">
      <div v-if="!categoryMap.currentItems.length">Nothing in here.</div>
      <article
        v-for="{ info, path } in categoryMap.currentItems"
        :key="path"
        class="article"
        @click="$router.push(path)"
      >
        <header class="title">
          
        </header>
        <hr />
        <div class="article-info">
          <span v-if="info.author" class="author"
            >Author: </span
          >
          <span v-if="info.date" class="date"
            >Date: </span
          >
          <span v-if="info.category" class="category"
            >Category: </span
          >
          <span v-if="info.tag" class="tag"
            >Tag: </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">
        
      </header>
      <hr />
      <div class="article-info">
        <span v-if="info.author" class="author">Author: </span>
        <span v-if="info.date" class="date"
          >Date: </span
        >
        <span v-if="info.category" class="category"
          >Category: </span
        >
        <span v-if="info.tag" class="tag">Tag: </span>
      </div>
      <div v-if="info.excerpt" class="excerpt" v-html="info.excerpt" />
    </article>
  </div>
  <div v-else>Nothing in here.</div>
</template>
```

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

## I18n Support

This plugin adds native i18n support, so your settings will be automatically applied to each language.

For example, if the user has the following locales config, and you are setting the "star" example above:

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

Then `/zh/star/` and `/star/` will both be available, and only articles under the correct locale will appear.

## Generating Excerpt

This plugin provides a built-in excerpt generator, which can be enabled by setting the `excerpt` option to `true`.

::: tip Excerpt introduction

An excerpt is an HTML fragment that is used to display a short description of an article in the blog list, so the excerpt has the following restrictions:

* It doesn't support any unknown tags (including all Vue components) and Vue syntax, so these contents will be removed when generating. If you have custom components (non-Vue components), set the `isCustomElement` option.
* Since the excerpt is an HTML fragment, you will not be able to import any images via relative paths or aliases, they will be removed directly. If you want to keep images, please use absolute paths based on `.vuepress/public` or full URLs to ensure they can be accessed in other places.

:::

The excerpt generator will try to find a valid excerpt separator from markdown contents, if it finds one, it will use content before the separator. The separator is default `<!-- more -->`, and you can customize it by setting the `excerptSeparator` option.

If it cannot find a valid separator, it will parse content from the beginning of the markdown file, and stop till its length reaches a preset value. The value is default `300`, and you can customize it by setting the `excerptLength` option.

To choose which page should generate excerpt, you can use the `excerptFilter` option.

::: tip Example

Normally you may want to use `frontmatter.description` if users set them, so you can let the filter function return `false` if `frontmatter.description` is not empty.

:::

---

---
url: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/plugins/blog/comment/guide.md
---
# Guide

## Configuration

Configure the plugin with its options and client config 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 Limitations

* **Plugin Options Only**: `provider`, locales, and resource-related options must be set in plugin options for tree-shaking optimization.

* **Client Config Only**: Function-based options must be set in client config as they cannot be serialized.

## Using Comments

The plugin registers a global `<CommentService />` component.

**For Users**: Use aliases and layout slots to insert the component. Recommended placement is after `<PageNav />`.

**For Theme Developers**: Insert the component in your theme layout.

### Comment Control

Control comments via plugin options or page frontmatter:

* **Global**: Set `comment: false` in plugin options to disable globally
* **Per Page**: Set `comment: true/false` in frontmatter to enable/disable locally
* **Custom ID**: Set `commentID` in frontmatter to customize comment storage identifier

## Available Providers

Choose from [Giscus](giscus/README.md), [Waline](waline/README.md), [Artalk](artalk/README.md), or [Twikoo](twikoo/README.md).

::: tip Recommendations

* **Developers**: Giscus (GitHub-based)
* **General Users**: Waline (full-featured)

:::

## Common Options

### provider&#x20;

* Type: `"Artalk" | "Giscus" | "Twikoo" | "Waline" | "None"`
* Default: `"None"`
* Details: Comment service provider.

### comment

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

---

---
url: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/plugins/blog/feed/channel.md
---
# Channel Config

The channel plugin option is used to config the feed channel.

## channel.title

* Type: `string`
* Default: `SiteConfig.title`

Channel title

## channel.link

* Type: `string`
* Default: Deployment link (generated by `options.hostname` and `context.base`)

Channel address

## channel.description

* Type: `string`
* Default: `SiteConfig.description`

Channel description

## channel.language

* Type: `string`

* Default:
  * `siteConfig.locales['/'].lang`
  * If the above is not provided, fall back to `"en-US"`

The language of the channel

## channel.copyright

* Type: `string`

* Default:
  * Try to read the `author.name` in channel options, and fall back to `Copyright by $author`

* Recommended to set manually: **Yes**

Channel copyright information

## channel.pubDate

* Type: `string` (must be a valid Date ISOString)
* Default: time when the plugin is called each time
* Recommended to set manually: **Yes**

Publish date of the Channel

## channel.lastUpdated

* Type: `string` (must be a valid Date ISOString)
* Default: time when the plugin is called each time

Last update time of channel content

## channel.ttl

* Type: `number`
* Recommended to set manually: **Yes**

The effective time of the content. It's the time to keep the cache after request without making new requests.

## channel.image

* Type: `string`
* Recommended to set manually: **Yes**

A picture presenting the channel. A square picture with a size not smaller than 512×512 is recommended.

## channel.icon

* Type: `string`
* Recommended to set manually: **Yes**

An icon representing a channel, a square picture, with not less than 128×128 in size. Transparent background color is recommended.

## channel.author

* Type: `FeedAuthor`
* Recommended to set manually: **Yes**

The 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`

Link to Websub. Websub requires a server backend, which is inconsistent with VuePress, so ignore it if there is no special need.

::: tip WebSub

For details, see [Websub](https://w3c.github.io/websub/#subscription-migration).

:::

---

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

## hostname

* Type: `string`
* Required: Yes

The domain name of the deployment site.

## atom

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

Whether to output Atom syntax files.

## json

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

Whether to output JSON syntax files.

## rss

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

Whether to output RSS syntax files.

## image

* Type: `string`

A large image/icon of the feed, probably used as banner.

## icon

* Type: `string`

A small icon of the feed, probably used as favicon.

## count

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

Set the maximum number of items in the feed. After all pages are sorted, the first `count` items will be intercepted.

If your site has a lot of articles, you may consider this option to reduce feed file size.

## preservedElements

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

Custom element or component which should be preserved in feed.

::: 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, used to filter feed items.

## 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,
    )
  ```

Custom sorter function for feed items.

The default sorting behavior is by file adding time coming from git (needs `@vuepress/plugin-git`).

::: tip

You should enable `@vuepress/plugin-git` to get the newest created pages as feed items. Otherwise, the feed items will be sorted by the default order of pages in VuePress.

:::

## channel

`channel` option is used to config *Feed Channels*.

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

## devServer

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

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}"`

Hostname to use in devServer

## atomOutputFilename

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

Atom syntax output filename, relative to dest folder.

## atomXslTemplate

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

Atom xsl template file content.

## atomXslFilename

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

Atom xsl filename, relative to dest folder.

## jsonOutputFilename

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

JSON syntax output filename, relative to dest folder.

## rssOutputFilename

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

RSS syntax output filename, relative to dest folder.

## rssXslTemplate

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

RSS xsl template file content.

## rssXslFilename

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

RSS syntax xsl filename, relative to dest folder.

## getter

Feed generation controller, see [Feed Getter](./getter.md).

::: tip The plugin has a built-in getter, only set this if you want full control of feed generation.

:::

## locales

* Type: `Record<string, BaseFeedOptions>`

You can use it to specific options for each locale.

Any options above are supported except `hostname`.

---

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

You can control each feed item generation by setting page frontmatter.

## Additions and Removals

By default, all articles are added to the feed stream. Set `feed: false` in frontmatter to remove a page from feed.

## Frontmatter Information

### title

* Type: `string`

Automatically generated by VuePress, defaults to the h1 content of the page

### description

* Type: `string`

Description of the page

### date

* Type: `Date`

Date when the page was published

### article

* Type: `boolean`

Whether the page is an article

> If this is set to `false`, the page will not be included in the final feed.

### copyright

* Type: `string`

Page copyright information

### cover / image / banner

* Type: `string`

Image used as page cover , should be full link or absolute link.

## Frontmatter Options

### feed.title

* Type: `string`

The title of the feed item

### feed.description

* Type: `string`

Description of the feed item

### feed.content

* Type: `string`

The content of the feed item

### feed.author

* Type: `FeedAuthor[] | FeedAuthor`

The author of the 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`

Contributors to 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`

The identifier of feed item, used to identify the feed item.

::: tip You should ensure every feed has a unique guid.

:::

---

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

You can take full control of feed items generation by setting `getter` in the plugin options.

## getter.title

* Type: `(page: Page, app: App) => string`

Item title getter

## getter.link

* Type: `(page: Page, app: App) => string`

Item link getter

## getter.description

* Type: `(page: Page, app: App) => string | undefined`

Item description getter

::: tip

Due to Atom supporting HTML in summary, you can return HTML content here if possible, but the content must start with the mark `html:`.

:::

## getter.content

* Type: `(page: Page, app: App) => string`

Item content getter

## getter.author

* Type: `(page: Page, app: App) => FeedAuthor[]`

Item author getter.

::: tip The getter should return an empty array when author information is missing.

:::

::: 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`

Item category getter.

::: 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`

Item enclosure getter.

::: details FeedEnclosure format

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

  /**
   * what its type is
   *
   * @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`

Item release date getter

## getter.lastUpdateDate

* Type: `(page: Page, app: App) => Date`

Item last update date getter

## getter.image

* Type: `(page: Page, app: App) => string`

Item image getter

::: tip Ensure it's returning a full URL

:::

## getter.contributor

* Type: `(page: Page, app: App) => FeedContributor[]`

Item contributor getter

::: tip The getter should return an empty array when contributor information is missing.

:::

::: 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
}
```

:::

## getter.copyright

* Type: `(page: Page, app: App) => string | undefined`

Item copyright getter

---

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

## Usage

The plugin can generate feed files in the following three formats for you:

* Atom 1.0
* JSON 1.1
* RSS 2.0

Please set `atom`, `json` or `rss` to `true` in the plugin options according to the formats you want to generate.

To correctly generate feed links, you need to set `hostname` in the plugin options.

## Readable Preview

When you open the feed file in a browser, we magically convert atom and rss feed xml to human readable html via xsl template. Check [atom](/atom.xml) and [rss](/rss.xml) feed of this site as an example!

If you want to preview your feed in devServer, set `devServer: true` in plugin options. You may also need to set `devHostname` if you are not using the default `http://localhost:{port}`.

## Channel settings

You can customize the feed channel information by setting the `channel` option.

We recommend the following settings:

* Convert the date of creating the feed to ISOString and write it into `channel.pubDate`
* The update period of the content set in `channel.ttl` (unit: minutes)
* Set copyright information via `channel.copyright`
* Set the channel author via `channel.author`.

For detailed options and their default values, see [Channel Config](./channel.md)

## Feed Generation

By default, all articles are added to the feed stream.

You can set `feed` and other options in page frontmatter to control contents of feed item. See [Frontmatter Config](./frontmatter.md) for how they are converted.

You can take full control of feed items generation by configuring the `getter` in the plugin options. For detailed options and their default values, see [Configuration → Feed Getter](./getter.md).

### I18n Config

The plugin generates separate feeds for each language.

You can provide different settings for different languages via `locales` in the plugin options.

---

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

---

---
url: /ecosystem/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: /ecosystem/plugins/development/git.md
---
# git

This plugin will collect git information of your pages, including the created and updated time, the contributors, the changelog, etc.

The [lastUpdated](../../themes/default/config.md#lastupdated) and [contributors](../../themes/default/config.md#contributors) of default theme is powered by this plugin.

This plugin is mainly used to develop themes. You won't need to use it directly in most cases.

## 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 inside a [Git Repository](https://git-scm.com/book/en/Git-Basics-Getting-a-Git-Repository), so that it can collect information from the commit history.

You should ensure all commits are available when building your site. For example, CI workflows usually clone your repository with [--depth 1](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt) to avoid fetching all commits, so you should disable the behavior to make this plugin work properly in CI.

::: warning
This plugin will significantly slow down the speed of data preparation, especially when you have a lot of pages. You can consider disabling this plugin in `dev` mode to get better development experience.
:::

## Options

### createdTime

* Type: `boolean`

* Default: `true`

* Details:

  Whether to collect page created time or not.

### updatedTime

* Type: `boolean`

* Default: `true`

* Details:

  Whether to collect page updated time or not.

### contributors

* Type: `boolean | ContributorsOptions`

  ```ts
  interface ContributorInfo {
    /**
     * Contributor's username on the git hosting service
     */
    username: string
    /**
     * Contributor name displayed on the page, default is `username`
     */
    name?: string
    /**
     * The alias of the contributor,
     * Since contributors may have different usernames saved in their local git configuration
     * compared to their usernames on the hosting service, In this case, aliases can be used to
     * map to the actual usernames.
     */
    alias?: string[] | string
    /**
     * The primary email of the contributor
     */
    email?: string
    /**
     * The alternative emails of the contributor on the Git hosting service,
     * or emails they have used in the past.
     */
    emailAlias?: string[] | string
    /**
     * The avatar url of the contributor.
     *
     * If the git hosting service is `github`, it can be ignored and left blank,
     * as the plugin will automatically fill it in.
     */
    avatar?: string
    /**
     * The url of the contributor
     *
     * If the git hosting service is `github`, it can be ignored and left blank,
     * as the plugin will automatically fill it in.
     */
    url?: string
  }

  interface ContributorsOptions {
    /**
     * Contributor information
     */
    info?: ContributorInfo[]

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

    /**
     * Avatar url pattern
     * - `:username` - Contributor's username
     *
     * @example 'https://github.com/:username'
     */
    avatarPattern?: string

    /**
     * Functions to transform contributors, e.g. remove duplicates ones and sort them.
     * The input is the contributors collected by this plugin, and the output should be the transformed contributors.
     */
    transform?: (contributors: GitContributorInfo[]) => GitContributorInfo[]
  }
  ```

* Default: `true`

* Details:

  Whether to collect page contributors or not.

### changelog

* Type: `boolean | ChangelogOptions`

  ```ts
  interface ChangelogOptions {
    /**
     * Maximum number of changelog
     */
    maxCount?: number

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

    /**
     * Commit url pattern
     *
     * - `:repo` - The url of the git repository
     * - `:hash` - Hash of the commit record
     *
     * @default ':repo/commit/:hash'
     */
    commitUrlPattern?: string

    /**
     * Issue url pattern
     *
     * - `:repo` - The url of the git repository
     * - `:issue` - Id of the issue
     *
     * @default ':repo/issues/:issue'
     */
    issueUrlPattern?: string

    /**
     * Tag url pattern
     *
     * - `:repo` - The url of the git repository
     * - `:tag` - Name of the tag
     *
     * @default ':repo/releases/tag/:tag'
     */
    tagUrlPattern?: string
  }
  ```

* Default: `false`

* Details:

  Whether to collect page changelog or not.

### filter

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

* Details:

  Page filter, if it returns `true`, the page will collect git information.

### locales

* Type: `Record<string, GitLocaleData>`

  ```ts
  export interface GitLocaleData {
    /**
     * Contributors title
     */
    contributors: string

    /**
     * Changelog title
     */
    changelog: string

    /**
     * Word to represent a commit "on" a time
     */
    timeOn: string

    /**
     * Changelog button
     */
    viewChangelog: string

    /**
     * Latest updated
     */
    latestUpdateAt: string
  }
  ```

* Details:

  Locales configuration, used in the [Git Component](#component).

## Frontmatter

### gitInclude

* Type: `string[]`

* Details:

  An array of relative paths to be included when calculating page data.

* Example:

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

### contributors

* Type: `boolean | string[]`

* Details:

  Whether to collect contributor information for the current page, this value will override the [contributors](#contributors) configuration item.

  * `true` - Collect contributor information
  * `false` - Do not collect contributor information
  * `string[]` - List of additional contributors, sometimes there are additional contributors on the page, and this configuration item can be used to specify the list of additional contributors to obtain contributor information

### changelog

* Type: `boolean`

* Details:

  Whether to collect the change history for the current page, this value will override the [changelog](#changelog) configuration item.

## Composables

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

### useChangelog

Get the changelog of 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
   */
  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[]

  /**
   * Date text of the commit
   */
  date: string
}

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

### useContributors

Get the contributors of 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
   */
  avatar?: string
  /**
   * The url of the contributor
   */
  url?: string
}

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

### useLastUpdated

Get 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 of the last updated time
   */
  locale: string
}

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

## Page Data

This plugin will add a `git` field to page data.

After using this plugin, you can get the collected git information in page data:

```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:

  Unix timestamp in milliseconds of the first commit of the page.

  This attribute would take the minimum of the first commit timestamps of the current page and the files listed in [gitInclude](#gitinclude).

### git.updatedTime

* Type: `number`

* Details:

  Unix timestamp in milliseconds of the last commit of the page.

  This attribute would take the maximum of the last commit timestamps of the current page and the 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 contributors information of the page.

  This attribute would also include contributors to the 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
   */
  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 of the page.

  This attribute would also include contributors to the files listed in [gitInclude](#gitinclude).

## Git Component{#component}

The plugin provides global components related to Git information, which can be used in themes.

### GitContributors

List the contributor information for the current page.

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

**Effect Preview:**

### GitChangelog

List the changelog of the current page.

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

**Effect Preview:**

---

---
url: /ecosystem/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: /ecosystem/plugins/development/reading-time.md
---
# reading-time

This plugin generates word count and estimated reading time for each page.

## 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
    }),
  ],
}
```

The plugin injects reading time information into the `readingTime` field of page data:

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

### Getting Data on Node Side

For any page, you can get estimated reading time and word count from `page.data.readingTime`:

```ts
page.data.readingTime // { minutes: 3.2, words: 934 }
```

You can access it for further processing in the `extendsPage` lifecycle and other lifecycles:

```js
export default {
  // ...
  extendsPage: (page) => {
    page.data.readingTime // { minutes: 3.2, words: 934 }
  },

  onInitialized: (app) => {
    app.pages.forEach((page) => {
      page.data.readingTime // { minutes: 3.2, words: 934 }
    })
  },
}
```

### Getting Data on Client Side

You can import `useReadingTimeData` and `useReadingTimeLocale` from `@vuepress/plugin-reading-time/client` to get the reading time data and locale data of the current page:

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

const readingTimeData = useReadingTimeData() // { minutes: 1.1, words: 100 }
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 (Brazil)** (pt-BR)
* **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>
```

## Advanced Usage

This plugin targets plugin and theme developers, so we provide a "Use API":

```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 you should use the "Use API"

1. When you register a plugin multiple times, VuePress gives you a warning that only the first one takes effect. The `useReadingTimePlugin` automatically detects if the plugin is registered and avoids registering multiple times.
2. If you access reading time data in the `extendsPage` lifecycle, then `@vuepress/plugin-reading-time` must be called before your theme or plugin, otherwise you will get `undefined` for `page.data.readingTime`. The `useReadingTimePlugin` ensures that `@vuepress/plugin-reading-time` is called before your theme or plugin.

:::

We also provide a `removeReadingTimePlugin` API to remove the plugin. You can use this to ensure your call takes effect or clear the plugin:

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

export default (options) => (app) => {
  // this removes any existing reading time plugin at this time
  removeReadingTimePlugin(app)

  // so this will take effect even if there is a reading time plugin registered before
  useReadingTimePlugin(app, {
    // your options
  })

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

---

---
url: /ecosystem/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: /ecosystem/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: /ecosystem/plugins/development/sass-palette/config.md
---
# Config

## Options

### id

* Type: `string`
* Required: Yes

Identifier for palette, used to avoid duplicate registration.

### config

* Type: `string`
* Default: `` `.vuepress/styles/${id}-config.scss` ``

User config file path, relative to source dir.

::: tip

This is the file where users set style variables.

The default filename starts with ID above.

:::

### defaultConfig

* Type: `string`
* Default: `"@vuepress/plugin-sass-palette/styles/default/config.scss"`

Default config file path, should be absolute path.

::: tip

This is the file you should use to provide default values with `!default`.

:::

### palette

* Type: `string`
* Default: `` `.vuepress/styles/${id}-palette.scss` ``

User palette file path, relative to source dir.

::: tip

This is the file where users control injected CSS variables. All the variables will be converted to kebab-case and injected.

The default filename starts with ID above.

:::

### defaultPalette

* Type: `string`

Default palette file path, should be absolute path.

::: tip

This is the file you should use to provide default CSS variables with `!default`. All the variables will be converted to kebab-case and injected.

:::

### generator

* Type: `string`

Custom generator used to generate derivative values with palette config.

For example: You may want to provide a `$theme-color-light` based on `$theme-color`.

### style

* Type: `string`

User style file path, relative to source dir.

## Alias

Available aliases are:

* config: `@sass-palette/${id}-config` (based on `id`)
* palette: `@sass-palette/${id}-palette` (based on `id`)
* style: `@sass-palette/${id}-style` (only available when `style` option is set)
* helper: `@sass-palette/helper`

---

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

Comparing to [`@vuepress/plugin-palette`](../palette.md), this plugin allows you to:

* Derive related styles based on user configuration
* Provide style customization similar to themes in plugins
* Group applications across multiple plugins or themes via id option

Before using the plugin, you need to understand the id option, as well as three styling concepts: configuration, palette and generator.

## ID Option

To get started, you should understand that this plugin is designed to work across plugins and themes (unlike the official one only for themes).

We are providing `id` option to do that, and using this plugin (by calling `useSassPalette`) with same ID won't have any side effects. Also, all the aliases and module names have an ID prefix.

This will allow you to:

* Share the same style system across your plugins (or themes) using the same ID without any side effects.

  All aliases and module names have an ID prefix, which means you can use a set of style variables within your plugins (or theme) to unify your styles without being affected by other plugins (or themes).

  Users can configure all color variables, breakpoints, and other style configurations in the same file and have them automatically applied to themes and plugins with the same ID.

  ::: tip Example

  `vuepress-theme-hope` and other related plugins use the same ID `hope` to call the plugin, so the styles configured by the user in the theme will automatically take effect in all plugins.

  :::

* With different ID, plugins and theme won't affect others. We recommend you to set the `id` variable with your plugin name.

  With the default settings, users will set your plugin style under `.vuepress/styles` directory with Sass files starting with your ID prefix. And you can access the variables you need with `${id}-config` and `${id}-palette`.

  ::: tip Example

  `vuepress-theme-hope` is using ID `"hope"`, and just imagine a `vuepress-plugin-abc` is using `"abc"`. They can get their own variables with module name `hope-config` `hope-palette` and `abc-config` `abc-palette`.

  :::

* Calling the plugin with the same ID has no side effects.

  ::: tip example

  `vuepress-theme-hope` and other related plugins use the same ID `hope` to call the plugin.

  :::

## Config

Config file is used for Sass variable only. It holds Sass variables which can be used via `${id}-config` in other files later.

You can specify a file (probably in `.vuepress/styles/` directory) as user config file. So you can get the module containing every variable later in Sass files. Also, you are able to provide a default config files where you can place fallback values for variables with `!default`.

::: details An example

Imagine you are invoking the plugin with the following options 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;
```

You can get the following variables in the plugin Sass files:

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

:::

### Limitations

We are using `additionalData` options to let `${id}-config` module available in your styles, but this has some limitations.

`additionalData` only works on Scss entry, so `${id}-config` is available only in :

* `<style lang="scss">` block in component files
* Scss files imported by script files directly (e.g.: `import "./a-scss-file.scss"` in client app enhance file).

If the Scss file is not imported directly, but is imported through `@use` or `@import` api, the module won't be available. So that in this case, you should manually import the module with `@use "@sass-palette/${id}-config";`.

## Palette

Palette files are used for CSS variable injection, where each variable will be injected in to root with kebab-name of variable name.

You can specify a file (probably in `.vuepress/styles/` directory) as user palette file, and the default filename is `${id}-palette.scss`. Also, you are able to provide a default palette files where you can place fallback values for variables with `!default`.

::: details An example

Imagine you are invoking the plugin with the following options in `vuepress-plugin-abc`:

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

If users are setting:

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

And you are providing a default palette file with:

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

Then the below CSS variables will be available under root selector:

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

:::

Like config file, palette file provides a module named `${id}-palette` (also including generator values), and it is also limited by `additionalData` option, so you should import the module manually if you want to use it in other Sass files.

### Color Settings

Since the default theme provides dark mode, you probably want different colors under light mode and dark mode.

To achieve that, you should set color variables with a map containing `light` and `dark` keys. Later, the plugin will generate different colors for you.

::: details An 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;
```

Then you will get:

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

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

:::

### Allowed Variable Types

Only colors (or color map for light/dark mode), length and strings are allowed in palette. Any other type will be dropped.

:::: tip Why only allow color and length besides strings

In common situations, you probably only want to make calculations with color and length. So it's quite safe to drop other type support, because any other value you want can be converted to string.

::: details Example

If you want a `--move-transition` with `width 0.3s ease`, you can use strings:

```scss
// this will be regarded as a list with (length, time, function) by Sass
// and will trigger a warning and be dropped by plugin
$moveTransition: width 0.3s ease;

// this will get what you want
// :root {
//   --move-transition: width 0.3s ease
// }
$moveTransition: 'width 0.3s ease';
```

:::

::::

## Helper

We are exposing internal functions that `@vuepress/plugin-sass-palette` uses, as a helper module.

You can use this helper with `@sass-palette/helper` alias and call its functions to achieve similar features yourself.

## Generator

A generator file is designed for developers to generate derived values based on palette file variables.

You can access variables from the palette file directly in this file and generate new values based on them.

Variables in the generator file will also be injected as CSS variables like palette, and they will be available in the palette module.

::: details Example

You may want a `$theme-color-light` based on `$theme-color`. So you can write a generator like this:

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

$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 generate values based on variables provided by config files by importing it:

```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

If you are a theme developer, you may want to provide your users a way to customize your theme or the site.

In this case you should set the `style` option as the user style file when using this plugin.

Later, you should manually include the user style file by importing `@sass-palette/${id}-style` **after your theme styles**.

::: tip

`@sass-palette/${id}-style` is an alias to user style file, and you can import it in JS/TS/SASS.

:::

---

---
url: /ecosystem/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: /ecosystem/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: /ecosystem/plugins/features/index.md
---
# Feature Plugins

---

---
url: /ecosystem/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: /ecosystem/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 (Brazil)** (pt-BR)
* **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: /ecosystem/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 (Brazil)** (pt-BR)
* **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: /ecosystem/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 (Brazil)** (pt-BR)
* **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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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 (Brazil)** (pt-BR)
* **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 
  </button>
</template>
```

## Styles

You can customize the style via CSS variables:

@[code css](@vuepress/plugin-photo-swipe/src/client/styles/vars.css)

---

---
url: /ecosystem/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: /ecosystem/plugins/markdown/index.md
---
# Markdown Plugins

---

---
url: /ecosystem/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: /ecosystem/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: /ecosystem/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.

---

---
url: /ecosystem/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
}
```

:::
````

Both `js` and `javascript` code blocks are also supported. For these, you should assign your export object to `module.exports`.

## 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: /ecosystem/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

If you need to use script to get the data, you can use `js` or `javascript` code block.

We will expose the echarts instance as `echarts` 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.

````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-md-enhance/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: /ecosystem/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: /ecosystem/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: /ecosystem/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`
* 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-md-enhance/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: /ecosystem/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: /ecosystem/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: /ecosystem/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



:::

::::

## 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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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-full
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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/plugins/pwa/index.md
---
# PWA Plugins

---

---
url: /ecosystem/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: /ecosystem/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 (Brazil)** (pt-BR)
  * **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: /ecosystem/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: /ecosystem/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: /ecosystem/plugins/search/index.md
---
# Search Plugins

---

---
url: /ecosystem/plugins/search/docsearch.md
---
# docsearch

Integrate [Algolia DocSearch](https://docsearch.algolia.com/) into VuePress, which can provide search to 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

You need to [submit the URL of your site](https://docsearch.algolia.com/apply/) to join the DocSearch program. The DocSearch team will send [apiKey](#apikey) and [indexName](#indexname) to your email once the index is generated. Then you can configure this plugin to enable DocSearch in VuePress.

Alternatively, you can [run your own crawler](https://docsearch.algolia.com/docs/run-your-own/) to generate the index, and then use your own [appId](#appid), [apiKey](#apikey) and [indexName](#indexname) to configure this 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 above `recordProps` is the configuration used for the default theme. You can modify them according to the theme you are using.

Notice that the `initialIndexSettings.YOUR_INDEX_NAME.attributesForFaceting` fields must include `'lang'` to make this plugin work properly.
:::

::: tip
If you are not using default theme, or you meet any problems when using docsearch, you can also check the above example crawler config, and ahead to [Algolia Crawler](https://crawler.algolia.com/admin/crawlers/), and edit your config with 'Editor' panel in project sidebar.
:::

## Options

### apiKey

* Type: `string`

* Required: Yes

* Details: The `apiKey` that you received from the DocSearch team, or generated by yourself.

* Also see:
  * [DocSearch > Options > apiKey](https://docsearch.algolia.com/docs/api#apikey)

### indexName

* Type: `string`

* Required: Yes

* Details: The `indexName` that you received from the DocSearch team, or generated by yourself.

* Also see:
  * [DocSearch > Options > indexName](https://docsearch.algolia.com/docs/api#indexname)

### appId

* Type: `string`

* Required: Yes

* Details: It defines your own application ID.

* Also see:
  * [DocSearch > Options > appId](https://docsearch.algolia.com/docs/api#appid)

### searchParameters

* Type: `SearchParameters`

* Details: Algolia Search API parameters.

* Reference:
  * [DocSearch > Options > searchParameters](https://docsearch.algolia.com/docs/api/#searchparameters)
  * [Algolia > Search API Parameters](https://www.algolia.com/doc/api-reference/search-api-parameters/)

### placeholder

* Type: `string`

* Default: `'Search docs'`

* Details: The placeholder attribute of the search input.

* Reference:
  * [DocSearch > Options > placeholder](https://docsearch.algolia.com/docs/api/#placeholder)

### disableUserPersonalization

* Type: `boolean`

* Default: `false`

* Details: Whether to disable all personalized features: recent searches, favorite searches, etc.

* Reference:
  * [DocSearch > Options > disableUserPersonalization](https://docsearch.algolia.com/docs/api/#disableuserpersonalization)

### initialQuery

* Type: `string`

* Details: The initial query 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 results per group.

* Also see:
  * [DocSearch > Options > maxResultsPerGroup](https://docsearch.algolia.com/docs/api/#maxresultspergroup)

### translations

* Type: `Partial<DocSearchTranslations>`

* Details: Allow replacing the default text in the DocSearch button or modal.

* Also see:
  * [DocSearch > Options > translations](https://docsearch.algolia.com/docs/api/#translations)

### locales

* Type: `Record<string, DocSearchPluginOptions>`

* Details: Options of this plugin in different locales. All other options of this plugin are acceptable in locale config.

* 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 search index.

  If you are deploying your site to multiple domains, you don't need to submit all of them to DocSearch and generate search index separately. You could choose one of the domains as the *index domain*, and only submit the *index domain* to DocSearch for crawling search index. Then, you could reuse the search index across all deployments.

  However, if the [base](https://vuejs.press/reference/config.html#base) of your deployments are different for different domains, you need to set the option to the [base](https://vuejs.press/reference/config.html#base) of your *index domain*, so that other deployments could reuse the search index correctly.

### injectStyles

* Type: `boolean`
* Default: `true`
* Details: Whether to inject the default styles of DocSearch or not.

  If you think the default styles of DocSearch is not compatible with your site, you can try to override the default styles, or set this option to `false` to totally exclude the default styles.

  When this option is disabled, you need to import your own styles for DocSearch. Also notice that all styles customization in [Styles](#styles) section would be unavailable.

## Client options

### defineDocSearchConfig

```ts
type DocSearchClientLocaleOptions = Partial<DocSearchProps>

interface DocSearchClientOptions extends DocSearchClientLocaleOptions {
  locales?: Record<string, DocSearchClientLocaleOptions>
}

const defineDocSearchConfig: (
  options: MaybeRefOrGetter<DocSearchClientOptions>,
) => void
```

Customize DocSearch options, support plain object, ref or getter.

::: warning

To support VuePress's routing and other optimizations, the `transformItems`, `hitComponent` `navigator` and `transformSearchClient` options have been configured internally. Overriding them directly may lead to unexpected behavior.

If you need to customize them, you may need to first understand [VuePress's adaptation](https://github.com/vuepress/ecosystem/blob/main/plugins/search/plugin-docsearch/src/client/composables/useDocSearchSlim.ts) and make sure not to break them.

:::

## Styles

You can customize styles via CSS variables that provided by [@docsearch/css](https://docsearch.algolia.com/docs/styling):

```css
:root {
  --docsearch-primary-color: rgb(84, 104, 255);
  --docsearch-text-color: rgb(28, 30, 33);
  --docsearch-spacing: 12px;
  --docsearch-icon-stroke-width: 1.4;
  --docsearch-highlight-color: var(--docsearch-primary-color);
  --docsearch-muted-color: rgb(150, 159, 175);
  --docsearch-container-background: rgba(101, 108, 133, 0.8);
  --docsearch-logo-color: rgba(84, 104, 255);

  /* modal */
  --docsearch-modal-width: 560px;
  --docsearch-modal-height: 600px;
  --docsearch-modal-background: rgb(245, 246, 247);
  --docsearch-modal-shadow:
    inset 1px 1px 0 0 rgba(255, 255, 255, 0.5), 0 3px 8px 0 rgba(85, 90, 100, 1);

  /* searchbox */
  --docsearch-searchbox-height: 56px;
  --docsearch-searchbox-background: rgb(235, 237, 240);
  --docsearch-searchbox-focus-background: #fff;
  --docsearch-searchbox-shadow: inset 0 0 0 2px var(--docsearch-primary-color);

  /* hit */
  --docsearch-hit-height: 56px;
  --docsearch-hit-color: rgb(68, 73, 80);
  --docsearch-hit-active-color: #fff;
  --docsearch-hit-background: #fff;
  --docsearch-hit-shadow: 0 1px 3px 0 rgb(212, 217, 225);

  /* key */
  --docsearch-key-gradient: linear-gradient(
    -225deg,
    rgb(213, 219, 228) 0%,
    rgb(248, 248, 248) 100%
  );
  --docsearch-key-shadow:
    inset 0 -2px 0 0 rgb(205, 205, 230), inset 0 0 1px 1px #fff,
    0 1px 2px 1px rgba(30, 35, 90, 0.4);

  /* footer */
  --docsearch-footer-height: 44px;
  --docsearch-footer-background: #fff;
  --docsearch-footer-shadow:
    0 -1px 0 0 rgb(224, 227, 232), 0 -3px 6px 0 rgba(69, 98, 155, 0.12);
}
```

## Components

* SearchBox

---

---
url: /ecosystem/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: /ecosystem/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: $
          # replace it with the path to your config file
          CONFIG_FILE_PATH: $/<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: /ecosystem/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: /ecosystem/plugins/search/slimsearch.md
---
# slimsearch

A powerful client-side search plugin with 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

With [`slimsearch`](https://mister-hope.github.io/slimsearch/), searching is ultra fast, even on large sites.

By default, the plugin will only index headings, article excerpt and custom fields you add. If you want to index all content, you should set `indexContent: true` in the plugin options.

To prevent a page from being indexed, you can set `search: false` in it's frontmatter. TO programmatically filter pages, you can set [`filter` option](#filter).

::: important Tokenize every language correctly

When indexing languages that is not word based, like Chinese, Japanese or Korean, you should set `indexOptions` and `indexLocaleOptions` to perform correct word-splitting, see [Customize Index Generation](#customize-index-generation).

Meanwhile, for better client search experience, you should customize the `querySplitter` option to split the input query through `defineSearchConfig`, introducing a NLP\[^nlp] API could be a good choice.

:::

## Custom Fields

Whether you are a theme developer or a user, adding extra data for a page through page frontmatter or the `extendsPage` lifecycle is common, and in most cases you may want to index these data as well.

The `customFields` options accepts an array, each element represents a custom search index configuration item. Each configuration item contains 2 parts:

* `getter`: The getter for this custom field. This function takes `page` object as a parameter and returns the value of the custom field as a string (single), an array of strings (multiple), `null` (the item is missing).
* `formatter`: a string controlling how the item is displayed in the custom search result, where `$content` is replaced with the actual value returned by `getter`. If you're using multiple languages, you can also set it as an object to set the display format for each language individually.

These data will be added to indexes and the search result will contain them.

::: tip Example: Adding author to index

Assuming you add author information via `author` in frontmatter:

```md
---
author: Your name
---

Your Markdown content...
```

You can add author information to the index by setting:

```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

Supposed you are using the `@vuepress/plugin-git` plugin and you are putting Chinese and English docs under `/zh/` and `/` respectively.

Then you can set the following to index the update time:

```ts title=".vuepress/config.ts"
import { slimsearchPlugin } from '@vuepress/plugin-slimsearch'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  // We assume you are using the following multilingual
  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 content indexing.

::: tip

By default, only headings and excerpt of the page will be indexed along with your custom fields. If you need to index the content of the page, set this option to `true`

:::

### suggestion

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

Whether to show suggestions while searching.

### customFields

* Type: `CustomFieldOptions[]`

  ```ts
  interface CustomFieldOptions {
    /**
     * Custom field getter
     */
    getter: (page: Page) => string[] | string | null | undefined

    /**
     * Display content
     *
     * @description `$content` will be replaced by the content returned by `getter`
     *
     * @default `$content`
     */
    formatter?: Record<string, string> | string
  }
  ```

Customize index 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/) of the hotkeys.

When hotkeys are pressed, the search box input will be focused. Set to an empty array to disable hotkeys.

### queryHistoryCount

* Type: `number`
* Default: `5`

Max stored query history count, set `0` to disable it.

### resultHistoryCount

* Type: `number`
* Default: `5`

Max stored matched result history count, set `0` to disable it.

### searchDelay

* Type: `number`
* Default: `150`

Delay to start searching after input.

::: note

Performing client search with huge contents could be slow, so under this case you might need to increase this value to ensure user finish input before searching.

:::

### filter

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

Function used to filter pages.

### sortStrategy

* Type: `"max" | "total"`
* Default: `"max"`

Result Sort strategy.

When there are multiple matched results, the result will be sorted by the strategy. `max` means that page having higher total score will be placed in front. `total` means that page having higher max score will be placed in front.

### worker

* Type: `string`
* Default: `slimsearch.worker.js`

Output Worker filename

### hotReload

* Type: `boolean`
* Default: Whether using `--debug` flag

Whether to enable hot reload in the development server.

::: note

It is disabled by default because this feature can have a huge performance impact on sites with huge content and drastically increases the speed of hot reloads when editing Markdown.

:::

### 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 used to create index.

### indexLocaleOptions

* Type: `Record<string, SlimSearchIndexOptions>`

Options used to create index per locale, the object keys should be the locale path.

### locales

* Type: `SlimSearchLocaleConfig`

  ```ts
  interface SlimSearchLocaleData {
    /**
     * Search box placeholder
     */
    placeholder: string

    /**
     * Search text
     */
    search: string

    /**
     * Clear search text
     */
    clear: string

    /**
     * Remove current item
     */
    remove: string

    /**
     * Searching text
     */
    searching: string

    /**
     * Cancel text
     */
    cancel: string

    /**
     * Default title
     */
    defaultTitle: string

    /**
     * Select hint
     */
    select: string

    /**
     * Choose 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

    /**
     * Search history empty hint
     */
    emptyHistory: string

    /**
     * Empty hint
     */
    emptyResult: string
  }

  interface SlimSearchLocaleConfig {
    [localePath: string]: SlimSearchLocaleData
  }
  ```

Multilingual configuration of the search 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 (Brazil)** (pt-BR)
* **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 index this page.

## Advanced

### Customize Index Generation

If you are indexing other language which is not using "Words", like Chinese, Japanese or Korean, you should set `indexOptions` and `indexLocaleOptions` to perform correct word-splitting.

If you are building a Chinese docs, you can use [nodejs-jieba](https://github.com/Mister-Hope/nodejs-jieba) to perform word splitting. (Japanese and Korean do not have built-in dictionary, but you can provide your own dictionary and split words with `nodejs-jieba`).

If your docs only contain Chinese, you can tokenize the content like this:

```ts title=".vuepress/config.ts"
import { slimsearchPlugin } from '@vuepress/plugin-slimsearch'
import { cut } from 'nodejs-jieba'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  lang: 'zh-CN',

  plugins: [
    slimsearchPlugin({
      // index all content
      indexContent: true,
      indexOptions: {
        // tokenize the content with nodejs-jieba
        tokenize: (text, fieldName) =>
          fieldName === 'id' ? [text] : cut(text, true),
      },
    }),
  ],
})
```

If you need word splitting in some locales, you can set `indexLocaleOptions`:

```ts title=".vuepress/config.ts"
import { slimsearchPlugin } from '@vuepress/plugin-slimsearch'
import { cut } from 'nodejs-jieba'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  locales: {
    '/': {
      lang: 'en-US',
    },
    '/zh/': {
      lang: 'zh-CN',
    },
  },

  plugins: [
    slimsearchPlugin({
      indexContent: true,
      indexLocaleOptions: {
        '/zh/': {
          // tokenize the content with nodejs-jieba
          tokenize: (text, fieldName) =>
            fieldName === 'id' ? [text] : cut(text, true),
        },
      },
    }),
  ],
})
```

### Using with API

If you want to access the search API, you need to 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 something
suggest('key').then((suggestions) => {
  // display search suggestions
})

// search something
search('keyword').then((results) => {
  // display search results
})

// return both suggestions and results
all('key').then(({ suggestions, results }) => {
  // display search suggestions and results
})

// terminate the worker when you don't need it
terminate()
```

### Limitations in DevServer

The search service is powered by a worker, and in dev mode we cannot bundle the worker file.

In order to load search indexes in dev mode, we are using a modern service worker with `type: "module"`, so if you want to try searching in devServer, you should use a supported browser, see [CanIUse](https://caniuse.com/mdn-api_worker_worker_ecmascript_modules) for support details.

For better performance, adding/editing/deleting markdown contents will not trigger update for search index in dev mode. If you are proofreading or refining your search results, you can enable hot reloading by setting the `hotReload: true` option.

### Comparing with Server-Search

Client-side search has advantages, like no backend services and easy to add, but you should be aware that it has disadvantages.

::: warning Disadvantages

1. You need to index your website during the build stage, which increases website deployment time and website bundle size.
2. Users need to fetch the entire search index from your server before searching, which will bring additional traffic and bandwidth pressure to your server. The more content you hold on your site, the larger search index will be.
3. To perform a search, users must wait for the search index to be downloaded and parsed locally. This may be much slower than performing a simple web request to get results via Server-search.
4. Since searching is done on users devices, the speed is totally based on device performance.

:::

In most cases, if you are building a large site, you should choose a service provider to provide search services for your site if possible, such as [Algolia](https://www.algolia.com/), or choose an open source search crawler tool and host it on your own server to provide a search service and regularly craw your site. This is necessary for large sites because users send search terms to the search API via network requests and get search results directly.

In particular, [DocSearch](https://docsearch.algolia.com/) is a free search service provided by Algolia for open source projects. If you are creating open source project documentation or an open source technical blog, you can [apply for it](https://docsearch.algolia.com/apply/), and use [`@vuepress/plugin-docsearch`](./docsearch.md) plugin to provide search features.

## Client Config

### defineSearchConfig

Customize [search options](https://mister-hope.github.io/slimsearch/interfaces/SearchOptions.html), accepts plain object, ref or getter functions as parameters.

Since searching is done in a Web Worker, setting function-typed options for `slimsearch` is not supported.

For more accurate search queries, suggestions, and results, we provide `querySplitter`, `suggestionsFilter`, and `resultsFilter` options. You can set them for specific or all languages:

```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({
  // search options here

  locales: {
    '/zh/': {
      // set different options for Chinese
    },
  },
})
```

## Components

* SearchBox

\[^nlp]: **N**atural **L**anguage **P**rocessing

---

---
url: /ecosystem/plugins/seo/index.md
---
# SEO Plugins

---

---
url: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/plugins/tools/index.md
---
# Tool Plugins

---

---
url: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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 (Brazil)** (pt-BR)
* **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: /ecosystem/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 [globby](https://github.com/sindresorhus/globby).

  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: /ecosystem/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: /ecosystem/themes/index.md
---
# Themes

---

---
url: /ecosystem/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: /ecosystem/themes/default/components.md
---
# Built-in Components

## Badge&#x20;

* Props:
  * 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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/tools/index.md
---
# Tool Packages

---

---
url: /ecosystem/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: /ecosystem/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 isChromeWebView: (ua: string) => boolean
export const isSafariMobile: (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">
    
  </button>

  <FadeInExpandTransition>
    <div v-show="expand">
      <p>Content</p>
    </div>
  </FadeInExpandTransition>
</template>
```

---

---
url: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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: /ecosystem/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%;
}
```