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

Usage

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

import { llmsPlugin } from '@vuepress/plugin-llms'

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

Why llms.txt?

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

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

Plugin Overview

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

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

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

Output Files

1. llms.txt

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

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

Default Format:

# Title

> Description

Details (Optional)

## Table of Contents

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

Content Resolution Logic:

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

• Site Title:

  1. llmsTxtTemplateGetter.title
  2. heroText in the homepage frontmatter
  3. The current locale's title in the VuePress config
  4. The main title in the VuePress config
  5. The page title of the locale homepage (README.md)

• Site Description:

  1. llmsTxtTemplateGetter.description
  2. tagline in the locale homepage frontmatter
  3. The current locale's description in the VuePress config
  4. The main description in the VuePress config
  5. frontmatter.description in the locale homepage (README.md)

• Site Details (Optional):

  1. llmsTxtTemplateGetter.details
  2. frontmatter.details in the locale homepage (README.md)

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

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

2. llms-full.txt

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

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

Format:

Usage

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

import { baiduAnalyticsPlugin } from '@vuepress/plugin-baidu-analytics'

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

Event Tracking

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

For advanced usage, the global _hmt array is exposed on the window object. You can utilize this to push custom events manually.

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

Options

id

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

clarity-analytics

Seamlessly integrate Microsoft Clarity into your VuePress project.

Usage

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

import { clarityAnalyticsPlugin } from '@vuepress/plugin-clarity-analytics'

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

Features

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

Key features include:

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

For more details on capabilities, please refer to the Clarity Features Overview.

Advanced Usage

Once the plugin is enabled, the clarity() function is exposed on the global window object. You can use this to interact with the Clarity Client API for advanced tasks, such as:

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

Options

id

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

crossOrigin

• Type: string
• Default: undefined
• Details: The crossorigin attribute for the injected script tag. This configures the CORS setting for loading the Clarity resources.

This plugin leverages the Global Site Tag (gtag.js) to enable robust traffic analysis and user tracking.

Usage

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

import { googleAnalyticsPlugin } from '@vuepress/plugin-google-analytics'

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

Reporting Events

Google Analytics 4 automatically collects a wide range of events by default, such as page_view, first_visit, and scroll.

For standard metric collection, simply set the Measurement ID.

If you require advanced tracking capabilities, this plugin exposes the global gtag() function on the window object. You can utilize this function to report custom events programmatically based on user interactions within your site.

Options

id

• Type: string

• Required: Yes

• Details:

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

  Please refer to the official guide to locate your Measurement ID. Ensure you are using a GA4 Measurement ID (G-XXXXXXXXXX) rather than a Universal Analytics Tracking ID (UA-XXXXXXXX).

• Example:

  .vuepress/config.ts

  export default {
    plugins: [
      googleAnalyticsPlugin({
        id: 'G-XXXXXXXXXX',
      }),
    ],
  }

debug

• Type: boolean

• Details:
  Enables the sending of events to the Google Analytics DebugView. This is useful for verifying your setup and troubleshooting event data during development. Learn more about DebugView.

• Example:

  .vuepress/config.ts

  export default {
    plugins: [
      googleAnalyticsPlugin({
        id: 'G-XXXXXXXXXX',
        debug: true,
      }),
    ],
  }

Usage

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

import { umamiAnalyticsPlugin } from '@vuepress/plugin-umami-analytics'

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

This plugin supports both Umami Cloud and Self-hosted instances.

Reporting Events

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

For advanced tracking needs, the global umami object is exposed on the window instance. You can utilize this to trigger custom events programmatically via umami.track().

Options

id

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

link

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

autoTrack

• Type: boolean

• Default: true

• Details:

  Controls whether to track pageviews and events automatically.

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

cache

• Type: boolean

• Details:

  Enables caching to improve the tracking script's performance.

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

domains

• Type: string[]

• Details:

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

hostUrl

• Type: string

• Default: link

• Details:

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

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

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

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 via markdown.anchor.

• Also see:

  • Guide > Markdown > Syntax Extensions > 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.

The lastUpdated and contributors features in the default theme are powered by this plugin.

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

Usage

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

import { gitPlugin } from '@vuepress/plugin-git'

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

Git Repository

This plugin requires your project to be located within a Git Repository to properly collect data from the commit history.

Ensure that the full commit history is available when building your site. CI workflows often use [--depth 1](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt

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

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

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

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

Palette and Style

This plugin provides a @vuepress/plugin-palette/palette (palette 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, SASS variables, LESS variables, or Stylus variables in the palette, and then you can use those variables in your theme styles.

Cookbook

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

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:

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

$color: green;

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

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 option.

  This option is used for generating tempPaletteFile , and you don't need to change this option in most cases.

Usage

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

import { readingTimePlugin } from '@vuepress/plugin-reading-time'

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

Page Data (Node.js Side)

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

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

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

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

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

Composition API (Client Side)

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

Import useReadingTimeData for raw numbers or useReadingTimeLocale for localized strings:

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

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

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

Options

wordPerMinute

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

locales

• Type: ReadingTimePluginLocaleConfig

  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.

Client API

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

useReadingTimeData

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

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

const useReadingTimeLocale: () => ComputedRef<ReadingTimeLocale>

Theme Integration

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

import { useReadingTimePlugin } from '@vuepress/plugin-reading-time'

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

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

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

import { useReadingTimePlugin } from '@vuepress/plugin-reading-time'

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

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

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

Usage

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

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

  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.

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

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

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 and useThemeLocaleData.

• Example:

export default {
  plugins: [
    themeDataPlugin({
      themeData: {
        foo: 'foo',
        locales: {
          '/zh/': {
            foo: 'zh-foo',
          },
        },
      },
    }),
  ],
}

Composition API

useThemeData

• Details:

  Returns the theme data ref object.

  The value is provided by themeData option.

• Example:

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:

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)
  },
}

Usage

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

import { tocPlugin } from '@vuepress/plugin-toc'

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

Differences with Markdown TOC Syntax

Similar to the Table of Contents Markdown Syntax, the TOC component provided by this plugin can be used in your markdown content directly:

<!-- 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 by setting the 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 prop.

renderOptions

• Type: Partial<TocPropsOptions>

• Default: {}

• Details:

  Override the default values of the component renderOptions prop.

Component Props

The TOC component also accepts props for customization.

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

headers

• Type: PageHeader[]

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

• Default:

  See GetHeadersOptions, it can be overridden by headersOptions in plugin options.

• Details:

  Customize header extracting behavior.

renderOptions

• Type: TocRenderOptions

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 in plugin options.

  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:

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

This plugin has been integrated into the default theme.

Usage

npm i -D @vuepress/plugin-back-to-top@next

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:

@use 'pkg:@vuepress/helper';

$back-to-top-icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="4" d="M24.008 14.1V42M12 26l12-12 12 12M12 6h24"/></svg>';

:root {
  --back-to-top-z-index: 5;
  --back-to-top-icon: #{helper.encode-svg($back-to-top-icon)};
  --back-to-top-c-bg: var(--vp-c-bg);
  --back-to-top-c-accent-bg: var(--vp-c-accent-bg);
  --back-to-top-c-accent-hover: var(--vp-c-accent-hover);
  --back-to-top-c-shadow: var(--vp-c-shadow);
  --back-to-top-c-icon: currentcolor;
}

Usage

npm i -D @vuepress/plugin-catalog@next

import { catalogPlugin } from '@vuepress/plugin-catalog'

export default {
  plugins: [
    catalogPlugin({
      // Your options
    }),
  ],
}

First, you should set catalog info in routeMeta:

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 to extract catalog info from route meta.

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)

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

• Type: 1 | 2 | 3
• Default: 3
• Details: Maximum depth of catalog items.

index

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

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

  404 pages will be automatically excluded.

component

• Type: string
• Details: Component name to use as the catalog component.

locales

• Type: CatalogPluginLocaleConfig

  interface CatalogPluginLocaleData {
    /**
     * Catalog title
     */
    title: string
  
    /**
     * Empty hint
     */
    empty: string
  }
  
  interface CatalogPluginLocaleConfig {
    [localePath: string]: Partial<CatalogPluginLocaleData>
  }

• Details: Locales configuration for catalog component.

Client Options

defineCatalogInfoGetter

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.

Styles

You can customize catalog styles via CSS variables:

:root {
  --catalog-c-accent: var(--vp-c-accent);
  --catalog-c-accent-text: var(--vp-c-accent-text);
  --catalog-c-control: var(--vp-c-bg-alt);
  --catalog-c-control-hover: var(--vp-c-bg-alt);
  --catalog-c-divider: var(--vp-c-divider);
  --catalog-header-offset: var(--header-offset, 3.6rem);
}

This plugin has been integrated into the default theme.

Usage

npm i -D @vuepress/plugin-copy-code@next

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

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

  .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

  interface CopyCodePluginLocaleData {
    /**
     * Copy text
     */
    copy: string
  
    /**
     * Copied text
     */
    copied: string
  }
  
  interface CopyCodePluginLocaleConfig {
    [localePath: string]: Partial<CopyCodePluginLocaleData>
  }

• Details:

  Locales config for copy code plugin.

• Example:

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

Styles

You can customize the icon of the copy button via CSS variables:

@use 'pkg:@vuepress/helper';

$copy-icon: '<svg viewBox="0 0 24 24"><path fill="none" stroke="#808080" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" d="M9 5H7a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2h-2M9 5a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2M9 5a2 2 0 0 1 2-2h2a2 2 0 0 1 2 2"/></svg>';
$copied-icon: '<svg viewBox="0 0 24 24"><path fill="none" stroke="#808080" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" d="M9 5H7a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2h-2M9 5a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2M9 5a2 2 0 0 1 2-2h2a2 2 0 0 1 2 2m-6 9l2 2 4-4"/></svg>';

:root {

Usage

npm i -D @vuepress/plugin-copyright@next

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

  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

  interface CopyrightPluginLocaleData {
    /**
     * Author text
     *
     * `:author` will be replaced by author
     */
    author: string
  
    /**
     * License text
     *
     * `:license` will be replaced by current license
     */
    license: string
  
    /**
     * Link text
     *
     * `:link` will be replaced by current page link
     */
    link: string
  }
  
  interface CopyrightPluginLocaleConfig {
    [localePath: string]: Partial<CopyrightPluginLocaleData>
  }

• Details: Locale config for copyright plugin.

• Example:

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

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

Usage

npm i -D @vuepress/plugin-icon@next

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.

::icon =16 /red:: <!-- <VPIcon icon="icon" color="red" size="16px" /> -->

::icon rotate vertical-align=middle:: <!-- <VPIcon icon="icon rotate" vertical-align="middle" /> -->

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:

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

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

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

<!-- 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.

Iconfont

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

Import Icon

Search and find the icon you want to use, and click the "Add to Library" button on the icon

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.

Generate Links

Click the "Font Class" button above the project and click Generate.

Then set assets option with the generated link.

Images

Images links are supported with any icon types (relative links are NOT supported).

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

  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

  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

• 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

This plugin has been integrated into the default theme.

Usage

npm i -D @vuepress/plugin-medium-zoom@next

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

Styles

You can customize most of the zoom styles via zoomOptions, while this plugin also provides some CSS variables for additional customization:

:root {
  --medium-zoom-z-index: 100;
  --medium-zoom-c-bg: var(--vp-c-bg-elv, #fff);
  --medium-zoom-opacity: 1;
}

Composition API

useMediumZoom

• Details:

  Returns the Zoom instance that is used by this plugin, so that you can use the instance 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 as the default parameter. It will help you refresh the zoomable images for current page.

• Example:

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()
    })
  },
}

Usage

npm i -D @vuepress/plugin-notice@next

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:

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.

Options

config

• Type: NoticeOptions[]

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

This plugin has been integrated into the default theme.

Usage

npm i -D @vuepress/plugin-nprogress@next

import { nprogressPlugin } from '@vuepress/plugin-nprogress'

export default {
  plugins: [nprogressPlugin()],
}

Styles

You can customize the style of the progress bar via CSS variables:

:root {
  --nprogress-c: var(--vp-c-accent);
  --nprogress-z-index: 1031;
}

Usage

npm i -D @vuepress/plugin-photo-swipe@next

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

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

  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:

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

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

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:

<script setup lang="ts">
import { createPhotoSwipe } from '@vuepress/plugin-photo-swipe/client'
import { onMounted, onUnmounted } from 'vue'

let state: PhotoSwipeState | null = null

const openPhotoSwipe = (index: number): void => {
  state?.open(index - 1)
}

onMounted(async () => {
  // Create a new PhotoSwipe instance with image links
  state = await createPhotoSwipe(
    [
      'https://example.com/image1.png',
      'https://example.com/image2.png',
      'https://example.com/image3.png',
    ],
    {
      // PhotoSwipe options
    },
  )
})

onUnmounted(() => {
  state?.destroy()
})
</script>

<template>
  <button v-for="i in 3" :key="i" type="button" @click="openPhotoSwipe(i)">
    Open photo {{ i }}
  </button>
</template>

Styles

You can customize the style via CSS variables:

:root {
  --photo-swipe-c-bullet: var(--vp-c-bg-elv);
  --photo-swipe-c-bullet-active: var(--vp-c-accent);
}

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

npm i -D @vuepress/plugin-watermark@next

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 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 for configuration options.

Usage

npm i -D @vuepress/plugin-remove-pwa@next

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.

Usage

npm i -D @vuepress/plugin-append-date@next

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

This plugin has been integrated into the default theme.

Usage

npm i -D @vuepress/plugin-links-check@next

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:

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

This plugin simplifies the use of markdown-it-container, but also retains its original capabilities.

Usage

npm i -D @vuepress/plugin-markdown-container@next

import { markdownContainerPlugin } from '@vuepress/plugin-markdown-container'

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

Container Syntax

::: <type> [info]
[content]
:::

• The type is required and should be specified via type option.
• The info is optional, and the default value can be specified via defaultInfo in locales option.
• The content can be any valid markdown content.

Options

type

• Type: string

• Required: Yes

• Details:

  The type of the container.

  It will be used as the name param of markdown-it-container.

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 option.

• Example:

export default {
  plugins: [
    markdownContainerPlugin({
      type: 'tip',
      locales: {
        '/': {
          defaultInfo: 'TIP',
        },
        '/zh/': {
          defaultInfo: '提示',
        },
      },
    }),
  ],
}

• Reference:
  • Guide > I18n

before

• Type: (info: string) => string

• Default:

  ;(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.

  This option will not take effect if you don't specify the after option.

after

• Type: (info: string) => string

• Default:

  ;(): string => '</div>\n'

• Details:

  A function to render the ending tag of the container.

  The first param is the info part of container syntax.

  This option will not take effect if you don't specify the before option.

render

• Type:

  type MarkdownItContainerRenderFunction = (
    tokens: Token[],
    index: number,
    options: unknown,
    env: MarkdownEnv,
    self: Renderer,
  ) => string

• Details:

  The render option of markdown-it-container.

  This plugin uses a default render function. If you specify this option, the default render function will be replaced, and the locales, before and after options will be ignored.

validate

• Type: (params: string) => boolean

• Details:

  The validate option of markdown-it-container.

marker

• Type: string

• Default: ':'

• Details:

  The marker option of markdown-it-container.

Usage

npm i -D @vuepress/plugin-markdown-ext@next

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

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)

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 :

  ```component ComponentName
  # component data here
  ```

• JSON:

  ```component ComponentName
  {
    // component data here
  }
  ```

v-pre

You can use any mustache syntax as raw text in v-pre container:

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

  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.

cjkFriendly

• Type: boolean
• Details: Whether to enable CJK-friendly support for emphasis marks. When not set, automatically enabled for CJK languages (zh, ja, ko) detected in site configuration.

Usage

npm i -D @vuepress/plugin-markdown-file-tree@next

import { markdownFileTreePlugin } from '@vuepress/plugin-markdown-file-tree'

export default {
  plugins: [markdownFileTreePlugin()],
}

Syntax

In the ::: file-tree container, use the built-in Markdown unordered list syntax to specify the file and directory structure.
Use nested list items to create subdirectories; if you want a directory to not display its contents, add a trailing slash / to the list item.

The following syntax can be used to customize the appearance of the file tree:

• By bolding the filename or directory name, you can highlight it, e.g. **README.md**
• By appending additional text starting with # to the filename or directory name, you can add a comment to the file or directory, e.g. README.md # a README file
• By prefixing the filename or directory name with ++ or --, you can mark the file or directory as added or deleted, e.g. ++ new-file.md or -- old-file.md
• Use ... or … as the name to add placeholder files and directories.
• Add any text after :::file-tree container to add a title to the file tree.

Example

Input：

::: file-tree

- docs
  - .vuepress
    - ++ config.ts
  - -- page1.md
  - README.md
- theme # a **theme** directory
  - client
    - components
      - **Navbar.vue**
    - composables
      - useNavbar.ts
    - styles
      - navbar.css
    - config.ts
  - node/
- package.json
- pnpm-lock.yaml
- .gitignore
- README.md
- …
  :::

Output：

This plugin has been integrated into the default theme.

Usage

npm i -D @vuepress/plugin-markdown-hint@next

import { markdownHintPlugin } from '@vuepress/plugin-markdown-hint'

export default {
  plugins: [
    markdownHintPlugin({
      // Enable hint container, true by default
      hint: true,
      // Enable gfm alert
      alert: true,
    }),
  ],
}