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

转载请标明出处: https://www.jianshu.com/p/307684deff51

本文出自 AWeiLoveAndroid的博客


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

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


一、工具

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


二、全局安装VuePress

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

下载路径分别在C:\Users\Administrator\AppData\Roaming\npm\vuepressC:\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.htmltemplates/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特有的设置

<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"/>

(一)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是网站描述。如果某个语言对象没有声明 titledescription,VuePress 会尝试获取根语言对象上相应的值。如果每个语言对象都声明了 titledescription,则可以省略根语言对象上的 titledescription

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.mdYAML 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 注意事项: 内置搜索只会为页面的标题、h2h3 构建搜索索引,如果你需要全文搜索,你可以使用 Algolia 搜索。 :::

b.Algolia搜索

通过 themeConfig.algolia 选项来用 Algolia 搜索 替换内置的搜索框。要启用 Algolia 搜索,你需要至少提供 apiKeyindexName,如下所示:

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/

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

扫码关注云+社区

领取腾讯云代金券