# 配置

# 基本配置

# base

类型: string
默认值: /

部署站点的基础路径，如果你想让你的网站部署到一个子路径下，你将需要设置它。如 GitHub pages，如果你想将你的网站部署到 https://foo.github.io/bar/，那么 base 应该被设置成 "/bar/"，它的值应当总是以斜杠开始，并以斜杠结束。

base 将会作为前缀自动地插入到所有以 / 开始的其他选项的链接中，所以你只需要指定一次。

参考:

# title

类型: string
默认值: undefined

网站的标题，它将会被用作所有页面标题的前缀，同时，默认主题下，它将显示在导航栏（navbar）上。

# description

类型: string
默认值: undefined

网站的描述，它将会以 <meta> 标签渲染到当前页面的 HTML 中。

# head

类型: Array
默认值: []

额外的需要被注入到当前页面的 HTML <head> 中的标签，每个标签都可以以 [tagName, { attrName: attrValue }, innerHTML?] 的格式指定，举个例子，增加一个自定义的 favicon：

module.exports = {
  head: [
    ['link', { rel: 'icon', href: '/logo.png' }]
  ]
}

# host

类型: string
默认值: '0.0.0.0'

指定用于 dev server 的主机名。

# port

类型: number
默认值: 8080

指定 dev server 的端口。

# temp

Type: string
Default: /path/to/@vuepress/core/.temp

指定客户端文件的临时目录。

# dest

类型: string
默认值: .vuepress/dist

指定 vuepress build 的输出目录。如果传入的是相对路径，则会基于 process.cwd() 进行解析。

# locales

类型: { [path: string]: Object }
默认值: undefined

提供多语言支持的语言配置。具体细节请查看多语言支持。

# shouldPrefetch

类型: Function
默认值: () => true

一个函数，用来控制对于哪些文件，是需要生成 <link rel="prefetch"> 资源提示的。请参考 shouldPrefetch (opens new window)。

# cache

类型: boolean|string
默认值: true

VuePress 默认使用了 cache-loader (opens new window) 来大大地加快 webpack 的编译速度。

此选项可以用于指定 cache 的路径，同时也可以通过设置为 false 来在每次构建之前删除 cache。

提示

这个选项也可以通过命令行来使用：

vuepress dev docs --cache .cache # 设置 cache 路径
vuepress dev docs --no-cache     # 在每次构建前删除 cache

# extraWatchFiles

类型: Array
默认值: []

指定额外的需要被监听的文件。

你可以监听任何想监听的文件，文件变动将会触发 vuepress 重新构建，并实时更新。

module.exports = {
  extraWatchFiles: [
    '.vuepress/foo.js', // 使用相对路径
    '/path/to/bar.js'   // 使用绝对路径
  ]
}

# patterns

Type: Array
Default: ['**/*.md', '**/*.vue']

Specify which pattern of files you want to be resolved.

# Styling

# palette.styl

如果要对默认预设 (opens new window)的样式进行简单的替换，或者定义一些变量供以后使用，你可以创建一个 .vuepress/styles/palette.styl 文件。

你可以调整的一些变量如下:

// 颜色
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961

// 布局
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px
$homePageWidth = 960px

// 响应式变化点
$MQNarrow = 959px
$MQMobile = 719px
$MQMobileNarrow = 419px

警告

你应该只在这个文件中定义变量。因为 palette.styl 将在根的 stylus 配置文件的末尾引入，作为配置，它将被多个文件使用，所以一旦你在这里写了样式，你的样式就会被多次复制。

# index.styl

VuePress 提供了一种添加额外样式的简便方法。你可以创建一个 .vuepress/styles/index.styl 文件。这是一个 Stylus (opens new window) 文件，但你也可以使用正常的 CSS 语法。

.content {
  font-size 30px
}

注意

由于背后的行为，不论是在 palette.styl 或是 index.styl ，都不能透过 @import / @require (opens new window) 從相对路径引用一般的 .css 样式表。

那如果你非得要 import / require 一般的 `.css` 样式表呢？

使用绝对路径。

从 npm package 引用档案：

@require '~my-css-package/style.css'

引用本地档案：

因为已经有 alias 这个选项，使用 webpack 别名会是最简单的方式，举例如下：

// config.js
 alias: {
    'styles': path.resolve(__dirname, './styles')
  }

@require '~styles/style.css'

参考:

为什么不能把 palette.styl 和 index.styl 合并到一个 API?

# 主题

# theme

类型: string
默认值: undefined

当你使用自定义主题的时候，需要指定它。

参考:

使用主题.

# themeConfig

类型: Object
默认值: {}

为当前的主题提供一些配置，这些选项依赖于你正在使用的主题。

也可以参考:

默认主题。

# Pluggable

# plugins

类型: Object|Array
默认值: undefined

请参考 plugin > Using a plugin 来使用一个插件。

# Markdown

# markdown.lineNumbers

类型: boolean
默认值: undefined

是否在每个代码块的左侧显示行号。

参考:

行号

# markdown.slugify

类型: Function
默认值: source (opens new window)

一个将标题文本转换为 slug 的函数。修改它会影响标题、目录、以及侧边栏链接的 id 和链接。

# markdown.anchor

类型: Object
默认值: { permalink: true, permalinkBefore: true, permalinkSymbol: '#' }

markdown-it-anchor (opens new window) 的选项。

# markdown.pageSuffix

类型: string
默认值: .html

Option to customize internal links to be compatible when using the vuepress-plugin-clean-urls (opens new window).

# markdown.externalLinks

类型: Object
默认值: { target: '_blank', rel: 'noopener noreferrer' }

这个键值对将会作为特性被增加到是外部链接的 <a> 标签上，默认的选项将会在新窗口中打开一个该外部链接。

# markdown.toc

类型: Object
默认值: { includeLevel: [2, 3] }

markdown-it-table-of-contents (opens new window) 的选项。

# markdown.plugins

你可以使用 markdown.plugins 来安装 markdown-it 插件。它的使用方法与安装一个 VuePress 插件类似。你可以使用 Babel 语法或对象语法。markdown-it- 前缀同样是可以忽略的。

module.exports = {
  markdown: {
    plugins: [
      '@org/foo', // 等价于 @org/markdown-it-foo，如果对应的包存在
      ['markdown-it-bar', {
        // 提供你的选项
      }]
    ]
  }
}

module.exports = {
  markdown: {
    plugins: {
      '@org/foo': {}
      'markdown-it-bar': {
        // 提供你的选项
      }
    }
  }
}

# markdown.extendMarkdown

类型: Function
默认值: undefined

一个用于修改当前的 markdown-it (opens new window) 实例的默认配置，或者应用额外的插件的函数，举例如下：

module.exports = {
  markdown: {
    extendMarkdown: md => {
      md.set({ breaks: true })
      md.use(require('markdown-it-xxx'))
    }
  }
}

提示

这个选项也被 Plugin API 所支持。

# markdown.extractHeaders

类型: Array
默认值: ['h2', 'h3']

Markdown 文件的 headers (标题 & 小标题) 会在准备阶段被提取出来，并存储在 this.$page.headers 中。默认情况下，VuePress 会提取 h2 和 h3 标题。你可以通过这个选项来修改提取出的标题级别。

module.exports = {
  markdown: {
    extractHeaders: [ 'h2', 'h3', 'h4' ]
  }
}

# 构建流程

# postcss

类型: Object
默认值: { plugins: [require('autoprefixer')] }

postcss-loader (opens new window) 的选项，请注意，指定这个值，将会覆盖内置的 autoprefixer，所以你需要自己将它加进去。

# stylus

类型: Object
默认值: { preferPathResolver: 'webpack' }

stylus-loader (opens new window) 的选项。

# scss

类型: Object
默认值: {}

加载 *.scss 文件的 sass-loader (opens new window) 的选项。

# sass

类型: Object
默认值: { indentedSyntax: true }

加载 *.sass 文件的 sass-loader (opens new window) 的选项。

# less

类型: Object
Default: {}

less-loader (opens new window) 的选项。

# configureWebpack

类型: Object | Function
默认值: undefined

用于修改内部的 Webpack 配置。如果给定一个对象，那么它将会被 webpack-merge (opens new window) 合并到最终的配置中，如果给定一个函数，它将会接受 config 作为第一个参数，以及 isServer 作为第二个参数，你可以直接更改 config，也可以返回一个待合并的对象。

module.exports = {
  configureWebpack: (config, isServer) => {
    if (!isServer) {
      // 修改客户端的 webpack 配置
    }
  }
}

# chainWebpack

类型: Function
默认值: undefined

通过 webpack-chain (opens new window) 来修改内部的 Webpack 配置。

module.exports = {
  chainWebpack: (config, isServer) => {
    // config 是 ChainableConfig 的一个实例
  }
}

# 浏览器兼容性

# evergreen

类型: boolean | Function
默认值: false

如果你的对象只有那些 “常青树” 浏览器，你可以将其设置成 true，这将会禁止 ESNext 到 ES5 的转译以及对 IE 的 polyfills，同时会带来更快的构建速度和更小的文件体积。