松鼠乐园 松鼠乐园
  • 注册
  • 登录
  • 首页
  • 快捷入口
    • Vue
    • Tensorflow
    • Springboot
    • 语言类
      • CSS
      • ES5
      • ES6
      • Go
      • Java
      • Javascript
    • 工具类
      • Git
      • 工具推荐
    • 服务器&运维
      • Centos
      • Docker
      • Linux
      • Mac
      • MySQL
      • Nginx
      • Redis
      • Windows
    • 资源类
      • 论文
      • 书籍推荐
      • 后端资源
      • 前端资源
      • html网页模板
      • 代码
    • 性能优化
    • 测试
  • 重大新闻
  • 人工智能
  • 开源项目
  • Vue2.0从零开始
  • 广场
首页 › Vue › Vue进阶篇-VuePress文档管理安装及Github免费建站

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

迦娜王
1年前Vue
2,358 0 5
Vue进阶篇-VuePress文档管理安装及Github免费建站

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


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文档里面没有的,而且感觉还挺有用的拓展。

  1. vuepress里面默认是会给所有的标题都加上锚链接,h1-h6,并且会根据标题来生成目录。
  2. 直接在内容中使用 [[toc]] 会生成自动目录。
  3. 代码高亮,在代码开始标记后进行“` 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上的源码。内容基本上都是跟着官方文档一步一步下来的。

欢迎鲜花和板砖,都是天天向上的动力。

5
前端 Vue.js 快速开发微信小程序,基于 Vue 的小程
上一篇
从VUE到前端的粗浅理解
下一篇
评论 (0)

请登录以参与评论。

现在登录
聚合文章
在Gitee收获近 5k Star,更新后的Vue版RuoYi有哪些新变化?
2月前
vue3.x reactive、effect、computed、watch依赖关系及实现原理
2月前
Vue 3 新特性:在 Composition API 中使用 CSS Modules
2月前
新手必看的前端项目去中心化和模块化思想
2月前
标签
AI AI项目 css docker Drone Elaticsearch es5 es6 Geometry Go gru java Javascript jenkins lstm mysql mysql优化 mysql地理位置索引 mysql索引 mysql规范 mysql设计 mysql配置文件 mysql面试题 mysql高可用 nginx Redis redis性能 rnn SpringBoot Tensorflow tensorflow2.0 UI设计 vue vue3.0 vue原理 whistle ZooKeeper 开源项目 抓包工具 日志输出 机器学习 深度学习 神经网络 论文 面试题
5
相关文章
在Gitee收获近 5k Star,更新后的Vue版RuoYi有哪些新变化?
vue3.x reactive、effect、computed、watch依赖关系及实现原理
Vue 3 新特性:在 Composition API 中使用 CSS Modules
新手必看的前端项目去中心化和模块化思想
松鼠乐园

资源整合,创造价值

小伙伴
墨魇博客 无同创意
目录
重大新闻 Centos CSS Docker ES5 ES6 Go Java Javascript Linux Mac MySQL Nginx Redis Springboot Tensorflow Vue Vue2.x从零开始 Windows 书籍推荐 人工智能 前端资源 后端资源 壁纸 开源项目 测试 论文
Copyright © 2018-2021 松鼠乐园. Designed by nicetheme. 浙ICP备15039601号-4
  • 重大新闻
  • Centos
  • CSS
  • Docker
  • ES5
  • ES6
  • Go
  • Java
  • Javascript
  • Linux
  • Mac
  • MySQL
  • Nginx
  • Redis
  • Springboot
  • Tensorflow
  • Vue
  • Vue2.x从零开始
  • Windows
  • 书籍推荐
  • 人工智能
  • 前端资源
  • 后端资源
  • 壁纸
  • 开源项目
  • 测试
  • 论文
热门搜索
  • jetson nano
  • vue
  • java
  • mysql
  • 人工智能
  • 人脸识别
迦娜王
坚持才有希望
1224 文章
33 评论
233 喜欢
  • 5
  • 0
  • Top