配置

基本配置

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:
  1. module.exports = {
  2. head: [
  3. ['link', { rel: 'icon', href: '/logo.png' }]
  4. ]
  5. }

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

cache

  • 类型: boolean|string
  • 默认值: trueVuePress 默认使用了 cache-loader 来大大地加快 webpack 的编译速度。

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

提示

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

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

extraWatchFiles

  • 类型: Array
  • 默认值: []指定额外的需要被监听的文件。

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

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

Styling

palette.styl

如果要对默认预设的样式应用简单的颜色替换,或者定义一些颜色变量供以后使用,你可以创建一个 .vuepress/styles/palette.styl 文件。

你可以调整一些颜色变量:

  1. // 默认值
  2. $accentColor = #3eaf7c
  3. $textColor = #2c3e50
  4. $borderColor = #eaecef
  5. $codeBgColor = #282c34

Note

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

index.styl

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

  1. .content {
  2. font-size 30px
  3. }

主题

theme

  • 类型: string
  • 默认值: undefined当你使用自定义主题的时候,需要指定它。

参考:

themeConfig

  • 类型: Object
  • 默认值: {}为当前的主题提供一些配置,这些选项依赖于你正在使用的主题。

也可以参考:

Pluggable

plugins

Markdown

markdown.lineNumbers

  • 类型: boolean
  • 默认值: undefined是否在每个代码块的左侧显示行号。

参考:

markdown.slugify

  • 类型: Function
  • 默认值: source一个将标题文本转换为 slug 的函数。修改它会影响 标题目录、以及侧边栏链接的 id 和 链接。

markdown.anchor

  • 类型: Object
  • 默认值: { permalink: true, permalinkBefore: true, permalinkSymbol: '#' }markdown-it-anchor 的选项。
  • 类型: Object
  • 默认值: { target: '_blank', rel: 'noopener noreferrer' }这个键值对将会作为特性被增加到是外部链接的 <a> 标签上,默认的选项将会在新窗口中打开一个该外部链接。

markdown.toc

markdown.plugins

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

  1. module.exports = {
  2. markdown: {
  3. plugins: [
  4. '@org/foo', // 等价于 @org/markdown-it-foo,如果对应的包存在
  5. ['markdown-it-bar', {
  6. // 提供你的选项
  7. }]
  8. ]
  9. }
  10. }

or

  1. module.exports = {
  2. markdown: {
  3. plugins: {
  4. '@org/foo': {}
  5. 'markdown-it-bar': {
  6. // 提供你的选项
  7. }
  8. }
  9. }
  10. }

markdown.extendMarkdown

  • 类型: Function
  • 默认值: undefined一个用于修改当前的 markdown-it 实例的默认配置,或者应用额外的插件的函数,举例如下:
  1. module.exports = {
  2. markdown: {
  3. extendMarkdown: md => {
  4. md.set({ breaks: true })
  5. md.use(require('markdown-it-xxx'))
  6. }
  7. }
  8. }

提示

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

构建流程

postcss

  • 类型: Object
  • 默认值: { plugins: [require('autoprefixer')] }postcss-loader 的选项,请注意,指定这个值,将会覆盖内置的 autoprefixer,所以你需要自己将它加进去。

stylus

  • 类型: Object
  • 默认值: { preferPathResolver: 'webpack' }stylus-loader 的选项。

scss

  • 类型: Object
  • 默认值: {}加载 *.scss 文件的 sass-loader 的选项。

sass

  • 类型: Object
  • 默认值: { indentedSyntax: true }加载 *.sass 文件的 sass-loader 的选项。

less

configureWebpack

  • 类型: Object | Function
  • 默认值: undefined用于修改内部的 Webpack 配置。如果给定一个对象,那么它将会被 webpack-merge 合并到最终的配置中,如果给定一个函数,它将会接受 config 作为第一个参数,以及 isServer 作为第二个参数,你可以直接更改 config,也可以返回一个待合并的对象。
  1. module.exports = {
  2. configureWebpack: (config, isServer) => {
  3. if (!isServer) {
  4. // 修改客户端的 webpack 配置
  5. }
  6. }
  7. }

chainWebpack

  • 类型: Function
  • 默认值: undefined通过 webpack-chain 来修改内部的 Webpack 配置。
  1. module.exports = {
  2. chainWebpack: (config, isServer) => {
  3. // config 是 ChainableConfig 的一个实例
  4. }
  5. }

浏览器兼容性

evergreen

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