Github Pages建立过程和详细教程

原因不多说，总之下决心把Blog从Blogger迁移到Github。

具体过程：

一、在Github创建Github Pages站点

二、安装建站工具

官网推荐用Jekyll，我用的 Hexo，原因是上面史上最全教程推荐的。

三、更换渲染器

Hexo默认的Markdown渲染器是hexo-renderer-marked，不支持Mathjax公式和emoji表情，拟将渲染器更换为hexo-renderer-markdown-it。

Hexo常见的Markdown渲染器有：hexo-renderer-marked，hexo-renderer-kramed，hexo-renderer-pandoc，hexo-renderer-markdown-it，hexo-renderer-markdown-it-plus，其简单对比如下（参考于：Hexo的多种Markdown渲染器对比分析）

渲染器	Mathjax	插件扩展	emoji表情
hexo-renderer-marked	❌	❌	❌
hexo-renderer-kramed	✔️	❌	❌
hexo-renderer-pandoc	✔️
hexo-renderer-markdown-it	✔️(需插件支持)	✔️	✔️
hexo-renderer-markdown-it-plus	✔️	✔️	✔️

1. 安装渲染器

卸载已有渲染器

1
npm un 渲染器名称 --save

如：

1
npm un hexo-renderer-marked --save

安装新渲染器hexo-renderer-markdown-it

1
npm i hexo-renderer-markdown-it --save

2. 安装插件

安装hexo-renderer-markdown-it不自带的四个常用插件

1
2
3
4
npm i markdown-it-checkbox 
npm i markdown-it-imsize 
npm i markdown-it-expandable 
npm install hexo-filter-mathjax

3. 配置

将如下文本复制粘贴到 Hexo 的配置文件 _config.yml 的尾部

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
markdown:
  preset: "default"
  render:
    html: true
    xhtmlOut: false
    langPrefix: "language-"
    breaks: true
    linkify: true
    typographer: true
    quotes: "“”‘’"
  enable_rules:
  disable_rules:
  plugins:
    - markdown-it-abbr
    - markdown-it-cjk-breaks
    - markdown-it-deflist
    - markdown-it-emoji
    - markdown-it-footnote
    - markdown-it-ins
    - markdown-it-mark
    - markdown-it-sub
    - markdown-it-sup
    - markdown-it-checkbox
    - markdown-it-imsize
    - markdown-it-expandable
    - name: markdown-it-container
      options: success
    - name: markdown-it-container
      options: tips
    - name: markdown-it-container
      options: warning
    - name: markdown-it-container
      options: danger
  anchors:
    level: 2
    collisionSuffix: ""
    permalink: false
    permalinkClass: "header-anchor"
    permalinkSide: "left"
    permalinkSymbol: "¶"
    case: 0
    separator: "-"

4. 渲染器（render）配置详解

1
2
3
4
5
6
7
8
9
# Markdown-it config
markdown:
  render:
    html: true
    xhtmlOut: false
    breaks: true
    linkify: true
    typographer: true
    quotes: '“”‘’'

html：定义文档中的HTML内容是否应转义或传递给最终结果。

1
2
html: true # 不转义 HTML 内容
html: false # 转义 HTML 内容，使标签作为文本输出

xhtmlOut：定义解析器是否将导出完全兼容XHTML的标记。

1
2
xhtmlOut: true # 必须使用完全的 XHTML 代码，换行必须为 <br/>
xhtmlOut: false # 不必必使用完全的 XHTML 代码，换行可以为 <br>

breaks：使源文件中的换行符被解析为标记。每次按Enter键都会创建换行符。

1
2
breaks: true # 每次会车换行相当于一个 <br/> 标签
breaks: false # Pa每次会车换行会被忽略

linkify：解析器能够将直接粘贴到文本中的链接内联。

1
2
linkify: true # 类似链接的文本，作为链接输出
linkify: false # 类似链接的文本，依然作为文本输出

typographer：可以替换常见的排版元素。

1
2
typographer: true # 替换常见的排版元素
typographer: false # 不替换常见的排版元素

quotes：单引号、双引号如何被替换

1
2
quotes: '“”‘’' # 'single'、"double" 变成 ‘single’、“double”
quotes: '«»“”' # 'single'、"double" 变成 “single”、«single»

5. 插件用法

如果不想启用某个插件，可以直接注释掉

1
2
3
plugins:
  - markdown-it-abbr
  # - markdown-it-deflist

名称	描述	语法	示例
markdown-it-abbr	注释	`*[HTML]: 超文本标记语言`	*[HTML]: 超文本标记语言
markdown-it-emoji	表情	`:)`	:)
markdown-it-footnote	脚注	`参考文献[^脚注]` `[^脚注]:脚注的内容`	参考文献¹
markdown-it-ins	下划线	`++下划线++`	++下划线++
markdown-it-mark	突出显示	`==标记==`	==标记==
markdown-it-sub	下标	`H~2~O`	H2O
markdown-it-sup	上标	`X^2^`	X^2^
markdown-it-checkbox	复选框	未选：`+ [ ]`选中：`+ [x]`	+ [ ] 未完成+ [x] 已完成
hexo-filter-mathjax	数学公式	$z^2 = x^2 + y^2$	$z^2 = x^2 + y^2$

markdown-it-imsize：自定义图片宽高
点击打开详细说明语法：（注意：=100x200 前面有一个空格）
1
![test](image.png =100x200)
输出：
1
<p><img src="image.png" alt="test" width="100" height="200" /></p>
markdown-it-expandable：折叠/展开内容
点击打开详细说明语法：+++ 初始打开 »> 初始隐藏
1 2 3
+++ **点击折叠** 这是被隐藏的内容 +++
效果：
+++ 点击折叠 这是被隐藏的内容 +++

markdown-it-container：自定义容器 ==有的主题无效==

点击打开详细说明语法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
::: tips
**提示**
这是一个提示
:::

::: warning
**注意**
这是一个警告
:::

::: danger
**警告**
这是一个危险信号
:::

::: success
**成功**
这是一个成功信号
:::

效果:

::: tips 提示这是一个提示 :::

::: warning 注意这是一个警告 :::

::: danger 警告这是一个危险信号 :::

::: success 成功这是一个成功信号 :::

  自定义容器还需要在 Hexo 的主题下的控制 Markdown 渲染样式文件中配置如下 CSS 内容：（否则不会显示背景色填充效果）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
.tips {
padding-left: 10px;
background-color rgba(52,152,219,.3);
border-left 4px solid rgb(52,152,219);
color: darken(rgb(52,152,219),20%);
}
.success {
    padding-left: 10px;
    background-color rgba(46,204,113,.3);
    border-left 4px solid rgb(46,204,113);
    color: darken(rgb(46,204,113),20%);
}
.warning {
    padding-left: 10px;
    background-color rgba(241,196,15,.3);
    border-left 4px solid rgb(241,196,15);
    color: darken(rgb(241,196,15),20%);
}
.danger {
    padding-left: 10px;
    background-color rgba(231,76,60,.3);
    border-left 4px solid rgb(231,76,60);
    color: darken(rgb(231,76,60),20%);
}

hexo-filter-mathjax 公式

点击打开详细说明用法：把下面代码加入 Hexo的 _config.yml中

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
mathjax:
tags: none # or 'ams' or 'all'
single_dollars: true # enable single dollar signs as in-line math delimiters
cjk_width: 0.9 # relative CJK char width
normal_width: 0.6 # relative normal (monospace) width
append_css: true # add CSS to pages rendered by MathJax
every_page: false # if true, every page will be rendered by MathJax regardless the `mathjax` setting in Front-matter
packages: # extra packages to load
extension_options: {}
# you can put your extension options here
# see http://docs.mathjax.org/en/latest/options/input/tex.html#tex-extension-options for more detail

  在页面文件中设置mathjax: true

1
2
3
4
5
6
---
title: On the Electrodynamics of Moving Bodies
categories: Physics
date: 1905-06-30 12:00:00
mathjax: true
---

6. 锚（anchors）的用法

可能自己不会用，因此，没太关注这个功能

1
2
3
4
5
6
7
8
# Markdown-it config
markdown:
  anchors:
    level: 2
    collisionSuffix: 'v'
    permalink: true
    permalinkClass: header-anchor
    permalinkSymbol: ¶

level：生成 Heading ID 的标题等级
collisionSuffix：Heading ID 重复时，数字的后缀
permalink：’true’，则创建一个锚标记，除标题外还有一个固定链接
permalinkClass：用于固定链接锚标记的样式
permalinkSymbol：用于固定链接标记的符号

四、安装主题

目前主题采用Tree,

~~目前我用的主题是Freemind，~~

~~优点：~~

~~1. 自带搜索引擎，看起来高大上~~

~~2. 标签插件加强~~

~~3. 多套颜色主题~~

~~4. 支持 Front-Matter~~

自带评论系统。不过我把评论系统改成了giscus，乱码问题参考了这个古老风格。

配置在Hexo的_config.yml，但是recent_comments组件没有完成。

按照giscus的官方教程一路操作就行。

五、自动部署

参考这个简单的部署方法：利用Github Action实现hexo博客的自动部署。

增加文章后，只需要下面三条命令，就会推送到服务器自动生成。

1
2
3
git add .
git commit -m "增加博文"
git push

六、编辑工具和图床

编辑工具使用 Typora，图床用github，图床工具用picGo。

七、文章使用父子分类

1
2
3
4
categories:
- [Diary, PlayStation]
- [Diary, Games]
- [Life]

此时这篇文章同时包括三个分类： PlayStation 和 Games 分别都是父分类 Diary 的子分类，同时 Life 是一个没有子分类的分类。

脚注的内容 ↩︎

奥国天空

文章目录