利用GitHub Pages建立项目或个人网站

关于GitHub Pages建站的文章我以前写过，不过，写的比较乱，今天整理了一下。

背景

为了更好地学习和记录自己的前端经历，搭建一个便捷、稳定的个人站点挺有必要的；而通过GitHub Pages来展示自己的作品，更是不错的选择。

注意：需要保证已经安装好git并且已经关联到git远程平台账户

搭建项目的展示页面

打开git shell，创建一个名为gh-pages的分支，GitHub Pages默认为这个分支创建页面
```
git checkout --orphan gh-pages
```
将项目的展示页面文件放在项目仓库的gh-pages分支的根目录下，并且命名为index.html，必须以html为扩展名。
- [x] Done! 自此，即可通过http://userName.github.io/repoName访问你的项目demo页面了。

补充：

自2016年6月开始，部署在GitHub Pages上的站点开始支持https协议GitHub Blog
自2016年8月开始，GitHub Pages开始支持master分支创建页面GitHub Blog
搭建个人网站

因为GitHub Pages上托管的页面都是静态页面，所有有服务器响应需求的页面无法实现。但是可以通过插入第三方代码来实现，诸如评论、分享、代码示例等动态的木块。

GitHub Pages官方是推荐使用jekyll来部署个人网站的，而比较简单上手的则是hexo，各有其优点和缺点

对比	jekyll	hexo
文档	只有英文	多语言，有中文
操作	需要手动push到GitHub	文章模板，生成，部署，自动push
自定义	结构清晰，较少的说明，也能理解某些功能的作用和文件位置，适合深入自定义	适合拿现有的模板直接用，但是新手自定义有难度
功能	插件多，功能完整，但略有bug	有更多更能待补充，比如post相对引用
安装	因为需要ruby，在大陆可能会有网络限制	需要node，大陆的网络环境似乎没问题

使用jekyll

安装ruby 在Windows下，从 http://rubyinstaller.org/downloads/ 下载rubyinstaller.exe和`DevKit ，两个要对应版本，且对应操作系统。执行rubyinstaller.exe，安装ruby。将DevKit执行，并解到一个指定命名文件夹，如：RubyDevKit 管理员权限打开cmd/PowerShell
```
ruby dk.rb init
dk.rb install
```
从 https://rubygems.org/pages/download/ 下载RubyGems，解压缩出来的文件夹，如：rubygems 管理员权限打开cmd/PowerShell
```
cd rubygems
ruby setup.rb
```
在Ubuntu下，安装ruby比较简单，可参考我的另一篇文章
```
gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
curl -L https://get.rvm.io | bash -s stable --autolibs=enabled --ruby
sudo apt-get install libgdbm-dev libncurses5-dev automake libtool bison libffi-dev
source ~/.rvm/scripts/rvm
```
配置ruby 由于国内网络受限，可能需要修改ruby的源为国内的镜像：淘宝镜像(https://ruby.taobao.org/)或者ruby中国镜像(https://gems.ruby-china.org/)。

依次执行以下命令，在Ubuntu和Windows下都如此，以下如未特别说明，命令都是两平台均适用
```
gem sources --add https://ruby.taobao.org/ --remove https://rubygems.org/
gem sources -l
```
在Windows下，如果出现证书失败，就去下载一个证书
```
curl http://curl.haxx.se/ca/cacert.pem -o cacert.pem
```
将下载的cacert.pem移到ruby安装目录的/bin这个目录下，并且在系统环境变量中新建SSL_CERT_FILE，值为刚才的/bin目录的绝对路径，管理员权限打开cmd/PowerShell
```
SETX /M SSL_CERT_FILE "/bin目录的绝对路径"
```
bundler是一款ruby工具，可以通过配置Gemfile文件来快速安装gems包或者解决已安装包的依赖。
```
gem install bundler
```
在Windows下，如果网络环境不允许，可以选择不安装bundler，或者安装虚拟机VirtualBox。如果连ruby安装都困难可以选择使用chocolatey来装jekyll。

安装jekyll

gem install jekyll

创建一个名为Gemfile的文件，无扩展名，添加如下行

source 'https://rubygems.org'
gem 'github-pages', group: :jekyll-plugins

然后在需要的时候就可以执行以下命令

bundle install # 自动安装gems包和依赖
bundle update  # 更新gems包依赖
bundle exec jekyll build # 执行jekyll build，常用于解决一些jekyll的依赖等问题
bundle exec jekyll serve # 执行jekyll serve，常用于解决一些jekyll的依赖等问题

常用jekyll命令

jekyll new <dir>               # 初始化一个站点目录
jekyll build -s <dir> -d <dir> # 生成编译后的静态站点文件
jekyll serve                   # 用于本地预览和调试，地址是127.0.0.1:4000

建立站点仓库有两种选择：一是自己从零开始一步一步建站，二是直接使用别人的模板

自己建站

jekyll new blog
cd blog

修改Gemfile文件

source 'https://ruby.taobao.org/' # 更改gem源可能要设置环境变量
'jekyll', '3.2.1' # 注释掉这行
gem 'github-pages', group: :jekyll_plugins # 去掉这行的注释井号#

安装插件和依赖

bundle install

使用别人的模板克隆一个模板，官方jekyll模板列表
```
git clone git@github.com:someone/jekyll-theme.git # 克隆一个的模板
```
拷贝到自己的站点仓库目录，注意区分Windows和Ubuntu的命令
```
mkdir blog
cp jekyll-theme/* blog # 这是Ubuntu的命令
copy jekyll-theme/* blog # 这是Windows的命令
```
删除克隆的模板中的git记录
```
rm -rf blog/.git # Ubuntu
rd /s blog/.git  # Windows
```
我是直接使用的现成模板，所以后面的内容都是以现成模板的修改来讲述

初始化本地站点仓库

cd blog
git init
git remote add origin git@github.com:userName/blog.git # 与你的github blog仓库建立联系
git checkout --orphan gh-pages

配置站点站点仓库的目录结构如下

/blog
 |-- _config.yml # 站点配置文件
 |-- _layouts # 用户构成页面区域的模板，default或post一般是发布的文章的模板，page则是主页面的模板比如说边栏
 |      |-- default.html
 |      |-- post.html
 |      \-- page.html
 |-- _includes # 页面的小组件，比如分享、评论、访问统计等等
 |      |-- share.html
 |      \-- sidebar.html
 |-- _posts # 你的markdown原文件存放的目录
 |-- _site # jekyll build 默认生成已编译站点文件的目录
 |-- _plugins # 使用的jekyll插件的存放目录
 \-- index.html # 站点首页

注意：只要是按照各目录结构，这个站点仓库直接push到GitHub的仓库里，就可以建立起站点了，当然要设置作为GitHub Pages站点的分支（一般是gh-pages，不过现在可以是master分支，甚至是master分支下的docs目录了）。但是有时候需要把编译后的文件作为站点页面文件（比如你使用了jekyll插件来实现页面，而不是用JavaScript），这时候就需要把blog目录的源文件和编译后的站点文件（一般默认是_site）分开来push了。建议在blog目录下新增一个.gitignore文件，其中写入_site来忽略对这个目录的提交。将blog目录作为远程仓库的source分支，而_site目录作为远程仓库的gh-pages分支或者master分支

git checkout -b source
git branch -D master # 删除分支
git branch -D gh-pages # 删除分支
cd _site # 切换到_site目录
git init
git remote add origin git@github.com:userName/blog.git # 与同意github blog仓库建立联系
git checkout -b gh-pages

修改_config.yml文件，整个站点的配置主要是在这个文件中修改

name: '博客名'
description: '博客简述'
encoding: 'utf-8'
url: 'http(s)://your.site.com'
baseurl: '/your/project/path or blank'

defaults:
 -
   scope:
     path: ''
     type: 'posts'
   value:
     layout: '在_layouts目录下的post.html或者default.html的文件名，不带扩展名'
     author: '作者'
     comments: true
     share: true
social:
 github: 'github用户名'
 codepen: 'codepen用户名'
 rss: feed.xml
disqus: '在disqus上设置的你的站点名或博客名'
comments: true

创建/修改_include和_layouts目录下的文件，使用Liquid语法

安装jekyll插件以及更多jekyll配置信息请阅读jekyll官方文档

撰写博文因为jekyll是使用kramdown来解析markdown，与常见markdown略有区别，建议参考kramdown的官方语法，如果需要更换其他markdown解析器需要在_config.yml文件中设置，并且安装插件

博文源文件的命名，前时间后文章名：2016-09-01-how-to-build-a-site-on-github-pages.md

博文结构主要是指头部，头部结构如下：
```
layout: post # 默认是default，跟_layouts目录下的default.html文件对应，可以通过_config.yml的defaults字段配置默认设置
author: 作者名 # 可以_config.yml默认配置
title: 博文标题
date: yyyy-mm-dd
categories:
- category1
- category2
tags:
- tag1
- tag2
comments: true # 开启第三方评论模块，可以_config.yml默认配置
share: true # 开启第三方分享模块，可以_config.yml默认配置
```
写好的markdown文件存储于_posts目录下即可。
做好源文件的版本控制对站点源文件进行提交，以便进行版本控制，进入blog目录
```
git add --all
git commit -m 'some revisions'
git push origin source
```

部署站点生成编译后的静态站点文件，并且push到远程仓库

jekyll build
cd _site
git add --all
git commit -m 'some descriptions'
git push origin gh-pages

以后每次有新的文章发布，需要重复7~9步的操作。
补充：添加disqus评论功能
- 创建一个disqus账号，新建一个admin Disqus admin->Your Sites->+new，完成表单，提交
- 在站点页面，插入disqus代码 Universal Code install instructions
  使用hexo

安装node 在Windows下，从 https://nodejs.org/en/ 下载以.msi为扩展名的安装包，如果不需要进行node相关开发的话，选LTS版本就够用了。

在Ubuntu下，可以利用nvm装node

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.0/install.sh | bash # 安装nvm
nvm install node  # 安装最新版本node
nvm ls            # 查看已安装的版本
nvm use node      # 使用node

安装hexo

npm install -g hexo-cli
npm install hexo-deployer-git --save # 安装部署站点的node功能包，hexo deploy命令需要

建立站点仓库

hexo init blog # 初始化一个站点目录
cd blog
npm install

配置站点一般hexo初始化后的站点目录结构如下

/blog
|-- _config.yml # 站点配置文件
|-- scaffolds   # 页面模板存放的目录
|      |-- post.html # 博文模板
|      |-- page.html # 分页模板
|      \-- draft.html # 草稿模板
|-- source         # 博文源文件目录
|      |-- _posts  # 存放博文的目录
|      \-- _drafts # 存放草稿的目录
|-- themes      # 存放主题文件夹的目录
|-- package.json
|-- node_modules # 功能依赖包
\-- .gitignore   # push的时候忽略node_modules文件夹等

修改_config.yml文件，整个站点的配置主要是在这个文件中修改

title: 博客名
description: 博客简述
author: 作者名
url: http(s)://your.site.com
root: /your/project/path or /

deploy:
 type: git
 repo: git@github.com:userName/blog.git
 branch: gh-pages
 message: [自定义的提交信息]

撰写博文每当需要撰写心得博文时，只需要执行以下命令，就可以得到一个标题和日期已经设置好的markdown文件

hexo new [layout] '博文标题' # layout是可选项，表示使用哪种模板来创建页面文件，默认是post

博文结构的头部

title: 博文标题
date: yyyy-mm-dd  # 日期是创建博文源文件时自动生成的
categories:
- category1
- category2
tags:
- tag1
- tag2
comments: true

做好源文件的版本控制由于hexo是自动将站点文件自动部署到GitHub Pages上的，所以不需要自己另外push，但是建立生成站点页面的分支，还是有必要的。
```
git init
git remote add origin git@github.com:userName/blog.git # 与你的github blog仓库建立联系
git checkout --orphan source
git push origin source
```
部署站点 hexo的站点部署很简单
```
hexo g # 生成编译后的静态站点文件
hexo d # 部署到远程仓库
```
或者可以结合起来，生成静态文件后直接部署，下面两条命令使用一条即可
```
hexo g -d # 生成后部署
hexo d -g # 部署前生成
```
以后每次有新的文章发布，只需要如下操作
```
hexo new '博文标题'
hexo g -d
```

常用hexo命令

hexo init <站点仓库的目录> # 初始化一个站点目录
hexo clean # 用于主题切换等涉及站点整体布局效果改变的行为时，清楚hexo原有缓存
hexo new '博文标题' # 新增一篇博文
hexo generate # 可简写为 hexo g ，编译生成静态页面文件
hexo server # 可简写为 hexo s ，开启本地服务器预览与测试编译生成的静态页面效果
hexo delpoy # 可简写为 hexo d ，部署站点到远程仓库
hexo generate -d # 可简写为 hexo g -d ，编译生成静态页面文件并部署到远程仓库
hexo deploy -g # 可简写为 hexo d -g ，同上

修改主题从hexo themes找到何意的主题，clone下来，放到站点本地仓库的themes目录下，修改_config.yml文件的theme字段为对应的主题名
```
theme: light
```

更多插件等功能，建议去hexo 官网查看。

参考链接

tags: GitHub Pages, jekyll, hexo

uolcano / blog