欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

创建 VuePress + GithubPages + TravisCI 在线文档

程序员文章站 2022-03-25 17:37:21
[TOC] "最新博客链接" "VuePress 在线文档链接_Github Pages" "VuePress 在线文档链接_博客服务器" (如果上面进不去,可以进这个,服务器在阿里云) "Github链接" 最终效果 "最终效果链接" 思路 总体 VuePress 在本地完成项目的源文件,推送至 ......

最新博客链接

vuepress 在线文档链接_github pages

vuepress 在线文档链接_博客服务器(如果上面进不去,可以进这个,服务器在阿里云)

github链接

最终效果

最终效果链接

创建 VuePress + GithubPages + TravisCI 在线文档

思路

总体

vuepress 在本地完成项目的源文件,推送至 github 触发 travis ci 自动构建目标文件,完成后自动部署到另一个 github 分支,此分支作在线文档使用。

在github上创建两个分支mastergh-pagesmaster用于上传源文件和触发 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密钥
$ 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分支

创建 VuePress + GithubPages + TravisCI 在线文档

这时github已经自动部署gh-pages分支为github pages的生成源

创建 VuePress + GithubPages + TravisCI 在线文档

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地址

创建 VuePress + GithubPages + TravisCI 在线文档

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 名字随便写,权限不清楚的可以全部选上,也可以参考我下面的配置

创建 VuePress + GithubPages + TravisCI 在线文档

创建 VuePress + GithubPages + TravisCI 在线文档

创建 VuePress + GithubPages + TravisCI 在线文档

下面的口令只出现一次,需及时保存

创建 VuePress + GithubPages + TravisCI 在线文档

travis ci 绑定和配置

绑定 github 账号

在 travis ci 里面 settings ---> repositories 点击 manage repositories on github

创建 VuePress + GithubPages + TravisCI 在线文档

选择给权限的仓库,为了方便也可以把所有仓库的权限都给了

创建 VuePress + GithubPages + TravisCI 在线文档

添加 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****

创建 VuePress + GithubPages + TravisCI 在线文档

推送到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 触发成功,构建没有问题的话就完成了

创建 VuePress + GithubPages + TravisCI 在线文档

本文由tsanfer's blog 发布!