Vue进阶篇-VuePress文档管理安装及Github免费建站

本篇内容技术比较简单,大神自动飘过

VuePress是vue框架下静态网站生成器,用于生成技术文档相当实用。结合部署到github的站点功能,用起来不要太爽。编辑内容使用Markdown编辑器,做开发的肯定是喜欢这个编辑器了。整体流程就是打好框架,在里面编辑md文件,vue自动预览更新。编辑完成之后,build成纯静态文件,然后上传到站点中去,样子看着还是很舒服的。
这里有个缺点,就是只能处理纯静态的内容,想要动态内容自行绕过。另外,这个模块目前属于开发的alpha阶段,功能接口都有可能重新调整。
本文指导从零开始搭建所有的vuepress安装,使用并部署到github站点上成功运行。最终效果请点击文章底部的阅读原文。
安装
注意,nodejs版本自己去找最新稳定版 直接上命令:
# 安装 npm install -g vuepress # 新建一个 markdown 文件 echo \'# Hello VuePress!\' > README.md # 开始写作 vuepress dev . # 构建静态文件 vuepress build .
上面命令是直接在根目录里面搭建的静态内容。一般这种技术文档,除非专门技术,都是在子文件夹下面的。
# 将 VuePress 作为一个本地依赖安装 npm install -D vuepress # 新建一个 docs 文件夹 mkdir docs # 新建一个 markdown 文件 echo \'# Hello VuePress!\' > docs/README.md # 开始写作 npx vuepress dev docs
官方指导再package.json的script里面添加一条快捷命令,感觉并没有降低多少要敲命令的成本,估计就是为了少计几个命令吧。
{ "scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs" } }
运行起来站点,然后就可以开始进行写作了,保存文件都是实时更新的。
npm run docs:dev # 或者 vuepress dev docs
编写完成之后打包静态文件
npm run docs:build # 或者 vuepress build docs
打包之后默认会放在 ** .vuepress/dist ** 文件夹下面,把里面的内容全部直接上传到任何的空间下面都可以运行。不过可能因为使用绝对路径的原因,直接运行index.html的话,里面的样式图片脚本都不运行的。
文件目录
这里对应的默认文件是 README.md ,类似index.html,index.jsp,index.php等等。引擎再打包的时候会把 README.md 解析成index.html。
. ├── docs │ ├── .vuepress (可选的) # 用于存放全局的配置、组件、静态资源等。 │ │ ├── components (可选的) # 该目录中的 Vue 组件将会被自动注册为全局组件 │ │ ├── theme (可选的) #用于存放本地主题。 │ │ │ └── Layout.vue │ │ ├── public (可选的) #静态资源目录 │ │ ├── styles (可选的) #用于存放样式相关的文件。 │ │ │ ├── index.styl #将会被自动应用的全局样式文件,会生成在最终的 CSS 文件结尾,具有比默认样式更高的优先级。 │ │ │ └── palette.styl #用于重写默认颜色常量,或者设置新的的 stylus 颜色常量。 │ │ ├── templates (可选的, 谨慎配置) #存储 HTML 模板文件。 │ │ │ ├── dev.html #用于开发环境的 HTML 模板文件。 │ │ │ └── ssr.html #构建时基于 Vue SSR 的 HTML 模板文件。 │ │ ├── config.js (可选的) #配置文件的入口文件,也可以是 YML 或 toml。 │ │ └── enhanceApp.js (可选的) #客户端应用的增强。 │ │ │ ├── README.md │ ├── guide │ │ └── README.md │ └── config.md │ └── package.json
按照对应的目录结构,生成对应的路由,默认的 / 会解析 docs/README.md。而 /guide/ 会显示docs/guide/README.md的内容。/config.html 会显示 docs/config.md的内容。
固定链接
使用过wordpress的人员应该都知道在设置里面有个选项是固定连接。vuepress的部分也是一样的。wordpress里面关于这块儿的中文翻译是
WordPress让您能够为您的永久链接和存档建立自定义URL结构。自定义URL结构可以为您的链接提高美感、可用性和前向兼容性。
这样可以在连接里面进行拼接 年,月,日,文件名等。由于vuepress关于博客部分的设计还不完善,关于作者,id,分类,等等就没有办法很好的拼接进来。使用方法可以通过全局配置或者局部文件配置来实现。
// .vuepress/config.js进行全局配置 module.exports = { permalink: \'/:year/:month/:day/:slug\' } # 或者在文件前方进行局部文件的配置 --- title: Hello World permalink: /hello-world --- Hello!
可以配置选项有
:year # 文章年份,4位 :month # 文章月份,2位,会自动补0 :i_month # 文章月份,不会自动补0 :day # 文章日,2位,会自动补0 :i_day # 文章日,2位,不会自动补0 :slug # 开启固定链接后的别名,英文。 :regular # vuepress默认的链接
不过呢,我自己没有试成功,没有花时间去详细研究啥原因。
全局配置
使用vuepress比较重要的部分就是设置配置文件了。由于默认的主题就挺好看的,自定义主题的事情再说了。
配置信息都包含在 docs/.vuepress/config.js 文件中,格式如下:
module.exports = { permalink: \'/:year/:month/:day/:slug\', //固定链接的全局配置 markdown: { //markdown编辑器的配置 lineNumbers: true, //代码显示行号,默认 false toc: { includeLevel: [1, 2] }, //显示目录的默认层级 }, title: \'Vue教程\', //网站的标题,默认主题几个地方用到 description: \'Tingno记编写的VUE教程\', //网站的描述 base:\'/docs/\', //要部署的根目录,不配置的话,都会到网站根目录下面 themeConfig: { //主题的配置信息 nav: [ //导航栏配置 { text: \'首页\', link: \'/\' }, //没有子导航的,显示文字和链接 { text: \'基础\', items: [ //有自导航的,就显示文字和子导航对象,下同 { text: \'入门\', link: \'/base/base\' }, { text: \'常见文件\', link: \'/base/file\' }, { text: \'组件化\', link: \'/base/package\' }, { text: \'ES6新特性\', link: \'/base/es6\' }, ]}, { text: \'核心\', items: [ { text: \'路由Router\', link: \'/core/Route\' }, { text: \'状态Vuex\', link: \'/core/Vuex\' }, ]}, { text: \'工具\', items: [ { text: \'git\', link: \'/tools/git\' }, { text: \'webpack\', link: \'/tools/webpack\' }, ]}, { text: \'博客\', link: \'https://notes.tingno.com\' }, //链接也可以是外部链接 ], sidebar: [ //配置边栏的链接,一个对象、一个数组都可以。也可以分组,分组配置找官方。 \'/\', //默认配置链接,名称会自动生成,首页或者文件第一个标题 [\'/base/base\',\'入门\'], //或者指定链接和显示标题 [\'/base/es6\', \'ES6新特性\'], [\'/base/file\', \'常见文件\'], [\'/base/package\', \'组件化\'], { //复杂的带子目录的对象 title: \'核心\', //显示名称 collapsable: false, //控制子目录是否可折叠,默认 true,下同 children: [ [\'/core/Route\', \'路由Router\'], [\'/core/Vuex\', \'状态Vuex\'] ] }, { title: \'工具\', children: [ [\'/tools/git\', \'版本管理工具git\'], [\'/tools/webpack\', \'webpack\'] ] } ], sidebarDepth:5, displayAllHeaders: true, // 显示所有活动链接,默认值:false activeHeaderLinks: false, // 关闭实时更新url的hash值,默认值:true lastUpdated: \'Last Updated\', // 显示最后更新时间 //帮助编辑 // 假定是 GitHub. 同时也可以是一个完整的 GitLab URL repo: \'q5276/vuestudy\', // 自定义仓库链接文字。默认从 `themeConfig.repo` 中自动推断为 // "GitHub"/"GitLab"/"Bitbucket" 其中之一,或是 "Source"。 repoLabel: \'查看源码\', // 以下为可选的编辑链接选项 // 假如你的文档仓库和项目本身不在一个仓库: docsRepo: \'q5276/vuestudy\', // 假如文档不是放在仓库的根目录下: docsDir: \'docs\', // 假如文档放在一个特定的分支下: docsBranch: \'master\', // 默认是 false, 设置为 true 来启用 editLinks: true, // 默认为 "Edit this page" editLinkText: \'帮助我们改善此页面!\' } }
当然还有好多其他的配置信息,可以直接通读官方文档去了解。
局部配置
官方文档里面一直强调用 YAML front matter 来进行配置,由于孤陋寡闻,英文太烂,看的我一脸懵逼。后来了解,就是在你编辑文档的头部直接使用 两个 — 进行包围的配置信息,YAML也姑且理解为也是一种标记语言吧。格式就是一行一个配置,通过冒号: 进行配置名和配置值的设置。举例
--- editLink: false --- # 下面是markdown的正文内容
所有在具体的文档里面放的 YAML标记都属于局部配置信息。配置解释为:
--- #默认主题中配置首页的配置信息 home: true #设置true就代表是首页了 actionText: 快速上手 → #中间有个按钮的文字 actionLink: /base/base #中间按钮的链接 features: # 下面内容直接对照下默认主题上显示的内容就知道了 - title: 方便理解 details: 总之是各种奇奇怪怪的帮助理解例子,懂就懂,不懂拉倒。 - title: VuePress驱动 details: 照着VuePress官方教程搭建的这个文档,至于内容,当然是把以前写的那些复制粘贴上来了。 - title: 高性能 details: VuePress最后会渲染成一个静态文件,你说高性能不性能。如果你打开的慢,只能说明站长比较穷,服务器太差。 footer: MIT Licensed | Copyright © 2018-present Evan You #其他常用配置信息 navbar: false #禁用侧边栏 sidebarDepth: 2 #标题嵌套深度 sidebar: auto #自动生成侧边栏 prev: ./some-other-page #上一篇内容 next: false #下一篇内容,false是没有 editLink: false #禁止全局配置里面编辑文件部分 pageClass: custom-page-class #自定义类名 layout: SpecialLayout #自定义布局的组件名 ---
Markdown 拓展
由于我平时编辑内容使用的是有道云笔记,所以罗列一些在有道云笔记的markdown文档里面没有的,而且感觉还挺有用的拓展。
- vuepress里面默认是会给所有的标题都加上锚链接,h1-h6,并且会根据标题来生成目录。
- 直接在内容中使用 [[toc]] 会生成自动目录。
- 代码高亮,在代码开始标记后进行“` js{4,6} 可以指定js代码行高亮。
VUE拓展
既然使用了vue引擎,vue特性当然也少不了。在md正文里面,可以直接使用 {{}} 进行一些处理,比如vue的模板语法
{{ 2 1 }} {{ i }} {{ $page }}
也可以使用 vue的组件语法,样式预处理器如scss、less,脚本样式,内置组件等等。不过由于初期使用,没有过多涉猎,不好瞎说。
Github站点部署
经过上面一大堆文件配置文件,安装文件摧残之后,进行文件打包生成静态文件,就可以进行站点发布了。当然你也可以自行购买空间、域名进行配置。配置好之后直接ftp把文件传上去就完事儿了。
这里用到的是Github里面的 Github Pages服务,可以放一些静态文件进行项目展示。打开翻了翻里面提供的一些模板,发现好多开源项目的文档介绍文件都是用的这个服务。
废话到这里。
第一步: 注册github账号,不赘述自行注册。
第二步: 新建库(New Repository),库名注意 <用户名>.github.io。其他选项默认,然后点击创建按钮 Create Repository
第三步: 根据提示,设置本地代码库与线上的库的绑定,上传代码。上传代码之前记得添加.gitignore文件,屏蔽一些无用的和敏感文件。
echo "# <用户名>.github.io" >> README.md git init git add README.md git commit -m "first commit" git remote add origin https://github.com/<用户名>/<用户名>.github.io.git git push -u origin master
第四部: 配置github pages。在库详情中 设置settings > 选项options > GitHub Pages 部分选择资源。设置后就可以使用 <用户名>.github.io 进行访问了。也可以设置下面的自定义域名Custom domain,把自己的二级域名使用CNAME别名解析到 <用户名>.github.io 上去,看着更好看。我就是这么搞的。
第四步: 就是进一步内容更新了,将编辑将打包的部分持续上传上去了。
正常编辑过程中是保存即所得的,内容编辑结束了才需要打包上传的。 到这一步我自己的折腾成两个不相关的库,发现两个库来回跳转。官方提供了一个方便的部署脚本,属于比较干净的那种。我这里直接修改成适合自己理解的,比较笨的一个。上传的时候直接执行下面的脚本就完成了源码库打包,上传,复制打包好的文件到发布库,然后进行更新上传的操作。
#!/usr/bin/env sh # 确保脚本抛出遇到的错误 set -e # 生成静态文件 npm run docs:build # 上传源码github git add -A git commit -m \'deploy\' git push # 复制站点文件 # 首先删除原来文件夹下的所有内容 rmdir --ignore-fail-on-non-empty G:/githubpages/docs # 复制打包好的文件 cp -avx "G:\vue\SSR\docs\.vuepress\dist" G:/githubpages/docs # 进入生成的文件夹 cd G:/githubpages/ # 如果是发布到自定义域名 # echo \'www.example.com\' > CNAME git add -A git commit -m \'deploy\' git push # 如果发布到 https://.github.io # git push -f git@github.com:/.github.io.git master # 如果发布到 https://.github.io/ # git push -f git@github.com:/.git master:gh-pages cd - # 最后刹车一下,不然刷刷也不知道刷了点儿啥 read -p "Press any key to continue." var
文末
到这里,就做了一个跟vue官方长一样的文档管理站点了。效果请点击文末的阅读原文或者查看更多了解。通过里面点击查看源码也可以看到发布在github上的源码。内容基本上都是跟着官方文档一步一步下来的。
欢迎鲜花和板砖,都是天天向上的动力。