使用vuepress搭建GitHub pages静态博客页面

vuepress官网 vuepress是尤大开发来写文档的静态页面。能够用Markdown 语法，而且也可使用vue模块化的方式开发页面。

vuepress-theme-reco 是另外的开发者开发的 vuepress主题。本文将介绍依赖这个主题，构建GitHub pages静态博客的详细过程

 

提早说明：本过程比较详细，至关于手把手的教，针对于不熟悉vuepress的人介绍的，大佬不喜勿喷。

 

第一步：新建一个GitHub仓库

1. 仓库名随便取，不用以 username.github.io 这种方式。

2. 仓库不要选 private ，否则不能发布为GitHub pages。

3. 选择添加一个README文件，虽然没什么做用，由于后面要覆盖。

 

第二步：克隆新建仓库的git地址，初始化项目

　　1.  cmd 中执行 git clone 刚才复制的 git 地址 

　　2.  推荐使用yarn 来进行安装，否则有可能会有其它不可未知的错误 

　　3.  执行 yarn global add @vuepress-reco/theme-cli  安装全局主题脚手架。安装完成后：

 

 　　4. 执行  theme-cli init  而后会提示你选择一些东西：

注意：最后一个让选择主页是什么样式的时候，有三种主题 blog，doc，afternoon-grocery。

我三个都试了一下，

• blog与doc感受基本上同样
• afternoon-grocery 目录和vuepress标准的目录一致，文章都放到view文件夹里
• 和前两个相比，多了选择颜色主题的功能（并不是明暗）；可是首页右边分类 我的认为没有 blog或者doc的好看。
• 还多了个全屏的功能　

因此我选择了blog 主题。怎么选择就看你本身了。 

注意：若是 yarn 过程出现错误，好比相似的：

 须要先把 yarn.lock 删掉 再从新安装。那里面的库路径有问题。 

　　5. 若是是安装的blog或者doc，那么安装完成以后，若是package.json中的dev项有  --open --host localhost ，要改为 vuepress dev . 否则运行不起。注意有个点，不过这个点无关紧要。 

　　6. 改完以后，执行 yarn dev  等待编译完成，就能看到本地运行的 url 地址，打开便可看到页面了

 

第三步：推到GitHub 自动转换成GitHub pages。步骤是blog主题

在上传代码到GitHub以前，须要改一些代码，否则上传上去 在GitHub pages里显示的就是404

1. 修改代码，push代码

（1） 根目录 .vuepress 下的config.js 中的dest项去掉，使用默认的打包后的路径，及： .vuepress/dist 。不过这项不重要，用自定义的也能够，后面新建脚本的时候，路径对上便可

（2） 在config.js 中 和刚才去掉的dest同级的地方加上  “base”:”/Blogs/”   这个Blogs 不能乱取，必须是你当前GitHub仓库名，而且先后都有 / 斜杠！！！否则打包后静态资源路径会有问题。

（3） 推送代码到GitHub仓库中：

git add . 
git commit -m’init’
git push

2. 新建分支

（1） 这时候，能够在GitHub的仓库中，看到最新提交的代码，而后切换到setting选项

 

（2） 下拉到下面 GitHub Pages 项，若是这时候Soure里面是none，切换成master。点击save便可。

 

（3） 页面自动刷新后，再拉到这个地方，就能看到已经自动发布好了

 

（4） 可是这时候点击连接，打开的倒是404，这是什么缘由呢？仔细看404页面提示的缘由，原来是GitHub pages 必需要有index.html，因为vuepress是Markdown语法没有html，因此显示不了。

（5） 咱们知道打包以后的静态文件项目就有html文件，因此只须要用另外的分支用来存放打包后的静态文件，html文件符合GitHub pages的规则，这样就能正确的显示了。

（6） GitHub上 点击master分支，输入新分支名并create branch 这时候会自动切换到blogs分支上，而且内容和master同样。blogs分支名随便取，只要后面发布的时候，脚本里面的分支名对应上便可

 

 3.  新建脚本，自动推送到blog分支

（1）本地master分支新建一个 deploy.sh文件 名字随意，后面执行的时候名称一致便可，后缀是shell的后缀名 .sh ;

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
yarn build

# 进入生成的文件夹，这里是默认的路径，能够自定义
cd .vuepress/dist

# 若是是发布到自定义域名
# echo 'www.isunbeam.cn' > CNAME

git init
git add -A
git commit -m 'deploy'

# 若是发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:<BranchName>
git push -f git@github.com:isunbeam/Blogs.git master:blogs

cd -

# 最后发布的时候执行 bash deploy.sh

（2） 注意 git push 的时候，分支名必定要和GitHub上新建的分支名同样。

（3） 执行  bash deploy.sh  。执行完成，到GitHub的仓库里，切换到setting，而后拉到GitHub Pages 这时候已经发布了，可是打开连接仍是404，缘由就是做为github pages的分支不正确，默认是master，下面切换成blogs，点击save便可

（4）等待页面刷新后，再次打开便可看到。若是仍是没有，强制刷新一下 ctrl + f5。可能有缓存。

 

到此，你的博客已经正常发布到GitHub pages了。\(^o^)/~

 

下面介绍怎么发表博客：

先说说目录：该目录是选择的blog主题

 

（1） dist 是打包后的静态文件

（2） public 是存放图片等内容的

（3） config.js 是最重要的，主题的配置项

（4） blogs 是发表博客文章的地方，第二级目录表示分类，第三级目录表示年份，应该是用来作时间线用的，应该不能改为其它的内容。而后年份里面就是真正的博客页面，是 xxx.md 通常是以时间来命名文件的。

　　好比我如今要新建一个博客：

　　（a）在blogs 里新建一个 2020 名称的文件夹，里面再新建一个 090801.md  的md文档，01表示0908号第一篇，02表示第二篇依此类推。写好了以后保存，直接刷新页面或者重启项目，便可看到新增的博客。

　　 （b）在写的 md 里面的 date 日期项，感受不能精确到时分秒，否则时间轴 文章的日期就会多一天。好比date 是写的 2020-09-08 18:08:08 ，时间轴中就会被解析成 2020年的9月9号发表的。因此建议不用时分秒。

　　 （c）若是想写的博客有摘要，在正文前加上  <!-- more -->  这以上的代码就会被解析成摘要。相似下面的文章摘要

 

（5） docs 是写文档的地方，至关因而 左边是大标题，右边是大标题对应的描述内容。第二级目录表示文档分类，和大标题的第一个内容，里面的README.md就是内容详情。而后里面的其他 .md 文档是另外的大标题的详情，而后要想新增后生效

　　好比我如今要新建一个文档说明：

　　（a）docs下面新建一个文件夹testdoc，在这个文件夹里再新建一个READEME.md做为大标题1的内容页，再建一个test1.md表示大标题2的内容页

　　（b）每一个内容页里随意编写内容，可是顶部须要有Front Matter配置，而后再写md文档。写好后，在 config.js 中去配置

　　（c）Docs配置项的items里面加上 

{
    "text": "test",
    "link": "/docs/testdoc/"
}

　　（d）sidebar的配置项里加上 。数组第一项要为空

"/docs/testdoc/": [
    "",
    "test1"
]

（6） 配置完以后，会自动构建代码，而后强制刷新一下页面 ctrl + f5 。若是未生效，就从新启动一下项目就能够看到最新的文档了。

 

自定义域名

 若是有人还想用本身的域名，不用 <username>.github.io/Blogs/ 这种域名，那么能够按下面的步骤来实现

第一步：把  config.js 中的 base 项注释掉，这样默认静态文件根目录是  / ，否则发布以后会出现静态文件路径不正确的问题

第二步：把 deploy.sh 的 echo 'xxx'  > CNAME 这一项放开，而且 把 xxx 换成 本身的域名，好比我是 www.isunbeam.cn 就是 echo 'www.isunbeam.cn' > CNAME

第三步：保存。而后从新构建项目 bash deploy.sh 便可

第四步：域名解析

　　（1） 新建一个 主机值为www，记录类型为 CNAME，记录值为 <username>.github.io 的解析

第五步： 在 GitHub 仓库的 setting 中，GitHub pages选项里 有一个Custom domain，把它更新为你刚才 CNAME解析的   www.xxx.xx 。点击save便可。

 

到此，自定义域名的静态博客就完整搭建成功了，其他的就剩看 vuepress-theme-reco的文档啦。O(∩_∩)O哈哈~

若是有想本身折腾的，也能够本身用组件的方式，自定义主题。(#^.^#)