作者博客地址:管鲍切思世所稀的博客... , 移动端和PC端有差别哦~前几天看到掘金上有人用Vuepress搭建博客,知道vuepress的我,却从来没有亲自上手过,于是乎瞎琢磨一下。总结：vuepress还是很强的,操作简单,没有那么难,只要你认真阅读了文章,你可以做vuepress的爸爸了。这篇文章通俗易懂,从起步到结束,按顺序讲解,认真看完你就是最靓的仔~
关于笔者博客
本博客是基于vuepress搭建而成,什么是vuepress? => vuepress是以Vue驱动的静态网站生成器。VuePress 由两部分组成：第一部分是一个极简静态网站生成器，它包含由 Vue 驱动的主题系统和插件 API，另一个部分是为书写技术文档而优化的默认主题，它的诞生初衷是为了支持 Vue 及其子项目的文档需求。
提示(认真看完你就是最靓的仔~)
你可能需要30-50分钟时间读完它,才能胜任vuepress
Vuepress三大特点:
- 简洁至上: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- Vue 驱动: 享受 Vue + webpack 的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主题。
- 高性能: VuePress 会为每个页面预渲染生成静态的 HTML，同时，每个页面被加载的时候，将作为 SPA 运行。
介绍
vuepress上手成本像 1,2,3一样容易
# 安装
yarn global add vuepress # 或者：npm install -g vuepress
# 新建一个 markdown 文件
echo '# Hello VuePress!' > README.md
# 开始写作
vuepress dev .
# 构建静态文件
vuepress build .注意:请确保你的 Node.js 版本 >= 8.6。
它是如何工作的？
事实上，一个 VuePress 网站是一个由 Vue、Vue Router 和 webpack 驱动的单页应用。如果你以前使用过 Vue 的话，当你在开发一个自定义主题的时候，你会感受到非常熟悉的开发体验，你甚至可以使用 Vue DevTools 去调试你的自定义主题。
在构建时，我们会为应用创建一个服务端渲染（SSR）的版本，然后通过虚拟访问每一条路径来渲染对应的HTML。这种做法的灵感来源于 Nuxt 的 nuxt generate 命令，以及其他的一些项目，比如 Gatsby
官方话就不扯了,更多官方术语详情请移步官方
快速上手
请确保你的 Node.js 版本 >= 8。
全局安装
如果你只是想尝试一下 VuePress，你可以全局安装它：
# 安装
yarn global add vuepress # 或者：npm install -g vuepress
# 新建一个 markdown 文件
echo '# Hello VuePress!' > README.md
# 开始写作
vuepress dev .
# 构建静态文件
vuepress build .现有项目
如果你想在一个现有项目中使用 VuePress，同时想要在该项目中管理文档，则应该将 VuePress 安装为本地依赖。作为本地依赖安装让你可以使用持续集成工具，或者一些其他服务（比如 Netlify）来帮助你在每次提交代码时自动部署。
# 将 VuePress 作为一个本地依赖安装
yarn add -D vuepress # 或者：npm install -D vuepress
# 新建一个 docs 文件夹
mkdir docs
# 新建一个 markdown 文件
echo '# Hello VuePress!' > docs/README.md
# 开始写作
npx vuepress dev docs注意如果你的现有项目依赖了 webpack 3.x，推荐使用 Yarn 而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树。
接着，在 package.json 里加一些脚本:
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}然后就可以开始写作了:
yarn docs:dev # 或者：npm run docs:dev要生成静态的 HTML 文件，运行：
yarn docs:build # 或者：npm run docs:build默认情况下，文件将会被生成在 .vuepress/dist，当然，你也可以通过 .vuepress/config.js 中的 dest 字段来修改，生成的文件可以部署到任意的静态文件服务器上，参考 部署 来了解更多。
目录结构
VuePress 遵循 “约定优于配置” 的原则，推荐的目录结构如下：
注意vuepress约定入口目录必须是 docs ,务必根目录是docs
.
├── docs
│ ├── .vuepress (可选的) → 官方标注可选,不过一般都会用这个文件夹,核心文件夹
│ │ ├── components (可选的) → 这个文件夹一些以.vue结尾的vue组件,可以在markdown文件里使用
│ │ ├── theme (可选的) → 可以配置自己的博客
│ │ │ └── Layout.vue
│ │ ├── public (可选的) → 放一些公共静态资源 使用方式 /xxx, 请必须以 `/` 开始表示根
│ │ ├── styles (可选的) → 样式
│ │ │ ├── index.styl → 自定义样式
│ │ │ └── palette.styl → 用于重写默认颜色常量，或者设置新的 stylus 颜色常量
│ │ ├── templates (可选的, 谨慎配置)
│ │ │ ├── dev.html → 用于开发环境的 HTML 模板文件
│ │ │ └── ssr.html → 构建时基于 Vue SSR 的 HTML 模板文件
│ │ ├── config.js (可选的) → 配置文件的入口文件，也可以是 YML 或 toml
│ │ └── enhanceApp.js (可选的) → 客户端应用的增强
│ │
│ ├── README.md
│ ├── guide
│ │ └── README.md
│ └── config.md
│
└── package.json注意当你想要去自定义 templates/ssr.html 或 templates/dev.html 时，最好基于 默认的模板文件 来修改，否则可能会导致构建出错。
默认的页面路由
此外，对于上述的目录结构，默认页面路由地址如下：
| 文件的相对路径 | 页面路由地址 |
|---|---|
| /README.md | / |
| /guide/README.md | /guide/ |
| /config.md | /config.html |
基本配置
// dcos/.vuepress/config.js
module.exports = {
title:"取舍", // HTML的title
description:"管鲍切思世所稀博客", // 描述
keywords:"管鲍切思世所稀博客", // 关键字
head:[ // 配置头部
[
['link', {rel:'icon', href:"/icon.png"}],
['meta', {'name':'viewport', content:"width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0;"}]
]
],
markdown: {
lineNumbers: true, // 代码显示行号
},
dest:"./outer", // 设置打包路径
lastUpdated: 'Last Updated', // 显示更新时间
themeConfig:{
logo:"/icon.png", // 导航栏左边logo,不写就不显示
sidebarDepth: 2, // 侧边栏显示2级
nav:[ // 导航栏配置
{ text: 'vue', link: '/' },
{ text: 'css', link: '/blog/' },
{
text: 'js', // 这里是下拉列表展现形式。 items可以一直嵌套下去
items:[
text:"ES5", link:"/js/es5/",
text:"ES6", link:"/js/es6/",
]
},
{text: 'github', link:"https://github.com/1046224544"}
],
// 为以下路由添加侧边栏
sidebar: ['/', '/git', '/vue']
// 嵌套侧边栏 以对象的方式嵌套下去
// sidebar: {
// '/2019/': [
// ['','前言(2019)'],
// {
// title:"10月份",
// collapsable:false,
// sidebarDepth:2,
// children:[
// ["Nginx部署Vue项目", "Nginx部署Vue项目"],
// ["NVM自由切换Node版本", "NVM自由切换Node版本小笔记"],
// ["KTV点歌系统", "KTV点歌系统"],
// ]
// },
// {
// title:"9月份",
// collapsable:false,
// sidebarDepth:2,
// children:[
// ["综合性博客网站", "综合性博客网站"]
// ]
// }
// ],
// ...
// }
},
plugins:[
// 'axios' // 配置插件
]
}
}注意以上就是完整的基本config.js配置文件,有强迫症的同学肯定会觉得文件大了,不好维护。的确,当我们的路有文件变多了,文件会变得很长。笔者在这里推荐,将导航栏和侧边栏单独拆分两个文件,以文件加载的方式引入,这样路由导航栏和侧边栏就可以无限嵌套,你也可以无限往下分级,建文件夹等等达到分类效果。
如下：
// docs/.vuepress/config.js
module.exports = {
...部分(同上)
themeConfig:{
nav: require('./nav'), // 引入导航栏
sidebar:require('./sidebar'), // 引入侧边栏
},
...
}
// docs/.vuepress/sidebar.js
module.exports = {
"/api/front/2019/": require('../.vuepress/frontbar/2019'), // 继续分类
"/api/front/2020/": require('../.vuepress/frontbar/2020'),
"/api/end/2019/": require('../.vuepress/endbar/2019'),
"/api/learn/koa/": require('../.vuepress/learnbar/koabar'),
"/api/learn/express/": require('../.vuepress/learnbar/expressbar'),
"/api/learn/java/": require('../.vuepress/learnbar/javabar'),
"/api/learn/es6/": require('../.vuepress/learnbar/es6bar'),
"/api/learn/vue/": require('../.vuepress/learnbar/vuebar'),
}
// docs/.vuepress/nav.js
module.exports = [
{text:"首页", link:"/"},
{
text:"技术API",
ariLabel:"技术API",
items:[
{text:"koa", link:"/api/learn/koa/"},
{text:"vue", link:"/api/learn/vue/"},
{text:"es6", link:"/api/learn/es6/"},
{text:"java", link:"/api/learn/java/"},
{text:"express", link:"/api/learn/express/"},
]
},
{
text:"日常博客",
ariLabel:"日常博客",
items:[
{text:"前端",link:"/api/front/"},
{text:"后端",link:"/api/end/"},
{text:"其他",link:"/api/orther/1.md"},
]
},
{text:"关于博客", link:"/api/builog/"},
{text:"关于作者", link:"/api/author/"},
{
text:"其他小站",
ariLabel:"其他小站",
items:[
{text:"掘金", link:'https://juejin.im/user/5d1079ab6fb9a07ed4410cc0'},
{text:"SegmentFault", link:'https://segmentfault.com/u/98kk'},
{text:"CSDN", link:'https://blog.csdn.net/weixin_43374176'},
]
},
{
text:"联系",
ariLabel:"联系",
items:[
{text:"邮箱", link:"mailto:[email protected]", target:"_blank"},
{text:"其他", link:"/api/contact/"}
]
},
{text:"GitHub", link:"http://github.com/1046224544"}
]笔者目录截图:
注意只要是自己配置的目录,都必须在docs目录下有对应的目录结构, 如果你的路径是/api/aboutme/, 那么对象的文件目录就是/docs/api/aboutme/readme.md,默认根路径就是readme.md文件。 如果你的路径是/api/aboutme/ktv点歌系统, 那么对象的文件目录就是/docs/api/aboutme/ktv点歌系统.md
在 Vue文件中使用第三方库(两步走)
- 在 VuePress 中编写 Vue 代码，和我们通常的编写
单文件的方式一致，有些时候我们有可能需要使用 Vue 的 UI 组件库。例如Element，Mint等，通常我们在项目中使用这些 UI 组件库的时候，我们都会在main.js或botostrap.js文件中统一注册。好在 VuePress 中也支持这种功能，我们可以通过创建一个.vuepress/enhanceApp.js文件来做一些应用级别的配置，这个文件exprot default 一个钩子函数，在这个钩子中你可以做一些特殊处理，例如添加全局路由钩子，注册外部组件库。 - 在vue文件中像平时一样调用它
// .vuepress/enhanceApp.js
// 全局注册 Element 组件库
import Vue from 'vue'
import Element from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'
export default ({
Vue,
options,
router
}) => {
Vue.use(Element)
}
// 在vue中使用第三方库
// 定义一个vue组件 /docs/.vuepress/componets/demo.vue
{{ msg }}
button // 使用了el-button
在markdown文件中使用vue组件
请确保只在 beforeMount 或者 mounted 访问浏览器 / DOM 的 API。
如果你正在使用，或者需要展示一个对于 SSR 不怎么友好的组件（比如包含了自定义指令），你可以将它们包裹在内置的
请注意，这并不能解决一些组件或库在导入时就试图访问浏览器 API 的问题 —— 如果需要使用这样的组件或库，你需要在合适的生命周期钩子中动态导入它们：
如果你的模块通过 export default 导出一个 Vue 组件，那么你可以动态注册它：
参考:
Markdown 拓展
链接
内部链接
网站内部的链接，将会被转换成 README.md 或者 index.md 文件都会被自动编译为 index.html，对应的链接将被视为 /。
以如下的文件结构为例：
.
├─ README.md
├─ foo
│ ├─ README.md
│ ├─ one.md
│ └─ two.md
└─ bar
├─ README.md
├─ three.md
└─ four.md假设你现在在 foo/one.md 中：
[Home](/)
[foo](/foo/)
[foo heading](./#heading)
[bar - three](../bar/three.md)
[bar - four](../bar/four.html) 链接的重定向
VuePress 支持重定向到干净链接。如果一个链接 /foo 找不到，VuePress 会自行寻找一个可用的 /foo/ 或 /foo.html。反过来，当 /foo/ 或 /foo.html 中的一个找不到时，VuePress 也会尝试寻找另一个。借助这种特性，我们可以通过官方插件 vuepress-plugin-clean-urls 定制你的网站路径。
注意无论是否使用了 permalink 和 clean-urls 插件，你的相对路径都应该依赖于当前的文件结构来定义。在上面的例子中，即使你将/foo/one.md的路径设为了/foo/one/，你依然应该通过./two.md来访问/foo/two.md。
外部链接
外部的链接将会被自动地设置为 target="_blank" rel="noopener noreferrer":
你可以自定义通过配置 config.markdown.externalLinks 来自定义外部链接的特性
Front Matter
VuePress 提供了对 YAML front matter 开箱即用的支持:
---
title: Blogging Like a Hacker
lang: en-US
---这些数据可以在当前 markdown 的正文，或者是任意的自定义或主题组件中使用。
想了解更多，请移步 Front Matter
GitHub 风格的表格
输入
| Tables | Are | Cool |
| ------------- |:-------------:| -----:|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |输出
| Tables | Are | Cool |
|---|---|---|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
Emoji
输入
:tada: :100:输出
- 掘金这里markdown这里不支持，可以看我博客原文:博客原文阅读
你可以在这个列表找到所有可用的 Emoji。
目录
输入
[[toc]]输出
- 掘金这里markdown这里不支持,可以看我博客原文:博客原文阅读
目录（Table of Contents）的渲染可以通过 markdown.toc 选项来配置。
自定义容器
输入
::: 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
:::
- 掘金这里markdown这里不支持,可以看我博客原文:博客原文阅读
你也可以自定义块中的标题：
::: danger STOP
Danger zone, do not proceed
:::::: danger STOP
Danger zone, do not proceed
:::
- 掘金这里markdown这里不支持,可以看我博客原文:博客原文阅读
参考:
代码块中的语法高亮
VuePress 使用了 Prism 来为 markdown 中的代码块实现语法高亮。Prism 支持大量的编程语言，你需要做的只是在代码块的开始倒勾中附加一个有效的语言别名：
输入
export default {
name: 'MyComponent',
// ...
}
```
**输出**
export default {
name: 'MyComponent',
// ...
}
**输入**
-
{{ todo.text }}
**输出**
v-for="todo in todos"
:key="todo.id"{{ todo.text }}
## 代码块中的行高亮
**输入**export default {
data () {
return {
msg: 'Highlighted!'
}
}
}**输出**export default {
data () {
return {
msg: 'Highlighted!'
}}
}
## 行号
你可以通过配置来为每个代码块显示行号：module.exports = {
markdown: {
lineNumbers: true}
}
## 导入代码段
你可以通过下述的语法导入已经存在的文件中的代码段：<<< @/filepath
它也支持 行高亮：<<< @/filepath{highlightLines}
>**注意**由于代码段的导入将在 webpack 编译之前执行，因此你无法使用 webpack 中的路径别名，此处的 `@` 默认值是 `process.cwd()`。
## 进阶配置
VuePress 使用 [markdown-it](https://github.com/markdown-it/markdown-it) 来渲染 Markdown，上述大多数的拓展也都是通过自定义的插件实现的。想要进一步的话，你可以通过 `.vuepress/config.js` 的` markdown` 选项，来对当前的 `markdown-it` 实例做一些自定义的配置：
module.exports = {
markdown: {
// markdown-it-anchor 的选项
anchor: { permalink: false },
// markdown-it-toc 的选项
toc: { includeLevel: [1, 2] },
extendMarkdown: md => {
// 使用更多的 markdown-it 插件!
md.use(require('markdown-it-xxx'))
}}
}
## 评论系统 Valine
>看完本节内容,你就可以胜任Valine了，从此网站不在寂静,本评论系统通俗易懂,完全可以解决其他作者讲解此部分留下的后遗症,赶紧收藏吧！
- 需要安装leancloud-storage和valine
- [valine官网](https://valine.js.org/quickstart.html)
- appid和appkey的获取需要注册[leancloud](https://leancloud.cn/)，然后可以新建应用并在`设置>应用 key`可以查看
### 安装
Install leancloud's js-sdk
npm install leancloud-storage --save
Install valine
npm install valine --save
### 配置
Components.vue组件// 新建Components.vue组件
Page.vue// Page.vue
### 使用(按需使用)
比如你想在china.md 文件中使用, 你就在头部 贴入一下代码
评论系统不是每个页面都一样的,根据不同的页面，加载不同的评论，
看了很多小编说什么评论的乱七八糟,看完这篇文章,对Valine不再那么恐慌,让你玩转第三方评论// China.md
coments: true
**截图**
>Valine实例与leancloud-storage实例 在每次页面加载时会向服务器发起带当前url参数的请求以获取评论数据，而这个url参数每次都是一样。首先Valine 实例与 leancloud-storage 实例都在 mounted 钩子中初始化或挂载至 window 对象上了。当页面 url 变化时，Page.vue 本身并没有变化,但mounted会重新触发。
## 关于其他插件
你可以移步到官网查看,插件就是给我们用的,如果难的话,还叫什么插件,只要认真看,你总会看懂的
## 部署到 Github pages
当我们将文档写好后就到了我们最关心的地方了，怎么将打包后的代码推送到远程仓库的 `gh-pages` 分支上，网上应该有很多文章描述怎么做，但是很多方法比较麻烦，还好有工具已经为我们解决了这个麻烦了。
### 创建一个deploy.sh
touch 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://.github.io
git push -f [email protected]:/.github.io.git master
如果发布到 https://.github.io/
git push -f [email protected]:/.git master:gh-pages
cd -
### 设置package.json{
"scripts": {
"deploy": "bash deploy.sh"
},}
### 发布npm run deploy // 即可自动构建部署到github上。
**详情移步官网**
- [vuepress.vuejs.org](https://vuepress.vuejs.org/zh/guide/deploy.html)
## 总结
相比较 Hexo 而言 VuePress 上手更加容易，功能也更强大，例如在 VuePress 可以注册自定义组件，而且 VuePress 中编写 Vue 和平时一样学习成本几乎为零。所以如果您正在开源一款 Vue 相关的库或是其他项目，您都可以使用 VuePress 作为您的文档编辑工具。虽然并没有完全将 VuePress 内容讲完，学完该篇文章相信你可以对 VuePress 有个大概的了解，您至少可以快速搭建一个博客，如果您想对 VuePress 有更多了解，请参考 [Vuepress 中文 API](https://vuepress.vuejs.org/zh/)
## 在线查看
[管鲍切思世所稀的博客...](https://blog.usword.cn/api/builog/)
>移动端和PC端有差别哦~
## 博客部分截图
## 其他
- [完整的综合性网站](https://juejin.im/post/5da2a8ed6fb9a04de818eeff)
- [KTV点歌系统](https://juejin.im/post/5dac3b4351882576534d33d7)
- [Nginx部署Vue项目](https://juejin.im/post/5dbbb4df51882522c14f81a8)
- [NVM的使用小技巧](https://juejin.im/post/5dae55b75188257d8936be94)
## 联系
如果大家有兴趣，欢迎关注公众号：_facebook(web技术进阶),查看更多优质文章，欢迎大家加入我的前端交流群：[866068198](https://qm.qq.com/cgi-bin/qm/qr?k=m8asYpHTs_cw3lJVLVv4U6wbF4ep2Ny5&authKey=OknnnniiEOFaIZNhEl2dUIhSrKPB8wGrEYu1AGyS01Y6XXz7doQl7v%2FitvPRr3ii) ，一起交流学习前端技术。博主目前一直在自学Node中，技术有限，如果可以，会尽力给大家提供一些帮助，或是一些学习方法.
- 公众号
- QQ群
## 福利
有需要刷钻，刷会员，刷腾讯视频会员，涨粉丝等等相关意向的小伙伴们，可以访问作者推荐的超值代刷网站：[qq.usword.cn](http://qq.usword.cn), 也可以扫描下方二维码
## 最后
>如果老板觉得这篇文章有帮助,就大方的点个赞吧,老板大气,老板最帅~
If you have some questions after you see this article, you can contact me or you can find some info by clicking these links.
- [juejin@wsm's juejin](https://juejin.im/user/5d1079ab6fb9a07ed4410cc0)
- Gi[tHub@1046224544](https://github.com/1046224544)
- [Segmentfault@wsm](https://segmentfault.com/u/98kk)