Vuepress中文网
VuePress 要求 Node.js 的版本 >= 8.6,本教程在是 Ubuntu18 下实验的;
安装步骤:
LTS 版本
的;tar -xvf node-v14.15.4-linux-x64.tar.xz
# 添加至 ~/.bathrc
export PATH=~/www/node-v14.15.4-linux-x64/bin:$PATH
# 添加后执行 source ~/.bashrc
# 查看版本信息
node -v
npm version
npx -v
点击这里 下载 yarn-v1.17.3.tar.gz
。
将下载的压缩包解压,其中bin目录下就是 node 的可执行文件;
tar -xvf yarn-v1.17.3.tar.gz
将 bin 目录添加到环境变量;
# 添加至 ~/.bathrc
export PATH=~/www/yarn-v1.17.3/bin:$PATH
# 添加后执行 source ~/.bashrc
查看安装;
yarn -v
自定义 yarn 的缓存目录!
yarn config set global-folder "/home/tamray/www/yarn-global"
yarn config set cache-folder "/home/tamray/www/yarn_cache"
配置晚后,yarn 下载的所有包都会缓存在该目录中,下一次安装的时候会首先从这里面查找。如果要在离线环境下使用 yarn
,就可以把需要的包先下载到缓存目录,然后拷贝到离线环境中,用 yarn 命令离线安装。
yarn 命令的常用参数
# 在指定目录下执行,初始化项目,会产生 package.json 文件,里面有基本的配置信息
yarn init
# 为项目添加xxx包,-D表示局部添加,对应包缓存在上面设置的/home/tamray/www/yarn_cache中
yarn add xxx -D
yarn add xxx -D --offline # 离线添加包
# 安装 package.json 中的所有包
yarn install
yarn install --offline # 离线安装
# 在 root 目录下创建并进入my_blogs目录
mkdir ~/my_blogs
cd ~/my_blogs
# 项目初始化
yarn init
# 安装 vuepress 包
yarn add vuepress -D
初始化后会在项目文件夹中生成 package.json 文件,添加下面的内容,以简化 vuepress 命令:
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
},
贴一个自己项目的 package.json,里面包含了用到的一些包名称,执行命令 yarn install
即可自动安装完所有包,并缓存到本地:
{
"name": "tamray-blogs",
"version": "1.0.0",
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs",
"deploy": "bash deploy.sh"
},
"license": "MIT",
"devDependencies": {
"vuepress": "^1.8.0",
"@vuepress/plugin-back-to-top": "^1.5.3",
"@vuepress/plugin-pwa": "^1.5.4",
"inquirer": "^7.1.0",
"json2yaml": "^1.1.0",
"markdown-it-footnote": "^3.0.2",
"markdown-it-ins": "^3.0.0",
"markdown-it-mark": "^3.0.0",
"markdown-it-sub": "^1.0.0",
"markdown-it-sup": "^1.0.0",
"markmap-lib": "^0.9.3",
"moment": "^2.25.3",
"vuepress-plugin-baidu-autopush": "^1.0.1",
"vuepress-plugin-baidu-tongji": "^1.0.1",
"vuepress-plugin-demo-block": "^0.7.2",
"vuepress-plugin-flowchart": "^1.4.3",
"vuepress-plugin-one-click-copy": "^1.0.2",
"vuepress-plugin-thirdparty-search": "^1.0.2",
"vuepress-plugin-zooming": "^1.1.7",
"vuepress-theme-vdoing": "^1.4.2",
"yamljs": "^0.3.0"
},
"dependencies": {
"d3": "5",
"markdown-it-katex": "^2.0.3",
"vuepress-plugin-comment": "^0.7.3",
"vuepress-plugin-mermaidjs": "^1.7.1"
}
}
然后创建必要的文件结构,目录结构如下:
.
├── docs # 文件夹
│ └── README.md # 文件
│ └── .vuepress # 文件夹
│ ├── config.js # 文集建安
│ └── public # 文件夹
└── package.json # 文件
其中:
yarn docs:dev # npm run docs:dev
启动后终端会显示访问的地址,如:http://localhost:8080/,直接打开浏览器访问即可;
要生成静态的 HTML 文件,运行:
yarn docs:build # 或者:npm run docs:build
本实验使用的默认主题,可以修改默认的配置,比如导航栏、左侧栏等,可以参考官网,描述得很详细,下面是满足个人喜好的基本配置:
module.exports = {
markdown: {
lineNumbers: true, // 代码行数
toc: { includeLevel: [1, 2] }, // 显示的目录深度
},
themeConfig: {
lastUpdated: 'Last Updated', // 显示最后的更新时间
sidebarDepth: 3, // 侧边栏的目录深度
repo: 'https://github.com/Tamray/myblog', // 源码地址
repoLabel: '查看源码', // (查看源码的)组件名称
docsBranch: 'master', // git 源仓库 仓库分支
docsDir: 'docs', // 仓库下的文件夹
editLinks: true, // 编辑链接
editLinkText: '修改页面', // 链接字段
serviceWorker: {
updatePopup: {
// 刷新内容的弹窗
message: '发现新内容',
buttonText: '刷新'
}
},
smoothScroll: true, //页面滚动效果
nav: [ // 导航栏
{ text: 'Home', link: '/' }
{ text: 'Class1',
items: [
{ text: 'Class11', link: '/class1/class11/' },
{ text: 'Class12', link: '/class1/class12/' }
],
},
{ text: 'Class2', link: '/class2/' }
],
sidebar: { // 侧边栏
'/class1/class11/': class11,
'/class1/class12/': class12,
'/class2/': class2
}
}
}
markdown-it 的其他插件参考这里
更多插件在npm中查找
此插件用来支持 katex 数学公式;
安装:
cd ~/my_blogs
yarn add markdown-it-katex # npm install markdown-it-katex
.vuepress/config.js
下的配置,添加:module.exports = {
markdown: {
extendMarkdown: md => {
md.use(require('markdown-it-katex')) // 启动 markdown-it-katex 插件
}
}
}
.vuepress/config.js
文件中的 head
项:module.exports = {
head: [
['link', { rel: 'stylesheet', href: 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.7.1/katex.min.css' }],
['link', { rel: "stylesheet", href: "https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/2.10.0/github-markdown.min.css" }]
]
}
此插件可以自动生成侧边栏,不用再手动添加;
安装:
yarn add vuepress-plugin-auto-sidebar
.vuepress/config.js
下的配置,添加:plugins: {
"vuepress-plugin-auto-sidebar": {}
},
.vuepress/config.js
中删除 sidebar 相关的设置;此插件实现了从底部回到顶部的按钮;
安装:
yarn add -D @vuepress/plugin-back-to-top
.vuepress/config.js
下的配置,添加:plugins: {
'@vuepress/back-to-top': true,
},
此插件实现了图片的放大查看功能;
安装:
yarn add -D @vuepress/plugin-medium-zoom
.vuepress/config.js
下的配置,添加:plugins: {
'@vuepress/medium-zoom': {
selector: '.content__default img',
},
},
这个插件将会在你切换页面的时候,在顶部显示进度条;
安装:
yarn add -D @vuepress/plugin-nprogress
.vuepress/config.js
下的配置,添加:plugins: {
'@vuepress/nprogress': {}
}
支持 mermaid 绘图的插件
yarn add vuepress-plugin-mermaidjs
.vuepress/config.js
下的配置,添加:plugins: {
'vuepress-plugin-mermaidjs': {}
}
--- mermaid
sequenceDiagram
Alice->John: Hello John, how are you?
loop every minute
John-->Alice: Great!
end
---
<img src="/app.png" width="400"/>
如:
<iframe src="/markmap/002.html" width="100%" height="400" frameborder="0">iframe>
或:<iframe src="/markmap/002.html" width="100%" height="400" frameborder="0" scrolling="No" leftmargin="0" topmargin="0">iframe>
参数 | 说明 |
---|---|
width=“100%” | 显示宽度(可以用像素,可以用百分比) |
height=“400” | 显示高度(可以用像素,可以用百分比) |
frameborder=“0” | 去除边框 |
scrolling=“No” | 禁止鼠标滑动 |
leftmargin=“0” | 左边距 |
topmargin=“0” | 右边距 |
如:
::: tip
这是一个提示
:::
::: warning
这是一个警告
:::
::: danger
这是一个危险警告
:::
::: details
这是一个详情块,在 IE / Edge 中不生效
:::
::: tip
这是一个提示
:::
::: warning
这是一个警告
:::
::: danger
这是一个危险警告
:::
::: details
这是一个详情块,在 IE / Edge 中不生效
:::