创建 VuePress + GithubPages + TravisCI 在线文档
vuepress 在线文档链接_博客服务器(如果上面进不去,可以进这个,服务器在阿里云)
最终效果
思路
总体
vuepress 在本地完成项目的源文件,推送至 github 触发 travis ci 自动构建目标文件,完成后自动部署到另一个 github 分支,此分支作在线文档使用。
在github上创建两个分支master
和gh-pages
,master
用于上传源文件和触发 travis ci 自动执行构建、部署脚本,gh-pages
用于保存 github pages 的最终页面。
完成上述操作之后就只需修改文本源文件markdown里面的内容,推送到github。travis ci 便可自动构建、部署,使其工作流程简化。
过程
- 在本地创建配置 vuepress 工程上传到
master
分支 - 上传成功后触发 travisci 开始自动构建
- 构建完成后将最终页面推送到
gh-pages
分支
用到的东西
- ssh密钥链接github
- vuepress目录文件结构
- vuepress配置文件
- travisci自动构建配置文件
相关
-
vuepress:
每一个由 vuepress 生成的页面都带有预渲染好的 html,也因此具有非常好的加载性能和搜索引擎优化(seo)。同时,一旦页面被加载,vue 将接管这些静态内容,并将其转换成一个完整的单页应用(spa),其他的页面则会只在用户浏览到的时候才按需加载。
-
github pages:
您可以使用 github pages 直接从 github 仓库托管关于自己、您的组织或您的项目的站点
github pages 是一项静态站点托管服务,它直接从 github 上的仓库获取 html、css 和 javascript 文件,(可选)通过构建过程运行文件,然后发布网站。
-
travis ci
travis ci 提供的是持续集成服务(continuous integration,简称 ci)。它绑定 github 上面的项目,只要有新的代码,就会自动抓取。然后,提供一个运行环境,执行测试,完成构建,还能部署到服务器。
持续集成指的是只要代码有变更,就自动运行构建和测试,反馈运行结果。确保符合预期以后,再将新代码"集成"到主干。
持续集成的好处在于,每次代码的小幅变更,就能看到运行结果,从而不断累积小的变更,而不是在开发周期结束时,一下子合并一大块代码。
创建github仓库
创建github仓库
在github官网上创建一个新的仓库(我仓库的名字叫vuepress-githubpages-travisci
)
ssh密钥链接github
生成ssh密钥
$ ssh-keygen generating public/private rsa key pair. # 输入准备存放密钥的位置,公钥和私钥放在同一个文件夹 enter file in which to save the key (/home/tsanfer/.ssh/id_rsa): /home/tsanfer/.ssh/test_key # 输入口令,不需要口令就直接回车,这里我不需要口令,直接回车 enter passphrase (empty for no passphrase): # 确认口令,跟上面一样 enter same passphrase again: # 显示私钥位置 your identification has been saved in /home/tsanfer/.ssh/test_key. # 显示公钥位置,下一步需要添加公钥到github中 your public key has been saved in /home/tsanfer/.ssh/test_key.pub.
github添加ssh密钥
在github头像旁边的菜单中 settings --> ssh and gpg keys --> ssh keys 中的右上角点击 new ssh key
下面要填入信息:
- title:随便填
- key:公钥文件里的所有内容(
~/.ssh/test_key.pub
)
测试ssh密钥
测试一下密钥
ssh -t git@github.com
设置github账号的地址
git config --global user.name "username" git config --global user.email "useremail" # 比如 git config --global user.name "tsanfer" git config --global user.email "a1124851454@gmail.com"
如果成功的话
hi tsanfer! you've successfully authenticated, but github does not provide shell access.
用ssh的方式克隆仓库到本地
# 选一个文件夹克隆仓库 # 比如家目录 cd ~ git clone git@github.com:{username}/{repo}.git # 比如 # cd ~ # git clone git@github.com:tsanfer/vuepress-githubpages-travisci.git
# 克隆完之后的目录 ~/vuepress-githubpages-travisci/
配置vuepress
安装vuepress
请确保你的 node.js 版本 >= 8。
安装yarn
也可以安装npm
debian / ubuntu
在 debian 或 ubuntu 上,需要用yarn的 debian 包仓库来安装 yarn。 首先需要配置仓库:
curl -ss https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
更新库和下载yarn
sudo apt-get update && sudo apt-get install yarn
运行命令来测试 yarn 是否安装:
$ yarn --version 1.22.4
windows
直接下安装包,然后在cmd或者powershell里运行
更换国内的源
先看一下当前的源
$ yarn config get registry https://registry.yarnpkg.com
更换阿里淘宝的源
yarn config set registry https://registry.npm.taobao.org
安装vuepress
# 先进入安装目录,就是刚刚克隆的仓库 cd ~/vuepress-githubpages-travisci # 安装 sudo yarn global add vuepress # 或者:npm install -g vuepress
然后试一下看是否安装成功
# 新建一个 markdown 文件 echo '# hello vuepress!' > readme.md # 开始写作 vuepress dev .
ℹ 「wds」: project is running at http://0.0.0.0:8081/ ℹ 「wds」: webpack output is served from / ℹ 「wds」: content not from webpack is served from /mnt/k/git_bash/vuepress-githubpages-travisci/.vuepress/public ℹ 「wds」: 404s will fallback to /index.html success [00:00:17] build 471ee0 finished in 8465 ms! > vuepress dev server listening at http://localhost:8081/ # 生成的地址 http://localhost:8081/
用浏览器打开vuepress生成的网页的地址
或者构建静态文件
# 构建静态文件 vuepress build .
但会因为路径不对,网页的样式显示不出来
vuepress目录结构
官方给的结构
vuepress 遵循 “约定优于配置” 的原则,推荐的目录结构如下:
. ├── 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
这里用到的结构
. ├── readme.md // github项目展示文件 ├── docs //vuepress项目根目录 │ ├── .vuepress //存放核心内容的文件夹 │ │ ├── public //存放静态文件,如图片等 │ │ └── config.js //设定顶部导航栏、侧边导航栏等项目配置的核心文件 │ ├── pages //存放markdown页面的文件 │ ├── readme.md //vuepress首页展示用的markdown文件 ├── deploy.sh //用于编写travisci上传、发布的脚本文件 ├── lisense //许可证文件 ├── package.json //node.js项目描述文件 └── .travis.yml //travis ci 自动部署文件
配置依赖和脚本
配置package.json
在 package.json
里加一些脚本和后面要用的依赖:
{ "dependencies": { "@vuepress/plugin-active-header-links": "^1.3.1", "@vuepress/plugin-medium-zoom": "^1.3.1", "@vuepress/plugin-nprogress": "^1.3.1", "@vuepress/plugin-back-to-top": "^1.3.1", "vuepress": "^1.3.1" }, "scripts": { "docs:build": "vuepress build docs", "docs:dev": "vuepress dev docs" } }
加载依赖
yarn
命令
yarn docs:dev # 或者:npm run docs:dev yarn docs:build # 或者:npm run docs:build
页面的设置
首页
/docs/readme.md
--- home: true heroimage: https://cdn-image.tsanfer.xyz/img/vuepress_githubpages_travisci.svg actiontext: 快速上手 → actionlink: /pages/思路.md features: - title: 简洁至上 details: 以 markdown 为中心的项目结构,以最少的配置帮助你专注于写作。 - title: vue驱动 details: 享受 vue + webpack 的开发体验,在 markdown 中使用 vue 组件,同时可以使用 vue 来开发自定义主题。 - title: 高性能 details: vuepress 为每个页面预渲染生成静态的 html,同时在页面被加载的时候,将作为 spa 运行。 footer: mit licensed | copyright © 2020 tsanfer ---
文档属性
/docs/.vuepress/config.js
module.exports = { base: '/vuepress-githubpages-travisci/', //目录根地址,应与github仓库名字相同 title: 'vuepress + githubpages + travisci', // 显示在左上角的网页名称以及首页在浏览器标签显示的title名称 description: '创建 vuepress + githubpages + travisci 在线文档', // meta 中的描述文字,用于seo head: [ ['link', { rel: 'icon', href: '/gamepad_game_128px.ico' } //浏览器的标签栏的网页图标,基地址/docs/.vuepress/public ], ], }
markdown扩展
/docs/.vuepress/config.js
module.exports = { markdown: { linenumbers: true, //是否在每个代码块的左侧显示行号 }, }
默认主题设置
导航栏
/docs/.vuepress/config.js
module.exports = { themeconfig: { nav: [ //链接页面链接的根地址为/docs { text: '思路', link: '/pages/思路.md' }, { text: '创建github仓库', link: '/pages/创建github仓库.md' }, { text: '配置vuepress', link: '/pages/配置vuepress.md' }, { text: '创建分支和github pages', link: '/pages/创建分支和github pages.md' }, { text: 'travisci生成和发布', link: '/pages/travisci生成和发布.md' }, { text: '博客', link: 'https://tsanfer.xyz' }, ], }, }
侧边栏
/docs/.vuepress/config.js
module.exports = { themeconfig: { sidebardepth: 2, //侧边栏深度 sidebar: [ ['/pages/思路.md', '思路'], ['/pages/创建github仓库.md', '创建github仓库'], ['/pages/配置vuepress.md', '配置vuepress'], ['/pages/创建分支和github pages.md', '创建分支和github pages'], ['/pages/travisci生成和发布.md', 'travisci生成和发布'], ], }, }
git仓库
/docs/.vuepress/config.js
module.exports = { themeconfig: { // 假定是 github. 同时也可以是一个完整的 gitlab url repo: 'tsanfer/vuepress-githubpages-travisci', // 自定义仓库链接文字。默认从 `themeconfig.repo` 中自动推断为 // "github"/"gitlab"/"bitbucket" 其中之一,或是 "source"。 repolabel: 'github', // 以下为可选的编辑链接选项 // 假如文档不是放在仓库的根目录下: docsdir: 'docs/pages', // 假如文档放在一个特定的分支下: docsbranch: 'master', // 默认是 false, 设置为 true 来启用 editlinks: true, // 默认为 "edit this page" editlinktext: '在 github 上编辑此页', }, }
其他
/docs/.vuepress/config.js
module.exports = { themeconfig: { smoothscroll: true, //页面滚动效果 lastupdated: '最后更新', // string | boolean }, }
插件
/docs/.vuepress/config.js
module.exports = { plugins: [ '@vuepress/medium-zoom', //zooming images like medium(页面弹框居中显示) '@vuepress/nprogress', //网页加载进度条 '@vuepress/plugin-back-to-top', //返回页面顶部按钮 ] }
到这里其实已经完成配置了,可以执行
yarn docs:dev
来浏览配置的页面,只是由于没有对应的 md 文件,打开的链接都会404
config.js所有内容
module.exports = { base: '/vuepress-githubpages-travisci/', //目录根地址,应与github仓库名字相同 title: 'vuepress + githubpages + travisci', // 显示在左上角的网页名称以及首页在浏览器标签显示的title名称 description: '创建 vuepress + githubpages + travisci 在线文档', // meta 中的描述文字,用于seo head: [ ['link', { rel: 'icon', href: '/gamepad_game_128px.ico' } //浏览器的标签栏的网页图标,基地址/docs/.vuepress/public ], ], //markdown扩展 markdown: { linenumbers: true, //是否在每个代码块的左侧显示行号 }, //默认主题配置 themeconfig: { //导航栏 nav: [ //链接页面链接的根地址为/docs { text: '思路', link: '/pages/思路.md' }, { text: '创建github仓库', link: '/pages/创建github仓库.md' }, { text: '配置vuepress', link: '/pages/配置vuepress.md' }, { text: 'travisci生成和发布', link: '/pages/travisci生成和发布.md' }, { text: '博客', link: 'https://tsanfer.xyz' }, ], sidebardepth: 2, //侧边栏深度 //侧边栏 sidebar: [ ['/pages/思路.md', '思路'], ['/pages/创建github仓库.md', '创建github仓库'], ['/pages/配置vuepress.md', '配置vuepress'], ['/pages/travisci生成和发布.md', 'travisci生成和发布'], ], // 假定是 github. 同时也可以是一个完整的 gitlab url repo: 'tsanfer/vuepress-githubpages-travisci', // 自定义仓库链接文字。默认从 `themeconfig.repo` 中自动推断为 // "github"/"gitlab"/"bitbucket" 其中之一,或是 "source"。 repolabel: 'github', // 以下为可选的编辑链接选项 // 假如文档不是放在仓库的根目录下: docsdir: 'docs/pages', // 假如文档放在一个特定的分支下: docsbranch: 'master', // 默认是 false, 设置为 true 来启用 editlinks: true, // 默认为 "edit this page" editlinktext: '在 github 上编辑此页', smoothscroll: true, //页面滚动效果 lastupdated: '最后更新', // string | boolean }, //插件 plugins: [ '@vuepress/medium-zoom', //zooming images like medium(页面弹框居中显示) '@vuepress/nprogress', //网页加载进度条 '@vuepress/plugin-back-to-top', //返回页面顶部按钮 ] }
travisci生成和发布
创建gh-pages分支
这时github已经自动部署gh-pages分支为github pages的生成源
deploy.sh部署文件
每当 github 仓库更新时,会触发 travis ci 执行 deploy.sh
脚本
创建一个如下的 deploy.sh
文件(请自行判断去掉高亮行的注释):
在项目根目录下创建
. ├── readme.md // github项目展示文件 ├── docs //vuepress项目根目录 │ ├── .vuepress //存放核心内容的文件夹 │ │ ├── public //存放静态文件,如图片等 │ │ └── config.js //设定顶部导航栏、侧边导航栏等项目配置的核心文件 │ ├── pages //存放markdown页面的文件 │ ├── readme.md //vuepress首页展示用的markdown文件 ├── deploy.sh //用于编写travisci上传、发布的脚本文件 ├── lisense //许可证文件 ├── package.json //node.js项目描述文件 └── .travis.yml //travis ci 自动部署文件
#!/usr/bin/env sh # 确保脚本抛出遇到的错误 set -e # 生成静态文件 yarn 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 # 比如 # git push -f git@github.com:tsanfer/vuepress-githubpages-travisci.git master:gh-pages cd -
上面的 git 地址其实就是仓库的ssh地址
travis ci 部署文件
在项目的根目录创建一个名为 .travis.yml
的文件
. ├── readme.md // github项目展示文件 ├── docs //vuepress项目根目录 │ ├── .vuepress //存放核心内容的文件夹 │ │ ├── public //存放静态文件,如图片等 │ │ └── config.js //设定顶部导航栏、侧边导航栏等项目配置的核心文件 │ ├── pages //存放markdown页面的文件 │ ├── readme.md //vuepress首页展示用的markdown文件 ├── deploy.sh //用于编写travisci上传、发布的脚本文件 ├── lisense //许可证文件 ├── package.json //node.js项目描述文件 └── .travis.yml //travis ci 自动部署文件
language: node_js node_js: - lts/* install: - yarn install # npm ci script: - yarn docs:build # npm run docs:build deploy: provider: pages skip_cleanup: true local_dir: docs/.vuepress/dist github_token: $github_token # 在 github 中生成,用于允许 travis 向你的仓库推送代码。在 travis 的项目设置页面进行配置,设置为 secure variable keep_history: true on: branch: master #这里指的是部署前的源文件分支
上面的 github_token 需要在 github 上生成
生成和使用 token
生成token
在 settings --> developer settings --> personal access tokens 右上角 generate new toekn 生成新token 名字随便写,权限不清楚的可以全部选上,也可以参考我下面的配置
下面的口令只出现一次,需及时保存
travis ci 绑定和配置
绑定 github 账号
在 travis ci 里面 settings ---> repositories 点击 manage repositories on github
选择给权限的仓库,为了方便也可以把所有仓库的权限都给了
添加 token
在项目的 settings --> environment variables 中输入 token
language: node_js node_js: - lts/* install: - yarn install # npm ci script: - yarn docs:build # npm run docs:build deploy: provider: pages skip_cleanup: true local_dir: docs/.vuepress/dist github_token: $github_token # 在 github 中生成,用于允许 travis 向你的仓库推送代码。在 travis 的项目设置页面进行配置,设置为 secure variable keep_history: true on: branch: master #这里指的是部署前的源文件分支
- name : github_token (刚刚的
github_token: $github_token
这个变量) - value : ****刚刚的 token****
推送到github
git add . git commit -m '初步完成' git push -f git@github.com:{username}/{repo}.git master # 比如 # git push -f git@github.com:tsanfer/vuepress-githubpages-travisci.git master
完成
如果没有 travis ci 触发成功,构建没有问题的话就完成了
本文由tsanfer's blog 发布!
上一篇: Mac Go 环境变量配置
下一篇: 用Python来做一个屏幕录制工具