亲宝软件园·资讯

展开

创建 VuePress + GithubPages + TravisCI 在线文档

田三番 人气:3
[TOC] > [最新博客链接](https://tsanfer.xyz/创建-vuepress-githubpages-travisci-在线文档) > [VuePress 在线文档链接_Github Pages](https://tsanfer.github.io/VuePress-GithubPages-TravisCI/) > **[VuePress 在线文档链接_博客服务器](https://tsanfer.xyz/VuePress-GithubPages-TravisCI/)(如果上面进不去,可以进这个,服务器在阿里云)** > [Github链接](https://github.com/Tsanfer/VuePress-GithubPages-TravisCI) ## 最终效果 ![](https://img2020.cnblogs.com/other/1394434/202003/1394434-20200322132421605-14027549.png) ## 思路 ### 总体 VuePress 在本地完成项目的源文件,推送至 Github 触发 Travis CI 自动构建目标文件,完成后自动部署到另一个 Github 分支,此分支作在线文档使用。 在Github上创建两个分支`master`和`gh-pages`,`master`用于上传源文件和触发 Travis CI 自动执行构建、部署脚本,`gh-pages`用于保存 Github Pages 的最终页面。 完成上述操作之后就只需修改文本源文件Markdown里面的内容,推送到Github。Travis CI 便可自动构建、部署,使其工作流程简化。 ### 过程 1. 在本地创建配置 VuePress 工程上传到`master`分支 2. 上传成功后触发 TravisCI 开始自动构建 3. 构建完成后将最终页面推送到`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密钥 ```shell $ 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密钥 测试一下密钥 ```shell ssh -T git@github.com ``` 设置Github账号的地址 ```shell 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" ``` 如果成功的话 ```shell Hi Tsanfer! You've successfully authenticated, but GitHub does not provide shell access. ``` 用SSH的方式克隆仓库到本地 ```shell # 选一个文件夹克隆仓库 # 比如家目录 cd ~ git clone git@github.com:{Username}/{Repo}.git # 比如 # cd ~ # git clone git@github.com:Tsanfer/VuePress-GithubPages-TravisCI.git ``` ```shell # 克隆完之后的目录 ~/VuePress-GithubPages-TravisCI/ ``` ## 配置VuePress ### 安装VuePress > 请确保你的 Node.js 版本 >= 8。 #### 安装yarn > 也可以安装npm ##### Debian / Ubuntu 在 Debian 或 Ubuntu 上,需要用yarn的 Debian 包仓库来安装 Yarn。 首先需要配置仓库: ```shell curl -sS https:/https://img.qb5200.com/download-x/dl.yarnpkg.comhttps://img.qb5200.com/download-x/debian/pubkey.gpg | sudo apt-key add - echo "deb https:/https://img.qb5200.com/download-x/dl.yarnpkg.comhttps://img.qb5200.com/download-x/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list ``` 更新库和下载yarn ```shell sudo apt-get update && sudo apt-get install yarn ``` 运行命令来测试 Yarn 是否安装: ```shell $ yarn --version 1.22.4 ``` ##### Windows 直接下安装包,然后在CMD或者Powershell里运行 ##### 更换国内的源 先看一下当前的源 ```shell $ yarn config get registry https://registry.yarnpkg.com ``` 更换阿里淘宝的源 ```shell yarn config set registry https://registry.npm.taobao.org ``` #### 安装VuePress ```shell # 先进入安装目录,就是刚刚克隆的仓库 cd ~/VuePress-GithubPages-TravisCI # 安装 sudo yarn global add vuepress # 或者:npm install -g vuepress ``` 然后试一下看是否安装成功 ```shell # 新建一个 markdown 文件 echo '# Hello VuePress!' > README.md # 开始写作 vuepress dev . ``` ```shell ℹ 「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生成的网页的地址 或者构建静态文件 ```bash # 构建静态文件 vuepress build . ``` 但会因为路径不对,网页的样式显示不出来 #### VuePress目录结构 官方给的结构 > VuePress 遵循 **“约定优于配置”** 的原则,推荐的目录结构如下: > > ```shell > . > ├── 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 > ``` 这里用到的结构 ```shell . ├── 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` 里加一些脚本和后面要用的依赖: ```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" } } ``` 加载依赖 ```shell yarn ``` 命令 ```bash yarn docs:dev # 或者:npm run docs:dev yarn docs:build # 或者:npm run docs:build ``` ### 页面的设置 #### 首页 `https://img.qb5200.com/download-x/docs/README.md` ```yaml --- 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 --- ``` #### 文档属性 `https://img.qb5200.com/download-x/docs/.vuepress/config.js` ```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' } //浏览器的标签栏的网页图标,基地址https://img.qb5200.com/download-x/docs/.vuepress/public ], ], } ``` #### markdown扩展 `https://img.qb5200.com/download-x/docs/.vuepress/config.js` ```js module.exports = { markdown: { lineNumbers: true, //是否在每个代码块的左侧显示行号 }, } ``` #### 默认主题设置 ##### 导航栏 `https://img.qb5200.com/download-x/docs/.vuepress/config.js` ```js module.exports = { themeConfig: { nav: [ //链接页面链接的根地址为https://img.qb5200.com/download-x/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' }, ], }, } ``` ##### 侧边栏 `https://img.qb5200.com/download-x/docs/.vuepress/config.js` ```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仓库 `https://img.qb5200.com/download-x/docs/.vuepress/config.js` ```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 上编辑此页', }, } ``` ##### 其他 `https://img.qb5200.com/download-x/docs/.vuepress/config.js` ```js module.exports = { themeConfig: { smoothScroll: true, //页面滚动效果 lastUpdated: '最后更新', // string | boolean }, } ``` #### 插件 `https://img.qb5200.com/download-x/docs/.vuepress/config.js` ```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所有内容 ```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' } //浏览器的标签栏的网页图标,基地址https://img.qb5200.com/download-x/docs/.vuepress/public ], ], //markdown扩展 markdown: { lineNumbers: true, //是否在每个代码块的左侧显示行号 }, //默认主题配置 themeConfig: { //导航栏 nav: [ //链接页面链接的根地址为https://img.qb5200.com/download-x/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分支 ![](https://img2020.cnblogs.com/other/1394434/202003/1394434-20200322132421898-959230046.png) 这时Github已经自动部署gh-pages分支为Github pages的生成源 ![](https://img2020.cnblogs.com/other/1394434/202003/1394434-20200322132422190-1316268230.png) ### deploy.sh部署文件 每当 Github 仓库更新时,会触发 Travis CI 执行 `deploy.sh` 脚本 创建一个如下的 `deploy.sh` 文件(请自行判断去掉高亮行的注释): 在项目根目录下创建 ```shell . ├── 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 自动部署文件 ``` ```bash #!/usr/bin/env sh # 确保脚本抛出遇到的错误 set -e # 生成静态文件 yarn docs:build # 进入生成的文件夹 cd docs/.vuepresshttps://img.qb5200.com/download-x/dist # 如果是发布到自定义域名 # echo 'www.example.com' > CNAME git init git add -A git commit -m 'deploy' # 如果发布到 https://

加载全部内容

相关教程
猜你喜欢
用户评论