# vuepress快速上手
# 生成简单的文档网站
mkdir 文件名cd 文件名npm init，示例如下：
// package.json
{
"name": "chrome_plugins_doc",
"version": "1.0.0",
"description": "This is the instruction document of chrome plugins",
"main": "index.js",
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
},
"keywords": [
"chrome",
"plugins",
"instruction"
],
"author": "Karl_fang",
"license": "ISC",
"devDependencies": {
"vuepress": "^1.9.7"
}
}
npm install -g vuepress，mac用sudo npm install -g vuepress
自己的mac电脑使用(sudo) npm install -g vuepress一直报错就报错了，报错信息如下：
Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/vuepress/node_modules/@vuepress/core/.temp'
at Object.mkdirSync (node:fs:1334:3)
at Object.mkdirsSync (/usr/local/lib/node_modules/vuepress/node_modules/fs-extra/lib/mkdirs/mkdirs-sync.js:31:9)
at createTemp (/usr/local/lib/node_modules/vuepress/node_modules/@vuepress/core/lib/node/createTemp.js:31:8)
at App.resolveConfigAndInitialize (/usr/local/lib/node_modules/vuepress/node_modules/@vuepress/core/lib/node/App.js:79:37)
at processTicksAndRejections (node:internal/process/task_queues:96:5)
at async App.process (/usr/local/lib/node_modules/vuepress/node_modules/@vuepress/core/lib/node/App.js:103:5)
at async dev (/usr/local/lib/node_modules/vuepress/node_modules/@vuepress/core/lib/index.js:17:3)
然后用npm install -D vuepress就可以了，也不知道为啥
- 创建
docs文件夹 - 在
docs文件下创建.vuepress文件夹，并在此文件夹里创建config.js文件
目录结构如下所示：
vuepress-demo
├── package.json
├── package-lock.json
├── node_modules
└── docs
├── .vuepress
│ └── config.js # 配置
├── README.md # 首页文件
- 配置
config.js文件，如下：
module.exports = {
title: 'Chrome插件文档说明',
description: '我的的文档',
}
- 执行
npm run dev后就能得到一个简单的网页，成功后终端会显示如下：
success [09:57:25] Build 57053e finished in 89 ms! (http://localhost:8080/)
如果出现404页面那么可能是
config.js这个配置文件有问题
# 推荐目录结构
.
├── docs
│ ├── .vuepress (可选的)
│ │ ├── components (可选的)
│ │ ├── theme (可选的)
│ │ │ └── Layout.vue
│ │ ├── public (可选的)
│ │ ├── styles (可选的)
│ │ │ ├── index.styl
│ │ │ └── palette.styl
│ │ ├── templates (可选的, 谨慎配置)
│ │ │ ├── dev.html
│ │ │ └── ssr.html
│ │ ├── config.js (可选的)
│ │ └── enhanceApp.js (可选的)
│ │
│ ├── README.md
│ ├── guide (一般用户都在这个目录下创建网站指南,当然可以不用)
│ │ └── README.md （指南里面的具体内容）
│ └── config.md
│
└── package.json 项目初始化时，根目录下自动生成的配置文件,定义了项目的基本配置信息及需要依赖的各个模块、指定运行脚本命令的npm命令行缩写等
- docs/.vuepress: 用于存放全局的配置、组件、静态资源等。
- docs/.vuepress/components: 该目录中的 Vue 组件将会被自动注册为全局组件。
- docs/.vuepress/theme: 用于存放本地主题。
- docs/.vuepress/styles: 用于存放样式相关的文件。
- docs/.vuepress/styles/index.styl: 将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级。
- docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量，或者设置新的 stylus 颜色常量。
- docs/.vuepress/public: 静态资源目录。
- docs/.vuepress/templates: 存储 HTML 模板文件。
- docs/.vuepress/templates/dev.html: 用于开发环境的 HTML 模板文件。
- docs/.vuepress/templates/ssr.html: 构建时基于 Vue SSR 的 HTML 模板文件。
- docs/.vuepress/config.js: 配置文件的入口文件，也可以是 YML 或 toml。
- docs/.vuepress/enhanceApp.js: 客户端应用的增强。
# 配置网页的图标
module.exports = {
...
head: [
[
'link', { rel: 'icon', href: '/images/common/logo.png' }
]
],
...
}
TIP
图片放在public文件夹下，这里的/images/common/logo.png，实际路径为/public/images/common/logo.png
# 侧边栏标题添加图标
module.exports = {
...
themeConfig: {
...
logo: '/images/common/logo.png',
...
}
...
}
TIP
图片存放的位置同上面说的，要放在public文件夹下
# 默认主题配置
# 导航栏
网页右上角部分的导航栏，试试就知道了
# 导航栏链接
你可以通过 themeConfig.nav 将链接添加到导航栏中：
// .vuepress/config.js
module.exports = {
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' },
{ text: 'External', link: 'https://google.com' },
]
}
}
如果你提供一个 items 而不是 link 的数组，这些链接也可以是下拉菜单：
module.exports = {
themeConfig: {
nav: [
{
text: 'Languages',
items: [
{ text: 'Chinese', link: '/language/chinese' },
{ text: 'Japanese', link: '/language/japanese' }
]
}
]
}
}
同时上述方式是可以嵌套的
# 禁用导航栏
可以使用 themeConfig.navbar，来禁用某个特定页面的导航栏：
// .vuepress/config.js
module.exports = {
themeConfig: {
navbar: false
}
}
# 侧边栏
# 侧边栏的使用
要启用侧边栏, 请使用 themeConfig.sidebar。基本的配置需要一个链接数组：
// .vuepress/config.js
module.exports = {
themeConfig: {
sidebar: [
'/',
'/page-a',
['/page-b', 'Explicit link text']
]
}
}
可以省略 .md 扩展名，以 / 结尾的路径被推断为 */README.md 。该链接的文本是自动推断的（从页面的第一个标题或 YAML front matter 中的显式标题）。如果希望明确指定链接文本，请使用 [link,text] 形式的数组，如['/page-b', 'Explicit link text']。
# 嵌套标题链接
侧边栏自动显示当前激活页面中标题的链接，嵌套在页面本身的链接下。可以使用 themeConfig.sidebarDepth 自定义此行为。默认深度是 1，它提取 h2 标题。将其设置为 0 将禁用标题链接，最大值为2，同时提取 h2 和 h3 标题。
页面也可以在使用 YAML front matter 时覆盖此值：
---
sidebarDepth: 2
---
# 侧边栏分组
可以使用对象将侧边栏链接分成多个分组：
// .vuepress/config.js
module.exports = {
themeConfig: {
sidebar: [
{
title: 'Group 1',
collapsable: false,
children: [
'/'
]
},
{
title: 'Group 2',
children: [ /* ... */ ]
}
]
}
}
侧边栏分组默认情况下是可折叠的，可以强制一个分组始终以 collapsable：false 打开。
# 多个侧边栏
如果希望为不同的内容部分显示不同的侧边栏，要求目录如下:
.
├─ README.md
├─ a.md
├─ b.md
├─ c
│ ├─ README.md
│ ├─ one.md
│ └─ two.md
└─ d
├─ README.md
├─ three.md
└─ four.md
然后，修改你的配置，将每个页面定义到不同的侧边栏中。
// .vuepress/config.js
module.exports = {
themeConfig: {
sidebar: {
'/c/': [
'', /* /c/ */
'one', /* /c/one.html */
'two' /* /c/two.html */
],
'/d/': [
'', /* /d/ */
'three', /* /d/three.html */
'four' /* /d/four.html */
],
// 回退(fallback)侧边栏配置
'/': [
'', /* / */
'a', /* /a.html */
'b' /* /b.html */
]
}
}
}
请确保将回退(fallback)侧边栏，定义在配置的最后。同时文件夹的目录一定要在最后加
/，否则路径会出错
# 搜索框
# 内置搜索
可以通过 themeConfig.search: false 禁用内置搜索框，以及通过 themeConfig.searchMaxSuggestions 来调整搜索框显示的搜索提示数量：
module.exports = {
themeConfig: {
search: false,
searchMaxSuggestions: 5
}
}
内置搜索只能从标题
h2和h3标题构建索引
# Algolia Search
要全文搜索可以使用 Algolia 搜索 (opens new window)。Algolia搜索需要你在使用之前将你的网站提交给它们用于创建索引。更多信息，请参考 Algolia DocSearch 文档 (opens new window)。
# 静态资源的处理
# 内部链接
假如有以下目录结构：
.
├─ README.md
├─ foo
│ ├─ README.md
│ ├─ one.md
│ └─ two.md
└─ bar
├─ README.md
├─ three.md
└─ four.md
那么资源引用按照如下方式进行：
[Home](/) <!-- 将根目录下的 README.md 发送给用户 -->
[foo](/foo/) <!-- 将 foo 目录下的 README.md 发送给用户 -->
[foo 标题锚点](/foo/#heading) <!-- 跳转到 foo 目录下的 README.md 文件中的特定锚点位置 -->
[foo - one](/foo/one.html) <!-- 追加 .html -->
[foo - two](/foo/two.md) <!-- 或者追加 .md -->
# 外部链接
就是按照如下格式进行：[文字](链接)
# 行号
可以通过配置给每个代码块启用行号：
module.exports = {
markdown: {
lineNumbers: true
}
}
但是是全局更改的，单独某一个代码块用行号怎么实现就不清楚了
# 自定义容器
代码示例如下：
:: tip
This is a tip
:::
::: warning
This is a warning
:::
::: danger
This is a dangerous warning
:::
结果输出如下：
TIP
This is a tip
WARNING
This is a warning
DANGER
This is a dangerous warning
同时还可以自定义块的标题，方法如下：
::: danger STOP
Danger zone, do not proceed
:::
结果如下：
STOP
Danger zone, do not proceed
# 目录
markdown文件想生成文件目录，示例如下：
[[toc]]
生成结果如下：
# markdown使用emoji表情
具体说明可以看这里
# markdown使用vue组件
.vuepress/components 中的所有 *.vue 文件都会自动注册为 全局异步(async)组件。例如：
.
└─ .vuepress
└─ components
├─ Demo.vue
在所有 markdown 文件中，都可以直接使用这些组件，其名称(name)是从文件名推断出的：
编写Demo.vue：
<template>
<div>
<button @click="cnt++">请点击我</button>
<span>点击次数：<span class="result">{{ cnt }}</span></span>
</div>
</template>
<script>
export default {
data() {
return {
cnt: 0
}
}
}
</script>
<style scoped>
button {
background-color: #007fff;
border-radius: 5px;
cursor: pointer;
padding: 5px 10px;
border: 0;
color: rgba(255, 255, 255, .8);
margin-right: 20px;
}
.result {
font-weight: 700;
text-decoration: underline;
}
</style>
在markdown中使用：
这是使用了Demo组件的运行结果：<Demo/>
运行结果：
Eaxmple
这是使用了Demo组件的运行结果：
# 评论功能
评论功能使用的是Valine (opens new window)，大家可以参考官方文档的在VuePress中使用 (opens new window)这篇文档进行配置，获取APP ID和APP Key的具体步骤可以参考快速开始 (opens new window)这篇文章，让自己的网站拥有评论功能！也可以参考作者为w晚风 (opens new window)的这篇博客 (opens new window)进行配置。
注意
作者自己使用官方文档配置后的评论区的占了整个宽度，觉得不好看，但是改不了样式，后来看了这篇博客，按照里面步骤操作后就完成了现在的评论功能，我觉得还不错😄，最后封装成了一个组件，具体代码可见下方。
<template>
<div id="comments">
<div class="visitor">
<!-- id 将作为查询条件 -->
<span ref="visitor" class="leancloud-visitors"
data-flag-title="leetcode">
<span class="post-meta-item-text">
<!-- 这是svg图标 -->
<svg t="1660878825126" class="icon" viewBox="0 0 1033 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="2288" width="24" height="24"><path d="M516.644571 146.285714c150.893714 0 278.930286 67.401143 384 178.578286a775.497143 775.497143 0 0 1 116.297143 160.621714c4.022857 7.460571 6.765714 12.946286 8.265143 16.128l8.045714 17.225143-9.472 16.493714c-1.718857 2.998857-4.900571 8.265143-9.435428 15.36a907.154286 907.154286 0 0 1-125.915429 154.550858C778.825143 812.617143 654.226286 877.714286 516.644571 877.714286c-137.581714 0-262.180571-65.097143-371.785142-172.470857A907.154286 907.154286 0 0 1 18.944 550.765714a418.852571 418.852571 0 0 1-9.435429-15.36l-9.508571-16.530285 8.082286-17.188572c5.485714-11.739429 15.981714-31.341714 31.561143-56.173714A775.497143 775.497143 0 0 1 132.644571 324.864C237.714286 213.686857 365.750857 146.285714 516.644571 146.285714z m415.049143 338.029715a703.012571 703.012571 0 0 0-84.224-109.202286C755.090286 277.394286 645.010286 219.428571 516.644571 219.428571c-128.365714 0-238.445714 57.965714-330.825142 155.684572a703.012571 703.012571 0 0 0-102.546286 140.361143 834.706286 834.706286 0 0 0 112.786286 137.508571C293.193143 748.214857 401.152 804.571429 516.644571 804.571429c115.492571 0 223.451429-56.393143 320.585143-151.552a834.706286 834.706286 0 0 0 112.786286-137.545143c-5.229714-9.508571-11.337143-20.004571-18.322286-31.158857zM516.644571 329.142857c100.242286 0 182.857143 82.614857 182.857143 182.857143 0 101.083429-80.713143 182.857143-182.857143 182.857143-101.083429 0-182.857143-80.713143-182.857142-182.857143 0-101.083429 80.713143-182.857143 182.857142-182.857143z m0 73.142857c-61.549714 0-109.714286 48.786286-109.714285 109.714286 0 61.549714 48.786286 109.714286 109.714285 109.714286 61.549714 0 109.714286-48.786286 109.714286-109.714286 0-59.830857-49.883429-109.714286-109.714286-109.714286z" p-id="2289" fill="#8a8a8a"></path></svg>
阅读量：
</span>
<i class="leancloud-visitors-count"></i>
</span>
</div>
<slot></slot>
<h3>评论区：</h3>
<div id="valine-vuepress-comment"></div>
</div>
</template>
<script>
export default {
name: 'Valine',
mounted() {
const path = location.href;
this.$refs.visitor.id = path; // 根据path来找到对应的评论，可自行修改，尽量唯一
this.createValine(path);
},
methods: {
createValine(path) {
const Valine = require('valine');
window.AV = require('leancloud-storage');
new Valine({
el: '#valine-vuepress-comment', // 与上面的id对应即可，可自行修改
appId: '填写自己的appId',
appKey: '填写自己的appKey',
path,
visitor: true,
placeholder: '欢迎留言...', // 输入框的默认占位字符，可自行修改
});
}
}
}
</script>
<style scoped>
svg {
vertical-align: top;
}
.post-meta-item-text {
color: #8a8a8a;
}
</style>
# CSS样式覆盖
具体方法简单概括就是在.vuepress/styles/文件夹下建立palette.styl文件，在该文件里修改样式可以全局生效，.styl的使用可以查看这里 (opens new window)进行学习。
小提示
可以参考这篇CSDN博客05. Vuepress1.x CSS 样式覆盖：修改内容宽度 (opens new window)
# 部署
以下指南基于几个共同的假设：
- 将文档放置在项目的
docs目录中； - 使用默认的构建输出位置（
.vuepress/dist）。 - VuePress 是在项目本地的依赖中安装的，并且配置如下的 npm scripts:
{
"scripts": {
"docs:build": "vuepress build docs"
}
}
# GitHub 页面部署
- 在
docs/.vuepress/config.js设置正确的base。
- 如果打算部署到
https://<USERNAME>.github.io/，就可以省略这一步，因为base默认为"/"。 - 如果打算部署到
https://<USERNAME>.github.io/<REPO>/（也就是说仓库地址是https://github.com/<USERNAME>/<REPO>），设置 base 为"/<REPO>/"
根目录下输入
npm run build对项目进行打包，成功之后会在.vuepress文件夹中生成一个dist文件，这就是我们打包之后的代码在GitHub建立仓库，名字随便取，但是仓库名字得与config.js的base一致，比如创建的仓库名字为：
plugin，那么config.js的配置内容为：
module.exports = {
...
base: "/plugin/", // 记得最后加斜杠
...
}
- 克隆仓库到本地，把dist文件拖到克隆文件夹里
- commit + push后刷新仓库就会出现dist文件
- 把主分支的名字改为
master，然后新建一个分支名为：gh-pages，这是要与deploy.sh脚本里一致 - 在项目根目录建立
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 -
TIP
主要就是改注释部分，三选一即可，根据要求来
- 在
package.json的script加上如下配置：
{
...
"scripts": {
...
"deploy": "bash ./deploy.sh"
},
...
}
- 在终端运行
npm run deploy，然后等待部署完成即可 - 部署完成后，进行如下操作：点击settings 选择pages
把分支设置为gh-pages点击下图中的链接。即可看到自己部署的网站了🎉
TIP
如果之后修改，想要重新部署，只要直接deploy即可(npm run deploy)
WARNING
当然部署后可能没有那么快的更改之前的页面，需要等待一段时间
# 部署遇到的问题
# Permission denied
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.
这是警告我们没有写入权限
解决办法：
用的MAC电脑
- 在当前的vuepress项目的根目录的终端输入
ssh-keygen -t rsa -C "你的邮箱"，一路回车即可，得到以下结果：
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/XXX/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/XXX/.ssh/id_rsa
Your public key has been saved in /Users/XXX/.ssh/id_rsa.pub
The key fingerprint is:
SHA256:C29TOuMv3FxrcaU7TeC358dGAzWqlI0VRNmYe1Q/ulE XXX@qq.com
The key's randomart image is:
+---[RSA 3072]----+
| o+* o|
| = =.|
| = =Eo|
| + =+.o|
| . S o .+o+ |
| o + .o *.+|
| .Oo . = Bo|
| oo+o o o.*|
| .o.. ++|
+----[SHA256]-----+
- 在终端里找到该语句：
Your public key has been saved in /Users/XXX/.ssh/id_rsa.pub，打开提示路径下的文件 - 打开要部署的GitHub的仓库(在GitHub网站中)
- 然后按照如下步骤进行操作：settings Deploy keysadd deploy key
- 添加密钥时需要输入title和key，其中密钥的title随便取个名字，输入Key的时候把上述提示路径的文件里的所有的内容都复制进文本框里，包括开头的
ssh-rsa和结尾的XXX@XX.XXX邮箱
总体步骤如下图所示：
成功后就会添加密钥，如下图所示：
小提示
每个仓库的deploy key只能操作此仓库，但是如果想部署其他仓库，又要生成新的deploy key，这样会很麻烦，但是如果设置了SSH key那么就能操作所有仓库了，操作如下图所示，部署后网站更新会比较慢，耐心等待片刻即可看到更新后的样子。
# 仓库名称与URL基准
之前也提到过，就是需要把仓库名称与base字段的值保持一致即可，具体如下图所示：
WARNING
base的最后一定要加斜杠/
# 仓库的分支
要创建master与gh-pages分支，与deploy.sh中保持一致，如下图所示：
# 更好的手册
其实大部分都可以在vuepress官方文档 (opens new window)中找到，本文档只不过把在本项目中使用的相应内容筛选出来，但是也加了文档中所没有写出的部署遇到的问题。