前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >开发工具总结(15)之Vuepress制作文档并发布到GitHub

开发工具总结(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的使用。


一、工具

VuePress支持使用Yarnnpm来安装,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文件需要手动格式化一下,我这里全部写在了一行,没有做换行和空格处理。

代码语言:javascript
复制
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

代码语言:javascript
复制
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命令编译项目:

代码语言:javascript
复制
vuepress dev

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

代码语言:javascript
复制
vuepress build

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

编译项目:

代码语言:javascript
复制
npm run docs:build 或者 yarn docs:build

运行项目:

代码语言:javascript
复制
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,那下面这些效果就不在话下了:

使用示例:

代码语言:javascript
复制
* 页内跳转

<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 风格的表格

使用示例:

代码语言:javascript
复制
| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

使用效果如下图所示:

GitHub 风格的表格示例

(四)Emoji

使用示例:

代码语言:javascript
复制
:tada: :100::fire:

使用效果如下图所示:

使用Emoji示例

(五)自定义容器

使用示例:

代码语言:javascript
复制
::: 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节点,如下:
代码语言:javascript
复制
  // 对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配置每个依赖库,免得出错。
代码语言:javascript
复制
    "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语法即可。

代码语言:javascript
复制
<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的版本号。

代码语言:javascript
复制
{
    "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) 普通配置

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

代码语言:javascript
复制
title: "LZW的博客",

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

代码语言:javascript
复制
description: "LZW的个人网站",

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

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

代码语言:javascript
复制
base: "/vuepress_usage/",

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

代码语言:javascript
复制
head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }]
],

设置主机名,默认0.0.0.0:

代码语言:javascript
复制
// host:"", 

设置端口号,默认8080:

代码语言:javascript
复制
// post:"",

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

代码语言:javascript
复制
dest: "public",
(1) 国际化
  • 1.要做国际化(多语言),需要以下文件结构:
代码语言:javascript
复制
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

代码语言:javascript
复制
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 的后面。

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

代码语言:javascript
复制
---
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 标签。

代码语言:javascript
复制
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表示开启

完整示例如下:

代码语言:javascript
复制
---
"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 增加一些导航栏链接。示例如下:
代码语言:javascript
复制
module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'GitHub', link: 'https://github.com' },
    ]
  }
}

如图所示:

nav添加链接

  • 当你提供了一个 items 数组而不是一个单一的 link 时,它将显示为一个下拉列表,如下所示:
代码语言:javascript
复制
module.exports = {
  themeConfig: {
    nav: [
      {
        text: '编程语言',
        items: [
          { text: 'Java', link: '/' },
          { text: 'HTML', link: '/' }
        ]
      }
    ]
  }
}

如图所示:

nav下拉列表

  • 你还可以通过嵌套的 items 来在 下拉列表 中设置分组,如下所示:
代码语言:javascript
复制
module.exports = {
  themeConfig: {
    nav: [
      {
        text: '程序员',
        items: [
          { text: '移动端', items: [{ text: 'Android', link: '/' },
          { text: 'iOS', link: '/' }] },
          { text: '服务端', items: [{ text: 'Java', link: '/' },
          { text: 'PHP', link: '/' }] }
        ]
      }
    ]
  }
}

如图所示:

nav分组

b.禁用导航栏
代码语言:javascript
复制
module.exports = {
  themeConfig: {
    navbar: false
  }
}

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

4.侧边栏
a.标题链接
  • 1.需要配置 themeConfig.sidebar即可让侧边栏生效。基本的配置,需要包含了多个链接的数组,如下所示:
代码语言:javascript
复制
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 来显示所有页面的标题链接:

代码语言:javascript
复制
module.exports = {
  themeConfig: {
    displayAllHeaders: true // 默认值:false
  }
}
  • 4.活动的标题链接

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

代码语言:javascript
复制
module.exports = {
  themeConfig: {
    activeHeaderLinks: false, // 默认值:true
  }
}
b.侧边栏分组
  • 你可以通过使用对象,也就是大括号{}来将侧边栏划分成多个组:
代码语言:javascript
复制
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. 所有页面启用自动生成侧边栏:
代码语言:javascript
复制
module.exports = {
  themeConfig: {
    sidebar: 'auto'
  }
}
    1. 如果设置了多语言模式,可以指定特定语言启动自动生成侧边栏:
代码语言:javascript
复制
module.exports = {
  themeConfig: {
     '/zh/': {
       sidebar: 'auto'
     }
  }
}
    1. 可以通过 YAML front matter 来自动生成侧边栏。
d.关于禁用侧边栏

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

代码语言:javascript
复制
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.默认主题的国际化
代码语言:javascript
复制
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 实例的默认配置,或者应用额外的插件的函数,

举例如下:

代码语言:javascript
复制
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 来调整默认搜索框显示的搜索结果数量,如下所示:

代码语言:javascript
复制
module.exports = {
  themeConfig: {
    search: false,
    searchMaxSuggestions: 10
  }
}

::: tip 注意事项:

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

:::

b.Algolia搜索

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

代码语言:javascript
复制
module.exports = {
  themeConfig: {
    algolia: {
      apiKey: '<API_KEY>',
      indexName: '<INDEX_NAME>'
    }
  }
}
(6) 最后更新时间

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

代码语言:javascript
复制
module.exports = {
  themeConfig: {
    lastUpdated: 'Last Updated', // string | boolean
  }
}

注意:

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

(7) 上 / 下一篇链接

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

(8) Git 仓库和编辑链接

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

代码语言:javascript
复制
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。如下所示:
代码语言:javascript
复制
module.exports = {
     serviceWorker: true,
}
  • 然后添加icons和Manifest配置,在public中添加manifest.json配置和图标。可以点击PWA配置查看相关资料。
  • 最后在config.js 配置中添加·manifest.json·:
代码语言:javascript
复制
module.exports = {
    head: [
      ['link', { rel: 'manifest', href: '/manifest.json' }],
    ]
}

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

(三)manifest.json配置

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

代码语言:javascript
复制
{
    "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 脚本文件,如下所示:

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

代码语言:javascript
复制
#!/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 删除

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

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

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

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 一、工具
  • 二、全局安装VuePress
  • 三、初始化项目
  • 四、构建和编译
  • 五、VuePress中的MarkDown特有的设置
    • (一)TOC
      • (二)直接支持html,css
        • (三)GitHub 风格的表格
          • (四)Emoji
            • (五)自定义容器
              • (六)代码中的行高亮 语言后面使用{数字} 例如js{4} 表示第四行高亮
                • (七)导入代码段(这个有点不好懂 不管它)
                  • (八)公式的支持,需要导入css
                  • 六、配置详解
                    • (一)package.json配置
                      • (二)config.js配置
                        • (1) 普通配置
                        • (1) 国际化
                        • (3) 默认主题配置
                        • (4) markdown配置
                        • (5) 搜索框
                        • (6) 最后更新时间
                        • (7) 上 / 下一篇链接
                        • (8) Git 仓库和编辑链接
                        • (9) PWA支持
                      • (三)manifest.json配置
                      • 七、部署
                        • (一)在config.js里面设置正确的路径。
                          • (二)在项目根路径,创建一个deploy.sh 脚本文件,如下所示:
                          • 八、遇到的一些错误
                          相关产品与服务
                          容器服务
                          腾讯云容器服务(Tencent Kubernetes Engine, TKE)基于原生 kubernetes 提供以容器为核心的、高度可扩展的高性能容器管理服务,覆盖 Serverless、边缘计算、分布式云等多种业务部署场景,业内首创单个集群兼容多种计算节点的容器资源管理模式。同时产品作为云原生 Finops 领先布道者,主导开源项目Crane,全面助力客户实现资源优化、成本控制。
                          领券
                          问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档