开发工具总结（15）之Vuepress制作文档并发布到GitHub

AWeiLoveAndroid

发布于 2019-07-08 00:43:51

3.9K0

发布于 2019-07-08 00:43:51

文章被收录于专栏：Flutter入门到实战

转载请标明出处：

https://cloud.tencent.com/developer/article/1458494

本文出自 AWeiLoveAndroid的博客

在线文档制作工具系列篇 ↓：

前面讲解了Gitbook，Hexo, Jekyll三种方式制作文档，今天讲一下Vuepress制作文档。Vuepress自带一个彩色的主题风格，很漂亮，相对于前面几个来说，可操作性比较方便，上手快，格式众多，适合小白学习和使用。下面具体讲一下Vuepress的使用。

本文示例代码：https://github.com/AweiLoveAndroid/AweiLoveAndroid.github.io
本文演示效果可以查看：https://aweiloveandroid.github.io/vuepress_usage/

一、工具

VuePress支持使用Yarn和npm来安装，Node.js版本需要>=8才可以。使用yarn更快。建议使用yarn。

二、全局安装VuePress

使用命令 npm install -g vuepress或者yarn global add vuepress 都行，感觉 yarn比较快。

下载路径分别在C:\Users\Administrator\AppData\Roaming\npm\vuepress和

C:\Users\Administrator\AppData\Local\Yarn\bin\vuepress。

使用npm下载vuepress

图片上传失败...(image-c2e686-1562312383507)

使用yarn下载vuepress

图片上传失败...(image-20f773-1562312383507)

查看版本号：vuepress --version 我的版本号是0.14.8

三、初始化项目

操作步骤：

1.新建项目文件夹：mkdir hello_vuepress ，然后进入文件夹：cd hello_vuepress 2.还有好多文件需要创建，由于每次创建项目都要手动创建这么多文件，很麻烦的。为了方便，我写了一个脚本，把常用的文件都创建了。你可以把脚本取名叫做：test.bat，格式为.bat，然后把脚本放到刚创建的文件hello_vuepress里面。

脚本内容如下：这里的js文件和json文件需要手动格式化一下，我这里全部写在了一行，没有做换行和空格处理。

test.bat------
set curdir=%~dp0
cd /d %curdir%
@echo off
echo >>package.json
set var="ECHO is off."
findstr /v %var% "package.json"
echo {"name": "替换成你的工程名字","version": "1.0.0","main": "index.js","license": "MIT","scripts": {"docs:dev": "vuepress dev docs","docs:build": "vuepress build docs"},"dependencies": {"vuepress": "^0.14.8"}} > package.json
md docs
md docs\.vuepress
echo >>docs\.vuepress\config.js
echo module.exports = {title: '个人文档',description: '练习文档'} > docs\.vuepress\config.js
md docs\.vuepress\public
echo >>docs\README.md
echo # 第一个VuePress页面 > docs\README.md
md docs\guide
echo >>docs\guide\README.md
echo # 这是导航文件 > docs\guide\README.md
echo >>docs\config.md
echo # 这是config文件 > docs\config.md
pause

下面这个是按照VuePress官网推荐的完整的目录写的一个脚本，如果有需要的话，可以执行下面这个脚本创建。例如，我把这个脚本取名叫做test-all.bat。

test-all.bat------
set curdir=%~dp0
cd /d %curdir%
@echo off
echo >>package.json
set var="ECHO is off."
findstr /v %var% "package.json"
echo {"name": "替换成你的工程名字","version": "1.0.0","main": "index.js","license": "MIT","scripts": {"docs:dev": "vuepress dev docs","docs:build": "vuepress build docs"},"dependencies": {"vuepress": "^0.14.8"}} > package.json
md docs
md docs\.vuepress
md docs\.vuepress\components
md docs\.vuepress\theme
echo >>docs\.vuepress\theme\Layout.vue
md docs\.vuepress\public
md docs\.vuepress\styles
echo >>docs\.vuepress\styles\index.styl
echo >>docs\.vuepress\styles\palette.styl
md docs\.vuepress\templates
echo >>docs\.vuepress\templates\dev.html
echo >>docs\.vuepress\templates\ssr.html
echo >>docs\.vuepress\config.js
echo module.exports = {title: '个人文档',description: '练习文档'} > docs\.vuepress\config.js
echo >>docs\.vuepress\enhanceApp.js
echo >>docs\README.md
echo # 第一个VuePress页面 > docs\README.md
md docs\guide
echo >>docs\guide\README.md
echo # 这是导航文件 > docs\guide\README.md
echo >>docs\config.md
echo # 这是config文件 > docs\config.md
pause

官方推荐的完整路径如下图所示：

vuepress官网推荐完整目录

各个文件目录的含义：

doc目录下各文件夹或文件名称	含义
.vuepress	用于存放全局的配置、组件、静态资源等。
.vuepress/components	该目录中的 Vue 组件将会被自动注册为全局组件。
.vuepress/theme	用于存放本地主题。
.vuepress/styles	用于存放样式相关的文件。
.vuepress/styles/index.styl	将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级。
.vuepress/styles/palette.styl	用于重写默认颜色常量，或者设置新的 stylus 颜色常量。
.vuepress/public	静态资源目录。
.vuepress/templates	存储 HTML 模板文件。
.vuepress/templates/dev.html	用于开发环境的 HTML 模板文件。
.vuepress/templates/ssr.html	构建时基于 Vue SSR 的 HTML 模板文件。
.vuepress/config.js	配置文件的入口文件，也可以是 YML 或 toml。
.vuepress/enhanceApp.js	客户端应用的增强。

注意：当你想要去自定义 templates/ssr.html 或 templates/dev.html 时，最好基于默认的模板文件来修改，否则可能会导致构建出错。

3.然后使用命令yarn init -y，进行初始化操作。这时候会创建一个package.json文件，用于配置。

注意：由于上一步的脚本里面已经创建了这个文件，所以就没必要执行这一步了。这里列举这个命令，针对那些手动创建文件的人来说的。）

命令使用如图所示：

初始化

四、构建和编译

使用vuepress命令编译项目：

vuepress dev

使用vuepress命令构建静态文件：

vuepress build

由于上面的package.json里面配置了自定义打包命令，所以就用那个就好了，修改后的命令如下：

编译项目：

npm run docs:build 或者 yarn docs:build

运行项目：

npm run docs:dev 或者 yarn docs:build

下图是使用npm run docs:build命令的示例：

编译项目

下面是使用npm run docs:dev的示范，然后可以打开浏览器http://localhost:8080/查看效果了。它会运行docs目录里面的READ.md`的内容。关于每一部分怎么来的，后面讲配置的时候详细说明。

效果如下图所示：

首个页面

五、VuePress中的MarkDown特有的设置

（一）TOC

看内容目录就是用[[toc]]生成的

注：只要放置:[[TOC]],就能把其后面的标题如：#,##,...######自动生成目录树，注意，[[TOC]]要独立一行，并前面和后面都要空一行

示例如下图所示：

TOC目录的使用

（二）直接支持html,css

如果你懂html和css，那下面这些效果就不在话下了：

使用示例：

* 页内跳转

<a href="#jump_test">来个页内跳转</a>，跳转到文未的：`<a id="jump_test">我是页内跳转到的位置</a>` ,对应：`id="jump_test"`

* 颜色 #5bdaed

<span  style="color: #5bdaed; ">先给点颜色你看看</span>

* 颜色 #AE87FA

<span  style="color: #AE87FA; ">再给点颜色你看看</span> 

* 字体大小 1.3em

<span  style="font-size:1.3em;">试试改变字体大小</span>

* 字体大小 1.3em  bold加粗

<span  style="font-size:1.3em;font-weight: bold;">改变字体大小，再来个粗体又如何？</span>

* 内容居中：

<p style="text-align:center">
试试内容居中
</p>

* 内容居右：

<p style="text-align:right">
那内容居右呢？
</p>

* 综合示例：

<p style="text-align:center;color:#1e819e;font-size:1.3em;font-weight: bold;">
来个综合的试试
<br/>
第二行
</p>
----

<a id="jump_test">我是页内跳转到的位置</a>

<a id="jump_1">我是页内跳转到的位置</a>
[^10]: 注脚跳转位置
111

使用截图如下所示：

支持html和css

（三）GitHub 风格的表格

使用示例：

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

使用效果如下图所示：

GitHub 风格的表格示例

（四）Emoji

使用示例：

:tada: :100::fire:

使用效果如下图所示：

使用Emoji示例

（五）自定义容器

使用示例：

::: tip 提示
This is a tip
:::

::: warning 警告
This is a warning
:::

::: danger 危险
This is a dangerous warning
:::

使用效果如下图所示：

自定义容器示例

（六）代码中的行高亮语言后面使用{数字} 例如js{4} 表示第四行高亮

效果示意图

（七）导入代码段（这个有点不好懂不管它）

...略

（八）公式的支持，需要导入css

1.使用命令yarn global add markdown-it全局安装markdown-it，
2.使用命令yarn global add markdown-it-katex全局安装markdown-it-katex，
3.使用命令yarn global add markdown-it-katex-external全局安装markdown-it-katex-external，
4.然后在config.js中设置markdown节点，如下：

  // 对markdown的配置
  markdown: {
    // 显示行号
    lineNumbers: true,
    // markdown-it-anchor 的选项
    anchor: { permalink: false },
    // markdown-it-toc 的选项
    toc: { includeLevel: [1, 2, 3, 4] },
    config: md => {
       // 使用更多 markdown-it-katex 插件！
       md.use(require("markdown-it-katex"));
    }
  }

5.然后在package.json配置每个依赖库，免得出错。

    "dependencies": {
        "markdown-it": "^8.4.2",
        "markdown-it-anchor": "^5.0.2",
        "markdown-it-container": "^2.0.0",
        "markdown-it-emoji": "^1.4.0",
        "markdown-it-katex": "^2.0.3",
        "markdown-it-katex-external": "^1.0.0",
        "markdown-it-table-of-contents": "^0.4.3",
        "vuepress": "^0.14.8"
    }

如果报错某个module找不到，就下载对应的就行了，例如：

报错：Cound not found module markdown-it-container，以下就是一个错误示意图：

module错误

解决：使用yarn global add markdown-it-container进行下载即可。

6.在markdown中的使用：

在markdown文件开头加入以下两个css链接，然后再去写katex语法即可。

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.5.1/katex.min.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/github-markdown-css/2.2.1/github-markdown.css"/>

下例是公式的使用：

公式的使用

7.最后通过编译命令npm run docs:dev，浏览器输入localhost:8080，回车就可以看到结果了。

六、配置详解

（一）package.json配置

路径为：hello_vuepress/package.json

开始的4行是运行yarn init -y自动生成的，这里的scripts节点里面配置两个启动命令。dependencies节点配置vuepress的版本号。

{
    "name": "hello_vuepress", // 项目名 
    "version": "1.0.0", // 版本号
    "main": "index.js", // 主要处理函数所在的js文件名
    "license": "MIT", // 协议名称
    "scripts":{ // 配置编译运行命令
        "docs:dev": "vuepress dev docs",
        "docs:build": "vuepress build docs"
    },
    "dependencies": {  // 配置vuepress版本号
        "vuepress": "^0.14.8"
    }
}

配置之后就用npm run docs:dev运行，编译成静态文件用命令npm run docs:build，编译之后的静态文件在docs\.vuepress\dist\目录，可以在本地使用，也可以部署到github或者服务器。

（二）config.js配置

路径为：hello_vuepress/docs/.vuepress/config.js

（1）普通配置

设置网站标题，并显示在默认主题的导航栏中。

title: "LZW的博客",

设置网站描述。相当于 HTML 中的<meta> 标签。

description: "LZW的个人网站",

要部署到的网站基础路径：（例如发布到http://aweiloveandroid.github.io/vuepress_usage

，仓库地址为:https://github.com/AweiLoveAndroid/AweiLoveAndroid.github.io/vuepress_usage，那么这里的base就填写/vuepress_usage/，注意前后各带有一个”/“）

base: "/vuepress_usage/",

额外的需要被注入到当前页面的 HTML <head> 中的标签时，配置head项，这里是自定义的favicon：

head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }]
],

设置主机名，默认0.0.0.0：

// host:"",

设置端口号，默认8080：

// post:"",

指定vuepress build的输出目录,默认值: .vuepress/dist，这里设置成public目录。

dest: "public",

（1）国际化

1.要做国际化（多语言），需要以下文件结构：

docs
  ├─ README.md
  ├─ page1.md
  ├─ charaters
  │    └─ README.md
  ├─ zh
  │   ├─ README.md
  │   ├─ page1.md
  │   └─ charaters
  │        └─ README.md
  └─ 
      ├─ README.md
      ├─ page1.md
      └─ charaters
           └─ README.md

2.列举几个lang属性值：

语言	ISO代码
英文	en
美式英文	en-us
中文（旧标准）	zh-CN
简体中文（新标准）	zh-cmn-Hans
繁体中文（新标准）	zh-cmn-Hant

3.在.vuepress/config.js 中指定 locales 选项：

每个语言对象的键(key)，是语言的访问路径。然而，一种特例是将 '/' 作为默认语言的访问路径。

设置lang这个值会被设置在 <html> 的 lang 属性上，用于设置语言。

设置title是标题，description是网站描述。如果某个语言对象没有声明 title 或 description，VuePress 会尝试获取根语言对象上相应的值。如果每个语言对象都声明了 title 和 description，则可以省略根语言对象上的 title 和 description。

module.exports = {
  locales: {
    "/": {
      lang: "en-US",
      title: "LZW’s blog",
      description: "websie of LZW"
    },
    "/zh/": {
      lang: "zh-CN",
      title: "LZW的首个博客",
      description: "LZW的首个个人网站"
    }
  }
},

（3）默认主题配置

1.首页

默认的主题提供了一个首页（Homepage）的布局。想要使用它，需要在你的根级 README.md 的 YAML front matter 指定 home: true。任何 YAML front matter 之后额外的内容将会以普通的 markdown 被渲染，并插入到 features 的后面。

以下是一个如何使用的例子：

---
home: true
heroImage: /favicon.png
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---

2.其它页面的`Front Matter`配置

在正文前面声明title，或者其它属性值。以下是VuePress自带的一些配置选项，可以自由选择使用：

选项	写法示例	作用
title	"title": "page1"	当前页面的标题。
lang	"lang": "en-US"	当前页面的语言。
description	"description": "当前页面的描述"	当前页面的描述。
layout	"layout": "xxx.vue"	设置当前页面的布局组件。
metaTitle	"metaTitle": "重写默认的 meta title"	重写默认的 meta title。
permalink	"permalink": "/:year/:month/:day/:slug"	设置页面的永久链接。

permalink的模板变量包括：

变量	介绍
:year	文章发布的年份 (4数字)
:month	文章发布的月份 (2数字)
:i_month	文章发布的月份 (前面不带0)
:day	文章发布的日份 (2数字)
:i_day	文章发布的日份 (前面不带0)
:slug	蛞蝓化文件路径 (不带扩展名)
:regular	VuePress默认的生成永久链接的方式，具体实现看

meta：指定额外的要注入的 meta 标签。

meta:
  - name: description
    content: hello
  - name: keywords
    content: super duper SEO

导航栏和侧边栏有关的Front Matter设置：

选项	写法示例	作用
navbar	navbar: false	false表示：禁用页面的导航栏
sidebarDepth	sidebarDepth: 2	设置侧边栏的嵌套的标题链接最大深度
sidebar	sidebar: auto	自动生成侧边栏
sidebar	sidebar: false	禁用侧边栏

设置上 / 下一篇链接：

选项	写法示例	作用
prev	prev: ./some-other-page	设置上一篇链接
next	next: false	设置下一篇链接

设置是否指定页面的编辑链接：

选项	写法示例	作用
editLink	editLink: false	false为禁用，true表示开启

完整示例如下：

---
"title": "page1"
"lang": "en-US"
"description": "当前页面的描述"
"layout": "xxx.vue"
"permalink": "/:year/:month/:day/:slug"
meta:
  - name: description
    content: hello
  - name: keywords
    content: super duper SEO
---

3.导航栏

a.导航栏链接

通过themeConfig.nav 增加一些导航栏链接。示例如下：

module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'GitHub', link: 'https://github.com' },
    ]
  }
}

如图所示：

nav添加链接

当你提供了一个 items 数组而不是一个单一的 link 时，它将显示为一个下拉列表，如下所示：

module.exports = {
  themeConfig: {
    nav: [
      {
        text: '编程语言',
        items: [
          { text: 'Java', link: '/' },
          { text: 'HTML', link: '/' }
        ]
      }
    ]
  }
}

如图所示：

nav下拉列表

你还可以通过嵌套的 items 来在 下拉列表 中设置分组，如下所示：

module.exports = {
  themeConfig: {
    nav: [
      {
        text: '程序员',
        items: [
          { text: '移动端', items: [{ text: 'Android', link: '/' },
          { text: 'iOS', link: '/' }] },
          { text: '服务端', items: [{ text: 'Java', link: '/' },
          { text: 'PHP', link: '/' }] }
        ]
      }
    ]
  }
}

如图所示：

nav分组

b.禁用导航栏

module.exports = {
  themeConfig: {
    navbar: false
  }
}

你也可以通过上文提到的 YAML front matter 来禁用导航栏。

4.侧边栏

a.标题链接

1.需要配置 themeConfig.sidebar即可让侧边栏生效。基本的配置，需要包含了多个链接的数组，如下所示：

module.exports = {
  themeConfig: {
    sidebar: [
      'config',
      ['/guide/', '标题2']
    ],
  }
}

书写规则：

省略·.md扩展名，以/结尾的相当于*/README.md，如果未显示地指定链接的文字，会自动引用md文件的H1标记后面的文字作为标题，或者md里面指定页面的标题。如果显示地指定链接的文字。比如上例中的/guild/这个路由，它的标题是标题2,侧边栏切换到这个页面时，显示的就是标题2`。

示例图如下所示：

侧边栏标题优先级

1. 可以通过上文提到的 YAML front matter 来设置侧边栏的嵌套的标题链接最大深度。
3.显示所有页面的标题链接

默认情况下，侧边栏只会显示由当前活动页面的标题（headers）组成的链接，你可以将 themeConfig.displayAllHeaders 设置为 true 来显示所有页面的标题链接：

module.exports = {
  themeConfig: {
    displayAllHeaders: true // 默认值：false
  }
}

4.活动的标题链接

默认情况下，当用户通过滚动查看页面的不同部分时，嵌套的标题链接和 URL 中的 Hash 值会实时更新，这个行为可以通过以下的配置来禁用：（一般用默认的就可以，不做修改。）

module.exports = {
  themeConfig: {
    activeHeaderLinks: false, // 默认值：true
  }
}

b.侧边栏分组

你可以通过使用对象，也就是大括号{}来将侧边栏划分成多个组：

module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: "web",
        children: ["/web/", "/web/one", "/web/two"]
      },
      {
        title: "php",
        children: ["/php/", "/php/three", "/php/four"]
      },
      {
        title: "life",
        children: ["/life/", "/life/life1", "/life/life2"]
      }
    ],
  }
}

注意：

1.侧边栏标题最多只能显示三级标题，其它的不显示。

例如你设置了#、##、###都可以显示，但是####、#####、######都不能显示。

2.如果超过了三层，滑动页面时，侧边栏的标题指示不会跟随移动。

c.自动生成侧边栏

1. 所有页面启用自动生成侧边栏：

module.exports = {
  themeConfig: {
    sidebar: 'auto'
  }
}

1. 如果设置了多语言模式，可以指定特定语言启动自动生成侧边栏：

module.exports = {
  themeConfig: {
     '/zh/': {
       sidebar: 'auto'
     }
  }
}

1. 可以通过 YAML front matter 来自动生成侧边栏。

d.关于禁用侧边栏

可以通过 YAML front matter 来禁用指定页面的侧边栏。

module.exports = {
  //////////  主题信息 ///////////
  themeConfig: {
    //git 仓库地址
    repo: "https://github.ioAWeiLoveAndroid/MyDocs",
    // 是否编辑链接
    editLinks: true,
    // 编辑链接文字
    editLinkText: "在 GitHub 上编辑此页",

    // 导航栏
    nav: [
      { text: "首页", link: "/nav/" },
      { text: "关于", link: "/nav/about" },
      { text: "联系", link: "/nav/contact" },
      {
        text: "更多",
        items: [
          { text: "博客", link: "https://github.com/AweiLoveAndroid" },
          { text: "简书", link: "https://www.jianshu.com/u/f408bdadacce" }
        ]
      }
    ],

    // 侧边栏
    sidebar: [
      {
        title: "foo",
        collapsable: false,
        children: ["/foo/", "/foo/one", "/foo/two"]
      },
      {
        title: "bar",
        collapsable: false,
        children: ["/bar/", "/bar/three", "/bar/four"]
      }
    ],

    // 嵌套的标题链接深度，默认的深度为1。
    // sidebarDepth: 2

    //搜索
    search: true,
    searchMaxSuggestions: 10,
    lastUpdated: "Last Updated" // string | boolean
  },

  //////////  PWA配置 ///////////
  serviceWorker: true
};

5.默认主题的国际化

module.exports = {
  themeConfig: {
    locales: {
      '/': {
        // text for the language dropdown
        selectText: 'Languages',
        // label for this locale in the language dropdown
        label: 'English',
        // text for the edit-on-github link
        editLinkText: 'Edit this page on GitHub',
        // config for Service Worker 
        serviceWorker: {
          updatePopup: {
            message: "New content is available.",
            buttonText: "Refresh"
          }
        },
        // algolia docsearch options for current locale
        algolia: {},
        nav: [
          { text: 'Nested', link: '/nested/' }
        ],
        sidebar: {
          '/': [/* ... */],
          '/nested/': [/* ... */]
        }
      },
      '/zh/': {
        // 语言下拉菜单的展示文本
        selectText: '选择语言',
        // 该语言在下拉菜单中的 label 标签
        label: '简体中文',
        // github 编辑链接的文字
        editLinkText: '在 GitHub 上编辑此页',
        serviceWorker: {
          updatePopup: {
            message: "发现新内容可用.",
            buttonText: "刷新"
          }
        },
        nav: [
          { text: '嵌套', link: '/zh/nested/' }
        ],
        algolia: {},
        sidebar: {
          '/zh/': [/* ... */],
          '/zh/nested/': [/* ... */]
        }
      }
    }
  }
}

（4） markdown配置

在 themeConfig节点里面设置markdown相关信息。

选项	写法示例	作用
lineNumbers	lineNumbers: true,	是否在每个代码块的左侧显示行号,true为显示
anchor	默认值：{ permalink: true, permalinkBefore: true, permalinkSymbol: '#' }	markdown-it-anchor 的选项。
toc	默认值: { includeLevel: 2, 3 }	markdown-it-table-of-contents 的选项。
扩展项	示例代码：config: md => {md.set({ breaks: true }) md.use(require('markdown-it-xxx'))}	用于修改当前的 markdown-it 实例的默认配置，或者应用额外的插件的函数，

举例如下：

module.exports = {
  markdown: {
    // 显示行号
    lineNumbers: true, 
    anchor: {
      // 标题头有一个¶图标
      permalink: true,
      level: 1,
      // permalinkSymbol: '&#187;'
      permalinkSymbol: '&#x00BB;'
    },
    toc: {
      // 包含的层级
      includeLevel: [1, 2, 3],
      // true表示在TOC中呈现所有标题
      forceFullToc: true
    }
    config: md => {
      md.set({ breaks: true })
      md.use(require('markdown-it-xxx'))
    }
  }
}

（5）搜索框

a.内置搜索

通过设置 themeConfig.search: false 来禁用默认的搜索框，或是通过 themeConfig.searchMaxSuggestions 来调整默认搜索框显示的搜索结果数量,如下所示：

module.exports = {
  themeConfig: {
    search: false,
    searchMaxSuggestions: 10
  }
}

::: tip 注意事项：

内置搜索只会为页面的标题、h2 和 h3 构建搜索索引，如果你需要全文搜索，你可以使用 Algolia 搜索。

:::

b.Algolia搜索

通过 themeConfig.algolia 选项来用 Algolia 搜索替换内置的搜索框。要启用 Algolia 搜索，你需要至少提供 apiKey 和 indexName，如下所示：

module.exports = {
  themeConfig: {
    algolia: {
      apiKey: '<API_KEY>',
      indexName: '<INDEX_NAME>'
    }
  }
}

（6）最后更新时间

通过 themeConfig.lastUpdated 选项来获取每个文件最后一次 git 提交的 UNIX 时间戳(ms)，同时它将以合适的日期格式显示在每一页的底部。themeConfig.lastUpdated 默认是关闭的，如果给定一个字符串，它将会作为前缀显示（默认值是：Last Updated）。具体配置如下：

module.exports = {
  themeConfig: {
    lastUpdated: 'Last Updated', // string | boolean
  }
}

注意：

由于 lastUpdated 是基于 git 的, 所以你只能在一个基于 git 的项目中启用它。

（7）上 / 下一篇链接

可以通过 YAML front matter 来设置上 / 下一篇链接。

（8） Git 仓库和编辑链接

当你提供了 themeConfig.repo 选项，将会自动在每个页面的导航栏生成生成一个 GitHub 链接，以及在页面的底部生成一个 "Edit this page" 链接。

module.exports = {
  themeConfig: {
    // 假定是 GitHub. 同时也可以是一个完整的 GitLab URL
    repo: "https://github.com/AweiLoveAndroid/AweiLoveAndroid.github.io/tree/master/vuepress_usage",
    // 自定义仓库链接文字。默认从 `themeConfig.repo` 中自动推断为
    // "GitHub"/"GitLab"/"Bitbucket" 其中之一，或是 "Source"。
    repoLabel: '查看源码',

    // 以下为可选的编辑链接选项

    // 假如你的文档仓库和项目本身不在一个仓库：
    docsRepo: 'vuejs/vuepress',
    // 假如文档不是放在仓库的根目录下：
    docsDir: 'docs',
    // 假如文档放在一个特定的分支下：
    docsBranch: 'master',
    // 默认是 false, 设置为 true 来启用
    editLinks: true,
    // 默认为 "Edit this page"
    editLinkText: '帮助我们改善此页面！'
  }
}

（9） PWA支持

VuePress默认支持PWA配置，需要在themeConfig中开启serviceWorker。如下所示：

module.exports = {
     serviceWorker: true,
}

然后添加icons和Manifest配置，在public中添加manifest.json配置和图标。可以点击PWA配置查看相关资料。
最后在config.js 配置中添加·manifest.json·:

module.exports = {
    head: [
      ['link', { rel: 'manifest', href: '/manifest.json' }],
    ]
}

可以通过 YAML front matter 来设置是否指定页面的编辑链接。

（三）manifest.json配置

路径为：hello_vuepress/docs/.vuepress/public/manifest.json

{
    "name": "lzw",
    "short_name": "lzw",
    "start_url": "index.html",
    "display": "standalone",
    "background_color": "#2196f3",
    "description": "阿韦的博客",
    "theme_color": "blue",
    "icons": [
      {
        "src": "./favicon.png",
        "sizes": "144x144",
        "type": "image/png"
      }
    ],
    // 配置PWA  用不到PWA的可以不用管它
    // "related_applications": [
    //   {
    //     "platform": "web"
    //   },
    //   {
    //     "platform": "play",
    //     "url": "https://play.google.com/store/apps/details?id=cheeaun.hackerweb"
    //   }
    // ]
  }

七、部署

（一）在config.js里面设置正确的路径。

base: “/vuepress_usage/", 这里的base就是我们要部署的路径，它的默认值是/。如果发布到 https://用户名.github.io/，则可以省略这一步。如果发布到https://用户名.github.io/二级路径，则将base设置成二级路径。例如：

发布到http://aweiloveandroid.github.io/vuepress_usage这个路径，我只要填写/vuepress_usage/即可。

注意：前后都要带上**/**，不然会报错。

（二）在项目根路径，创建一个`deploy.sh` 脚本文件，如下所示：

请根据你想要提交的网址进行修改。

#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -

八、遇到的一些错误

1.无法使用touch命令

解决：使用命令行npm install touch-cli -g就可以了。

2.官网说的slidebar多个侧边栏，我怎么都配置不好，可能是一个坑吧。

本文参考：https://vuepress.vuejs.org/zh/guide/

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2019.07.05 ，如有侵权请联系 cloudcommunity@tencent.com 删除

markdown

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！