VuePressVuePress
  • Introduction
  • Getting Started
  • Configuration
  • Page
  • Markdown
  • Assets
  • I18n
  • Deployment
  • Theme
  • Plugin
  • Bundler
  • Migrating from v1
  • Troubleshooting
  • Core

    • CLI
    • Config
    • Frontmatter
    • Built-in Components
    • Plugin API
    • Theme API
    • Client API
    • Node API
  • Bundlers

    • Vite
    • Webpack
  • Ecosystem

    • Default Theme
    • Plugins
  • Advanced

    • Architecture
    • Writing a Plugin
    • Writing a Theme
    • Cookbook
  • Resources

    • Ecosystem
    • MarketPlace
    • Contributing Guide
  • Changelog
  • v1.x
  • v0.x
  • English
  • 简体中文
GitHub
  • Introduction
  • Getting Started
  • Configuration
  • Page
  • Markdown
  • Assets
  • I18n
  • Deployment
  • Theme
  • Plugin
  • Bundler
  • Migrating from v1
  • Troubleshooting
  • Core

    • CLI
    • Config
    • Frontmatter
    • Built-in Components
    • Plugin API
    • Theme API
    • Client API
    • Node API
  • Bundlers

    • Vite
    • Webpack
  • Ecosystem

    • Default Theme
    • Plugins
  • Advanced

    • Architecture
    • Writing a Plugin
    • Writing a Theme
    • Cookbook
  • Resources

    • Ecosystem
    • MarketPlace
    • Contributing Guide
  • Changelog
  • v1.x
  • v0.x
  • English
  • 简体中文
GitHub
  • Core

    • Command Line Interface
    • Config
    • Frontmatter
    • Built-in Components
    • Plugin API
    • Theme API
    • Client API
    • Node API
  • Bundlers

    • Vite
    • Webpack
  • Ecosystem

    • Default Theme
    • Plugins

Theme API

A VuePress theme also works as a plugin, so Theme API can accept all the options of Plugin API with following differences.

Basic Options

name

  • Type: string

  • Details:

    Name of the theme.

    It should follow the naming convention, and ensure consistency with the package name when publishing to NPM:

    • Non-scoped: vuepress-theme-foo
    • Scoped: @org/vuepress-theme-foo

multiple

  • Details:

    A theme should never be used multiple times, so this option is not supported in theme API.

Theme Specific Options

extends

  • Type: Theme

  • Details:

    The theme to inherit.

    All of the Theme API of the parent theme will be inherited, but the child theme will not override the parent theme directly. Theme specific options will override according to following rules:

    • plugins: When a same plugin is used in both child and parent theme, if the plugin does not support to be used multiple times, only the one used in the child theme will take effect.
    • templateBuild / templateDev: Child theme templates will override parent theme templates.

    Multi-level inheritance is supported, i.e. theme B could be extended from theme A, and then theme C could be extended from theme B. In other words, a theme could have a parent theme, a grandparent theme and so on.

  • Example:

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

const __dirname = getDirname(import.meta.url)

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

plugins

  • Type: (Plugin | Plugin[])[]

  • Details:

    Plugins to use in the theme.

  • Also see:

    • Config > plugins

templateBuild

  • Type: string

  • Details:

    Specify the path of the HTML template for build.

    It would override the default value of templateBuild, and could be overridden by user config.

  • Also see:

    • Config > templateBuild

templateBuildRenderer

  • Type: TemplateRenderer

  • Details:

    Specify the HTML template renderer to be used for build.

    It would override the default value of templateBuildRenderer, and could be overridden by user config.

  • Also see:

    • Config > templateBuildRenderer

templateDev

  • Type: string

  • Details:

    Specify the HTML template for dev.

    It would override the default value of templateDev, but could be overridden by user config.

  • Also see:

    • Config > templateDev
Edit this page on GitHub
Last Updated:: 2/6/24, 3:46 PM
Contributors: meteorlxy
Prev
Plugin API
Next
Client API