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

Config

Site Config

base

  • Type: string

  • Default: /

  • Details:

    The base URL the site will be deployed at.

    You will need to set this if you plan to deploy your site under a sub path. It should always start and end with a slash. For example, if you plan to deploy your site to GitHub pages at https://foo.github.io/bar/, then you should set base to "/bar/".

    The base is automatically prepended to the URLs that start with / in other options, so you only need to specify it once. (Except for attrs of head)

    Notice that base should be an absolute URL pathname starting and ending with / .

  • Also see:

    • Guide > Assets > Base Helper
    • Guide > Deployment

lang

  • Type: string

  • Default: en-US

  • Details:

    Language for the site.

    This will be the lang attribute of the <html> tag in the rendered HTML.

    This can be specified in different locales.

  • Also see:

    • Config > locales
    • Frontmatter > lang

title

  • Type: string

  • Default: ''

  • Details:

    Title for the site.

    This will be the suffix for all page titles, and displayed in the navbar in the default theme.

    This can be specified in different locales.

  • Also see:

    • Config > locales

description

  • Type: string

  • Default: ''

  • Details:

    Description for the site.

    This will be the content attribute of <meta name="description" /> tag in the rendered HTML, which will be overrode by the description field of page frontmatter.

    This can be specified in different locales.

  • Also see:

    • Config > locales
    • Frontmatter > description

head

  • Type: HeadConfig[]

  • Default: []

  • Details:

    Extra tags to inject into the <head> tag in the rendered HTML.

    You can specify each tag in the form of [tagName, { attrName: attrValue }, innerHTML?].

    This can be specified in different locales.

    Notice that if the attrValue is a pathname, it will be kept as-is without prepending base automatically, so remember to prepend it manually if needed.

  • Example:

    To add a custom favicon:

export default {
  head: [['link', { rel: 'icon', href: '/images/logo.png' }]],
}

Rendered as:

<head>
  <link rel="icon" href="/images/logo.png" />
</head>
  • Also see:
    • Config > locales
    • Frontmatter > head

locales

  • Type: { [path: string]: Partial<SiteLocaleData> }

  • Default: {}

  • Details:

    Specify locales for i18n support.

    Acceptable fields:

    • lang
    • title
    • description
    • head
  • Also see:

    • Guide > I18n

Theme Config

theme

  • Type: Theme

  • Details:

    Set the theme of your site.

    If this option is not set, the default theme will be used.

  • Also see:

    • Guide > Theme
    • Default Theme > Config

Bundler Config

bundler

  • Type: Bundler

  • Details:

    Set the bundler of your site.

    If this option is not set, the default bundler will be used:

    • With vuepress or vuepress-vite, the default bundler is vite.
    • With vuepress-webpack, the default bundler is webpack.
  • Also see:

    • Guide > Bundler
    • Bundlers > Vite
    • Bundlers > Webpack

Common Config

dest

  • Type: string

  • Default: `${sourceDir}/.vuepress/dist`

  • Details:

    Specify the output directory for vuepress build command.

temp

  • Type: string

  • Default: `${sourceDir}/.vuepress/.temp`

  • Details:

    Specify the directory for temporary files.

Warning

Since VuePress will load temp files during dev and build, the temp directory should be inside project root to resolve dependencies correctly.

cache

  • Type: string

  • Default: `${sourceDir}/.vuepress/.cache`

  • Details:

    Specify the directory for cache files.

public

  • Type: string

  • Default: `${sourceDir}/.vuepress/public`

  • Details:

    Specify the directory for public files.

  • Also see:

    • Guide > Assets > Public Files

debug

  • Type: boolean

  • Default: false

  • Details:

    Enable debug mode or not.

    This would be helpful for developers. Also, we are using debug package for debug logging, which can be enabled via DEBUG=vuepress* environment variable.

pagePatterns

  • Type: string[]

  • Default: ['**/*.md', '!.vuepress', '!node_modules']

  • Details:

    Specify the patterns of files you want to be resolved as pages. The patterns are relative to the source directory.

permalinkPattern

  • Type: string | null

  • Default: null

  • Details:

    Specify the pattern to generate permalink.

    This will be overrode by the permalinkPattern field of page frontmatter.

  • Also see:

    • Frontmatter > permalinkPattern

Dev Config

host

  • Type: string

  • Default: '0.0.0.0'

  • Details:

    Specify the host to use for the dev server.

port

  • Type: number

  • Default: 8080

  • Details:

    Specify the port to use for the dev server.

open

  • Type: boolean

  • Default: false

  • Details:

    Whether to open the browser after dev-server had been started.

templateDev

  • Type: string

  • Default: '@vuepress/client/templates/dev.html'

  • Details:

    Specify the path of the HTML template to be used for dev.

Build Config

shouldPreload

  • Type: ((file: string, type: string) => boolean)) | boolean

  • Default: true

  • Details:

    A function to control what files should have <link rel="preload"> resource hints generated. Set to true or false to enable or disable totally.

    By default, only those files that are required by current page will be preloaded. So you can keep it true in most cases.

shouldPrefetch

  • Type: ((file: string, type: string) => boolean)) | boolean

  • Default: true

  • Details:

    A function to control what files should have <link rel="prefetch"> resource hints generated. Set to true or false to enable or disable for all files.

    If you set it to true, all files that required by other pages will be prefetched. This is good for small sites, which will speed up the navigation, but it might not be a good idea if you have lots of pages in your site.

templateBuild

  • Type: string

  • Default: '@vuepress/client/templates/build.html'

  • Details:

    Specify the path of the HTML template to be used for build.

templateBuildRenderer

  • Type: TemplateRenderer

  • Default: templateRenderer

  • Details:

    Specify the HTML template renderer to be used for build.

Markdown Config

markdown

  • Type: MarkdownOptions

  • Default: {}

  • Details:

    Configure VuePress built-in Markdown syntax extensions.

    It accepts all options of markdown-it, and the following additional options.

  • Also see:

    • markdown-it > Init with presets and options
    • Guide > Markdown > Syntax Extensions

markdown.anchor

  • Type: AnchorPluginOptions | false

  • Default:

const defaultOptions = {
  level: [1, 2, 3, 4, 5, 6],
  permalink: anchorPlugin.permalink.headerLink({
    class: 'header-anchor',
    safariReaderFix: true,
  }),
}
  • Details:

    Options for markdown-it-anchor.

    Set to false to disable this plugin.

  • Also see:

    • Guide > Markdown > Syntax Extensions > Header Anchors

markdown.assets

  • Type: AssetsPluginOptions | false

  • Details:

    Options for VuePress built-in markdown-it assets plugin.

    Set to false to disable this plugin.

Caution

You should not configure it unless you understand what it is for.

markdown.component

  • Type: undefined | false

  • Details:

    Options for @mdit-vue/plugin-component.

    Set to false to disable this plugin.

Caution

You should not configure it unless you understand what it is for.

markdown.emoji

  • Type: EmojiPluginOptions | false

  • Details:

    Options for markdown-it-emoji.

    Set to false to disable this plugin.

  • Also see:

    • Guide > Markdown > Syntax Extensions > Emoji

markdown.frontmatter

  • Type: FrontmatterPluginOptions | false

  • Details:

    Options for @mdit-vue/plugin-frontmatter.

    Set to false to disable this plugin.

  • Also see:

    • Guide > Page > Frontmatter
    • Node API > Page Properties > frontmatter

Caution

You should not configure it unless you understand what it is for.

markdown.headers

  • Type: HeadersPluginOptions | false

  • Default:

const defaultOptions = {
  level: [2, 3],
}
  • Details:

    Options for @mdit-vue/plugin-headers.

    Set to false to disable this plugin.

  • Also see:

    • Node API > Page Properties > headers

markdown.importCode

  • Type: ImportCodePluginOptions | false

  • Details:

    Options for VuePress built-in markdown-it import-code plugin.

    Set to false to disable this plugin.

  • Also see:

    • Guide > Markdown > Syntax Extensions > Import Code Blocks

markdown.importCode.handleImportPath

  • Type: (str: string) => string

  • Default: (str) => str

  • Details:

    A function to handle the import path of the import code syntax.

markdown.links

  • Type: LinksPluginOptions | false

  • Details:

    Options for VuePress built-in markdown-it links plugin.

    It will convert the tag of internal links to internalTag, and add extra attributes and icon to external links.

    Set to false to disable this plugin.

  • Also see:

    • Guide > Markdown > Syntax Extensions > Links

markdown.links.internalTag

  • Type: 'a' | 'RouteLink' | 'RouterLink'

  • Default: 'RouteLink'

  • Details:

    Tag for internal links.

    By default, this plugin will transform internal links to RouteLink.

markdown.links.externalAttrs

  • Type: Record<string, string>

  • Default: { target: '_blank', rel: 'noopener noreferrer' }

  • Details:

    Additional attributes for external links.

markdown.sfc

  • Type: SfcPluginOptions | false

  • Details:

    Options for @mdit-vue/plugin-sfc.

    Set to false to disable this plugin.

  • Also see:

    • Cookbook > Markdown and Vue SFC
    • Node API > Page Properties > sfcBlocks

Caution

You should not configure it unless you understand what it is for.

markdown.slugify

  • Type: (str: string) => string

  • Details:

    The default slugify function.

markdown.title

  • Type: undefined | false

  • Details:

    Options for @mdit-vue/plugin-title.

    Set to false to disable this plugin.

Caution

You should not configure it unless you understand what it is for.

markdown.toc

  • Type: TocPluginOptions | false

  • Default:

const defaultOptions = {
  level: [2, 3],
}
  • Details:

    Options for @mdit-vue/plugin-toc.

    Set to false to disable this plugin.

  • Also see:

    • Guide > Markdown > Syntax Extensions > Table of Contents

markdown.vPre.block

  • Type: boolean

  • Default: true

  • Details:

    Add v-pre directive to <pre> tag of code block or not.

  • Also see:

    • Guide > Markdown > Syntax Extensions > Code Blocks > Wrap with v-pre

markdown.vPre.inline

  • Type: boolean

  • Default: true

  • Details:

    Add v-pre directive to <code> tag of inline code or not.

  • Also see:

    • Guide > Markdown > Syntax Extensions > Code Blocks > Wrap with v-pre

Plugin Config

plugins

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

  • Details:

    Plugins to use.

    This option accepts an array, each item of which could be a plugin or an array of plugins.

  • Also see:

    • Guide > Plugin

Plugin API

User config file also works as a VuePress plugin, so all of the Plugin APIs are available except the name and multiple options.

Please check out Plugin API Reference for a full list of Plugin APIs.

Edit this page on GitHub
Last Updated:: 7/14/24, 2:29 PM
Contributors: meteorlxy, Mr.Hope, lebennington
Prev
Command Line Interface
Next
Frontmatter