Theme API

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

Basic Options


  • Type: string

  • Details:

    Name of the theme.

    It should follow the naming convention:

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


  • Details:

    A theme should never be used multiple times, so this option should not be set.

Theme Specific Options


  • Type: string | Record<string, string>

  • Details:

    Specify layout components of the theme.

    It accepts absolute path of the layouts directory. All the .vue,.ts,.js files in the directory will be registered as layout components.

    It also accepts a plain object, of which the key is the layout name and the value is the absolute path of the layout file.

    A theme must have at least two layouts: Layout and 404.

  • Example:

The layout directory:

  1. layouts
  2. ├─ Layout.vue
  3. ├─ 404.vue
  4. └─ FooBar.vue

Using the absolute path of layout directory:

  1. module.exports = {
  2. layouts: path.resolve(__dirname, 'path/to/layouts'),
  3. }

Using a plain object is equivalent:

  1. module.exports = {
  2. layouts: {
  3. Layout: path.resolve(__dirname, 'path/to/layouts/Layout.vue'),
  4. 404: path.resolve(__dirname, 'path/to/layouts/404.vue'),
  5. FooBar: path.resolve(__dirname, 'path/to/layouts/FooBar.vue'),
  6. },
  7. }


  • Type: string

  • Details:

    The name of 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.

    If a layout with the same name is registered in both the child theme and the parent theme, the layout of the child theme will have a higher priority.

    Multi-level inheritance is not supported.

  • Example:

  1. module.exports = {
  2. // inherit the default theme
  3. extends: '@vuepress/theme-default',
  4. // override the `404` layout
  5. layouts: {
  6. 404: path.resolve(__dirname, 'path/to/404.vue'),
  7. },
  8. }