07-GitHub Pages

GitHub Pages

不能有README.md文件，必须index.html文件作为首页

个人官网

仓库名的格式为GitHub用户名.github.io，之后可使用https://GitHub用户名.github.io访问该页面的index.html的首页

搭建

推荐使用Hexo进行静态博客搭建（前提是有Nodejs环境），具体步骤如下

npm install -g hexo-cli  #全局安装hexo个人静态博客生成器
hexo init blog  #会在当前目录下生成一个blog目录，用于存放博客系统文件；长时间无响应按回车即可
cd blog  #进入该项目目录
npm install  #安装该项目所需依赖
npm install hexo-deployer-git --save  #安装博客部署到Github Pages上的插件
npm install hexo-image-link --save  #安装静态图片映射插件

博客项目目录

生成的博客项目目录如下：

• scaffolds：生成文章的一些模板
• source：文章目录
• themes：主题
• _config.yml ：博客系统配置文件

必要的配置

注意：若是复制需要将行内注释删除

# Site
title: 'xxx'  #站点标题
subtitle: 'xxx'  #站点副标题
description: 'xxx'  #站点描述
keywords: 'xxx'  #站点关键字
author: 'xxx'  #作者名
language: zh-CN  #站点语言
timezone: Asia/Shanghai  #站点时区

#其他非必要配置省略...

# URL
## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
url: GitHub用户名.github.io  #站点url
root: /  #站点根目录

# Writing
#其他非必要配置省略...
post_asset_folder: true  #允许访问静态资源
#其他非必要配置省略...

## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: hexo-theme-matery  #主题

# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
  type: git  #部署类型
  repository: https://github.com/GitHub用户名/GitHub用户名.github.io.git  #其实就是clone地址
  branch: master  #分支

常用的命令

Hexo常用命令如下：

• hexo g：将编写的Markdown文件转化成静态博客中的文章
• hexo s：本地查看静态博客效果，运行此命令后，访问http://locakhost:4000即可看到效果
• hexo d：将静态博客推送到远端
• hexo clean：清空hexo g生成的内容
• hexo new post 标题名称：根据模板在/source/_post目录下生成文章模板，进行编写

定制化

注意：插件的安装是在博客项目的根目录进行安装

将主题下载到本地后，放入Hexo的themes文件夹中即可，修改Hexo根目录下的_config.yml的theme的值为要切换的主题文件夹名

这里推荐下面两个主题如下：

• hexo-theme-matery：美化教程推荐如下
  • 效果：官方教程
  • 效果：教程
  • 效果：教程
  • 效果：教程
  • 效果：教程
• hexo-theme-sakura：美化教程推荐如下
  • 效果（作者正在开发中）：官方教程
  • 效果：教程

项目官网

进入仓库，点击settings进入仓库设置页面，向下滑找到GitHub Pages板块，点击Choose a theme选择一个主题，编辑完成后为该会生成一个gh-pages分支，此后就可以使用https://GitHub用户名.github.io/项目名访问到该页面的index.html；点击项目右侧About的设置按钮，将该地址填入Website输入框，以及简短的描述信息

搭建

• gitbook-cli和gitbook是两个软件
• gitbook-cli 会将下载的gitbook的不同版本放到 ~/.gitbook中, 可以通过设置GITBOOK_DIR环境变量来指定另外的文件夹

推荐使用gitbook进行项目文档搭建（前提是有Nodejs环境），具体步骤如下

mkdir project  #创建一个项目目录
cd project  #进入该目录
gitbook init  #初始化项目文档，第一次执行会比较慢，因为要下载gitbook
#会在该目录下创建出以下两个文件
#SUMMARY.md：目录文件
#README.md：自述文件

文档目录

写好该文件后再次执行gitbook init将自动生成文件目录结构

分组

# Summary

* [介绍](README.md)

## 第一部分
  * [子项1](第一部分/子项1.md)
  * [子项2](第一部分/子项2.md)

## 第二部分
  * [子项1](第二部分/子项1.md)
  * [子项2](第二部分/子项2.md)
---
  * [分隔线下的子项3](第二部分/子项3.md)

分组介绍

# Summary
* [介绍](README.md)
* [第一部分目录介绍](第一部分/README.md)
    * [子项1](第一部分/子项1.md)
    * [子项2](第一部分/子项2.md)
* [第二部分目录介绍](第二部分/README.md)
    * [子项1](第二部分/子项1.md)
    * [子项2](第二部分/子项2.md)

必要的配置

在文档根目录创建book.json文件，进行下面配置，复制时将注释去掉json不支持注释

{
  "title" : "文档标题",
  "author" : "文档作者",
  "description" : "简单描述",
  "language" : "zh-hans",  //文档语言
  "links" : {
    "sidebar" : {
      "Home" : "URL"  //在左侧导航栏添加链接信息
    }
  }
}

常用的命令

• gitbook build：输出当前文档项目为html格式
• gitbook serve：本地查看静态文档效果
• gitbook pdf：生成pdf格式文档

部署

git clone URL  #将远端项目克隆下来
cd 项目名  #进入该项目
git checkout gh-pages  #切换到gh-pages分支
cp ../_book/* ./  #拷贝gitbook生成的静态文档到该项目内，windows就手动复制吧
git add .  #将改动添加到暂存区
git commit -m "消息"  #提交
git push origin gh-pages  #向gh-pages分支中提交

常用的插件

官网的插件库貌似已经搬家了，一时找不到，所以更多插件请参照

在book.json文件下添加插件配置，再执行gitbook install安装插件

{
  "plugins": [
    "-lunr",  //去掉lunr自带插件
    "-search",  //去掉search自带插件
    "search-plus",  //使用search-plus支持中文搜索
    "-highlight",  //去掉highlight自带插件
    "prism",  //使用prism代码高亮插件
    "copy-code-button",  //代码复制按钮
    "katex",  //使用katex支持数学公式
    "-sharing",  //去掉sharing自带插件
    "sharing-plus",  //使用sharing-plus支持更多分享方式
    "tbfed-pagefooter",  //使用tbfed-pagefooter为页面添加页脚
    "expandable-chapters-small",  //使用expandable-chapters-small左侧导航栏可伸缩
    "donate",  //打赏插件
    "anchors",  //Github的锚点样式
    "todo",  //todo多选框
  ],
  "pluginsConfig": {
    "sharing": {  //配置sharing-plus插件分享方式
       "douban": false,
       "facebook": false,
       "google": true,
       "hatenaBookmark": false,
       "instapaper": false,
       "line": true,
       "linkedin": true,
       "messenger": false,
       "pocket": false,
       "qq": false,
       "qzone": true,
       "stumbleupon": false,
       "twitter": false,
       "viber": false,
       "vk": false,
       "weibo": true,
       "whatsapp": false,
       "all": [
         "facebook", "google", "twitter",
         "weibo", "instapaper", "linkedin",
         "pocket", "stumbleupon"
       ]
    },
    "tbfed-pagefooter": {
      "copyright":"Copyright &copy 2021 域名. All rights reserved.",
      "modify_label": "该文件修订时间：",
      "modify_format": "YYYY-MM-DD HH:mm:ss"
    },
    "donate": {
      "wechat": "微信图片URL",
      "alipay": "支付宝图片URL",
      "title": "标题",
      "button": "赏",
      "alipayText": "支付宝打赏",
      "wechatText": "微信打赏"
    }
  }
}