GitHub Pages (Hexo - Fluid)

Quickstart - Create Your Website

• GitHub Pages are public webpages hosted and easily published through GitHub. The quickest way to get up and running is by using the Jekyll Theme Chooser to load a pre-made theme. You can then modify your GitHub Pages’ content and style remotely via the web or locally on your computer.

---

• (1) Create a new repository on GitHub. On the new repository screen, you need to give this repository a special name (i.e. username.github.io) to generate your website. (If your user name contains uppercase letters, you must lowercase the letters)
  
• (2) Open the Settings tab
  See the Pages section. Click the Choose a theme button to start the process of creating your site.
  Click Select theme on the right to move on
  After you select a theme, your repository’s README.md file will open in the file editor. The README.md file is where you will write the content for your site. You can edit the file or keep the default content for now.
  When you are done editing the file, click Commit changes.
• (3) Edit _config.yml file to add a friendlier title and description to your site.
  
• (3) Check your own page on https://username.github.io/ !

Note: It can take up to 20 minutes for changes to your site to publish after you push the changes to GitHub.

Hexo

什么是 Hexo？

• Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 Markdown (或其他渲染引擎) 解析文章，在几秒内，即可利用靓丽的主题生成静态网页

安装

• 需要先安装 Git 和 Node.js

在 Linux 中，如果使用 Snap 来安装 Node.js，在初始化博客时可能需要手动在目标文件夹中执行 npm install

• 下面安装 Hexo

$ npm install -g hexo-cli

建站

• 执行下列命令，Hexo 将会在指定文件夹中新建所需要的文件：

$ hexo init <folder>
$ cd <folder>
$ npm install

• 新建完成后，指定文件夹的目录如下：

.
├── _config.yml		# 用于配置大部分的参数
|
├── package.json	# 应用程序的信息
|
├── scaffolds		# 模版文件夹。新建文章时，Hexo 会根据 scaffolds 来建立文件
|					# Hexo 的模板是指在新建的文章文件中默认填充的内容。例如，如果
|					# 修改 scaffolds/post.md 中的 Front-matter 内容，那么
|					# 每次新建一篇文章时都会包含这个修改
|
├── source			# 存放用户资源。除 _posts 文件夹之外，开头命名为 _ (下划线)
|   ├── _drafts		# 的文件 / 文件夹和隐藏的文件将会被忽略。Markdown 和 HTML
|   └── _posts		# 文件会被解析并放到 public 文件夹，而其他文件会被拷贝过去
|
└── themes			# 主题文件夹。Hexo 会根据主题来生成静态页面

基本操作

写作

# 创建一篇新文章或者新的页面
$ hexo new [layout] <title>

• 默认情况下，Hexo 会使用文章的标题来决定文章文件的路径。对于独立页面 (page) 来说，Hexo 会创建一个以标题为名字的目录，并在目录中放置一个 index.md 文件 (这个 .md 文件就是页面内容)
• layout: Hexo 有三种默认布局：post、page 和 draft。在创建这三种不同类型的文件时，它们将会被分别保存到 source/_posts、source、source/_drafts 路径下；而您自定义的其他布局和 post 相同，都将储存到 source/_posts 文件夹
  • 默认为 post，可以通过修改 _config.yml 中的 default_layout 参数来指定默认布局
  • If you don’t want an article (post/page) to be processed with a theme, set layout: false in its front-matter.
• 文件名称: Hexo 默认以标题做为文件名称，但您可编辑 new_post_name 参数来改变默认的文件名称. 如果标题包含空格的话，请使用引号括起来
  • 举例来说，设为 :year-:month-:day-:title.md 可让您更方便的通过日期来管理文章

变量	描述
:title	标题（小写，空格将会被替换为短杠）
:year	建立的年份，比如， 2015
:month	建立的月份（有前导零），比如， 04
:i_month	建立的月份（无前导零），比如， 4
:day	建立的日期（有前导零），比如， 07
:i_day	建立的日期（无前导零），比如， 7

• 草稿: 可通过 publish 命令将 draft 移动到 source/_posts 文件夹。草稿默认不会显示在页面中，您可在执行时加上 --draft 参数，或是把 render_drafts 参数设为 true 来预览草稿

$ hexo publish [layout] <title>

• 模版（Scaffold）: 在新建文章时，Hexo 会根据 scaffolds 文件夹内相对应的文件来建立文件，例如：$ hexo new photo "My Gallery" 会尝试在 scaffolds 文件夹中寻找 photo.md，并根据其内容建立文章

Front-matter

• Front-matter 是文件最上方以 --- 分隔的区域，用于指定个别文件的变量

---
title: Hello World
date: 2013/7/13 20:46:25
tags:
  - Testing
  - Another Tag
---

• 以下是预先定义的参数，您可在模板中使用这些参数值并加以利用：

参数	描述	默认值
layout	布局	config.default_layout
title	标题	文章的文件名
date	建立日期	文件建立日期
updated	更新日期	文件更新日期
comments	开启文章的评论功能	true
tags	标签 (不适用于分页); 只有文章支持分类和标签; 标签没有顺序和层次
categories	分类 (不适用于分页); 分类具有顺序性和层次性，也就是说 Foo, Bar 不等于 Bar, Foo
permalink	覆盖文章网址
excerpt	Page excerpt in plain text. Use this plugin to format the text
disableNunjucks	Disable rendering of Nunjucks tag {{ }}/{% %} and tag plugins when enabled
lang	Set the language to override auto-detection	Inherited from _config.yml

---

Examples

categories:
- Diary
- Life	# 分类 Life 成为 Diary 的子分类
tags:
- PS3	# 设置两个 tag
- Games

categories:	# 添加 3 个分类
- [Diary, PlayStation]	# PlayStation 和 Games 分别都是父分类 Diary 的子分类
- [Diary, Games]
- [Life]				# Life 是一个没有子分类的分类

---

JSON Front-matter:

• 除了 YAML 外，你也可以使用 JSON 来编写 Front-matter，只要将 --- 代换成 ;;; 即可

"title": "Hello World",
"date": "2013/7/13 20:46:25"
;;;

标签插件 (Tag Plugins)

• 标签插件和 Front-matter 中的标签不同，它们是用于在文章中快速插入特定内容的插件

---

引用块

{% blockquote [author[, source]] [link] [source_link_title] %}
content
{% endblockquote %}

Example

{% blockquote David Levithan, Wide Awake %}
Do not just seek happiness for yourself. Seek happiness for all. Through kindness. Through mercy.
{% endblockquote %}

{% blockquote Seth Godin http://sethgodin.typepad.com/seths_blog/2009/07/welcome-to-island-marketing.html Welcome to Island Marketing %}
Every interaction is both precious and an opportunity to delight.
{% endblockquote %}

---

代码块

{% codeblock [title] [lang:language] [url] [link text] [additional options] %}
code snippet
{% endcodeblock %}

• Specify additional options in option:value format, e.g. line_number:false first_line:5

Extra Options	Description	Default
line_number	Show line number	true
highlight	Enable code highlighting	true
first_line	Specify the first line number	1
mark	Line highlight specific line(s), each value separated by a comma. Specify number range using a dash (Example: mark:1,4-7,10 will mark line 1, 4 to 7 and 10).
wrap	Wrap the code block in <table>	true

Example

# 附加说明和网址
{% codeblock _.compact http://underscorejs.org/#compact Underscore.js %}
_.compact([0, 1, false, 2, '', 3]);
=> [1, 2, 3]
{% endcodeblock %}

---

文章摘要和截断

• 在文章中使用 <!-- more -->，那么 <!-- more --> 之前的文字将会被视为摘要。首页中将只出现这部分文字，同时这部分文字也会出现在正文之中

---

• To learn more

资源文件夹 (图片、CSS、JS 文件)

• 资源代表 source 文件夹中除了文章以外的所有文件，例如图片、CSS、JS 文件等。比方说，如果你的 Hexo 项目中只有少量图片，那最简单的方法就是将它们放在 source/images 文件夹中。然后通过类似于 ![](/images/image.jpg) 的方法访问它们

---

资源文件管理功能

• Hexo 也提供了更组织化的方式来管理资源。可以通过将 _config.yml 文件中的 post_asset_folder 选项设为 true 来打开。当资源文件管理功能打开后，Hexo 将会在你每一次通过 hexo new [layout] <title> 命令创建新文章时自动创建一个文件夹。这个资源文件夹将会有与这个文章文件一样的名字。将所有与你的文章有关的资源放在这个关联文件夹中之后，你可以通过相对路径来引用它们 (![](example.jpg) )
• 通过常规的 markdown 语法和相对路径来引用图片和其它资源可能会导致它们在存档页或者主页上显示不正确 (图片会显示在文章中，但不会出现在首页上)。为此需要进行如下配置来自动解析图片地址：
  • e.g. “image.jpg” is located at “/2020/01/02/foo/image.jpg”, meaning it is an asset image of “/2020/01/02/foo/“ post, ![](image.jpg) will be rendered as <img src="/2020/01/02/foo/image.jpg">.

# _config.yml
post_asset_folder: true
marked:
  prependRoot: true
  postAsset: true

数据文件夹

• 有时您可能需要在主题中使用某些资料，而这些资料并不在文章内，并且是需要重复使用的，那么您可以考虑使用 「数据文件」功能。此功能会载入 source/_data 内的 YAML 或 JSON 文件，如此一来您便能在网站中复用这些文件了

---

• 举例来说，在 source/_data 文件夹中新建 menu.yml 文件：

Home: /
Gallery: /gallery/
Archives: /archives/

• 您就能在模板中使用这些资料：

<% for (var link in site.data.menu) { %>
  <a href="<%= site.data.menu[link] %>"> <%= link %> </a>
<% } %>

渲染结果如下 :

<a href="/"> Home </a>
<a href="/gallery/"> Gallery </a>
<a href="/archives/"> Archives </a>

服务器

• 安装 hexo-server

$ npm install hexo-server --save

• 启动服务器，网站会在 http://localhost:4000 下启动。在服务器启动期间，Hexo 会监视文件变动并自动更新，您无须重启服务器

$ hexo server
$ hexo server -p 5000	# 启动服务器时可以指定其他端口
$ hexo server -s	# 开启静态模式。在静态模式下，服务器只处理 public 文件夹内的文件，
					# 而不会处理文件变动，在执行时，您应该先自行执行 hexo generate，
					# 此模式通常用于生产环境（production mode）下
$ hexo server -i 192.168.1.1	# 服务器默认运行在 0.0.0.0，您可以覆盖默认的 IP 设置

生成器

$ hexo generate		# 在项目根目录下自动生成 public 文件夹, 该文件夹即是我们网站所需的静态文件
$ hexo generate --watch		# 监视文件变动并立即重新生成静态文件，在生成时会比对
							# 文件的 SHA1 checksum，只有变动的文件才会写入

# 执行下列的其中一个命令，让 Hexo 在生成完毕后自动部署网站
$ hexo generate --deploy
$ hexo deploy --generate
$ hexo g --d
$ hexo d --g

clean

• 清除缓存文件 (db.json) 和已生成的静态文件 (public)。在某些情况（尤其是更换主题后），如果对站点的更改无论如何也不生效，可能需要运行该命令

$ hexo clean

常用配置

# _config.yml

# 网站相关参数
title: Ruikang Liu's homepage	# 网站标题
description: Feel free to bookmark this to keep an eye on my projext updates	# 网站描述
author: Ruikang Liu		# 文章的作者
language: en		# 网站使用的语言
timezone: Asia/Shanghai		# 网站时区

# 网址相关参数
url: https://ruikangliu.github.io/		# 网址

# 目录相关参数
skip_render: "README.md"	# 可以在 /source 里面放一个 README.md，推送的时候自动传到 Github 上面

# 文章相关参数
new_post_name: :year-:month-:day-:title.md	# 设置默认的文件名称
post_asset_folder: true		# 开启资源文件管理功能
marked:		# 自动解析图片地址
  prependRoot: true
  postAsset: true

# 扩展相关参数
theme: fluid	# 当前主题名称

# 自动部署
deploy:
  type: git	
  repo: https://github.com/ruikangliu/ruikangliu.github.io # Repository 地址
  branch: master	# 分支名称
  message: auto deploy	# 自定义提交信息

---

网站

参数	描述
title	网站标题
subtitle	网站副标题
description	网站描述。主要用于 SEO，告诉搜索引擎一个关于您站点的简单描述，通常建议在其中包含您网站的关键词
keywords	网站的关键词。支持多个关键词
author	用于主题显示文章的作者
language	网站使用的语言。对于简体中文用户来说，使用不同的主题可能需要设置成不同的值，请参考你的主题的文档自行设置，常见的有 en 和 zh-CN
timezone	网站时区。Hexo 默认使用您电脑的时区。对于中国大陆地区可以使用 Asia/Shanghai

---

网址

参数	描述	默认值
url	网址, 必须以 http:// 或 https:// 开头
root	网站根目录	url's pathname
permalink	文章的永久链接格式	:year/:month/:day/:title/
permalink_defaults	永久链接中各部分的默认值
pretty_urls	改写 permalink 的值来美化 URL
pretty_urls.trailing_index	是否在永久链接中保留尾部的 index.html，设置为 false 时去除	true
pretty_urls.trailing_html	是否在永久链接中保留尾部的 .html, 设置为 false 时去除 (对尾部的 index.html无效)	true

如果您的网站存放在子目录中，例如 http://example.com/blog，则请将您的 url 设为 http://example.com/blog 并把 root 设为 /blog/

---

目录

参数	描述	默认值
skip_render	跳过指定文件的渲染。匹配到的文件将会被不做改动地复制到 public 目录中。您可使用 glob 表达式来匹配路径

skip_render: "mypage/**/*"
# 将会直接将 `source/mypage/index.html` 和 `source/mypage/code.js` 不做改动地输出到 'public' 目录
# 你也可以用这种方法来跳过对指定文章文件的渲染
skip_render: "_posts/test-post.md"
# 这将会忽略对 'test-post.md' 的渲染

---

• more…

更换 Markdown 渲染器

• Hexo 默认使用 hexo-renderer-marked 渲染器，但该渲染器功能较弱，为此改为使用 hexo-renderer-markdown-it 渲染器，它的渲染速度更快，功能也更强大

$ npm un hexo-renderer-marked --save	# 卸载原有渲染器
$ npm i hexo-renderer-markdown-it --save

Hexo 部署至 GitHub Pages

• 安装 hexo-deployer-git

$ npm install hexo-deployer-git --save

• 修改配置

deploy:
  type: git	
  repo: <repository url> # 库（Repository）地址
  						 # e.g. https://bitbucket.org/JohnSmith/johnsmith.bitbucket.io
  branch: [branch]	# 分支名称
  message: [message]	# 自定义提交信息

• 生成站点文件并推送至远程库: 将 public 目录中的文件和目录推送至 _config.yml 中指定的远端仓库和分支中，并且完全覆盖该分支下的已有内容

$ hexo clean && hexo deploy

• You will be prompted with username and password of the target repository, unless you authenticate with a token or ssh key.

此外，如果您的 Github Pages 需要使用 CNAME 文件自定义域名，请将 CNAME 文件置于 source 目录下，只有这样 hexo deploy 才能将 CNAME 文件一并推送至部署分支

Hexo 主题 - Fluid

安装 Fluid

(1) 获取最新版本

$ npm install --save hexo-theme-fluid

• 在博客目录下创建 _config.fluid.yml，将主题的 _config.yml 内容复制过去

(2) 指定主题

# _config.yml
theme: fluid	# 指定主题

(3) 创建「关于页」

# 创建「关于页」
hexo new page about

# /source/about/index.md
---
title: about
date: 2020-02-23 19:20:33
layout: about	# 添加 layout 属性
---

这里写关于页的正文，支持 Markdown, HTML

更新主题

npm update --save hexo-theme-fluid

配置指南

• 参考 配置指南。可配置项包括：
  • 全局：页面顶部大图、导航菜单、网页统计、展示 PV 与 UV 统计、评论 (目前用的 Waline)、LaTeX 数学公式
  • 首页：Slogan、文章跳转方式、文章信息、隐藏文章、文章排序
  • 文章页：文章在首页的封面图、文章页顶部大图、文章内容图片、阅读数、脚注、Tag 插件
  • 归档页、分类页、标签页、关于页、自定义页面

云存储

• GitHub 限制仓库大小在 1 GB 内，因此图片、视频之类的资源还是用云存储比较好 (阿里云 对象存储 OSS，如果存的东西比较多的话可以开个资源包，半年 40GB 存储 5 块钱就搞定)。但我们平时是在本地写博客，怎么方便地在写博客时自动将本地图片上传到云端并填写相应的 url 呢？下面介绍一种解决方案 - Typora + PigGo + 阿里云

---

设置 Typora

• (1) 文件 $\to$ 偏好设置 $\to$ 图像。按下图进行配置
  
• (2) 点击下载或更新
• (3) 点击打开配置文件，粘贴为以下内容，其中 accessKeyId、accessKeySecret、bucket、area、customUrl 需要自行更改

{
  "picBed": {
    "uploader": "aliyun",
    "aliyun": {
    "accessKeyId": "",
    "accessKeySecret": "",
    "bucket": "", // 存储空间名
    "area": "", // 存储区域代号
    "path": "img/", // 自定义存储路径
     "customUrl": "", // 自定义域名，注意要加 http:// 或者 https://
     "options": "" // 针对图片的一些后缀处理参数 PicGo 2.2.0+ PicGo-Core 1.4.0+
    }
  },
  "picgoPlugins": {}
}

---

阿里云对象存储

• 首先需要创建一个阿里云对象存储 OSS 的 bucket 用于存储网站所需的视频、图片等信息。注意读写权限需要设置为公共读 (会产生额外的流量计费)，然后就是获取上述配置文件中需要的几项内容
• (1) accessKeyId、accessKeySecret：鼠标悬浮在右上角头像上，并选择 AccssKey 管理
  选择继续使用 AccessKey，并点击创建 AccessKey
  填写 accessKeyId、accessKeySecret
  
• (2) bucket、area、customUrl 按下图填写， bucket 即为创建的 bucket 名。注意，下图有误，“path 对应的值” 应该改为 “customUrl 对应的值”
  
• (3) 保存配置文件后点击验证图片上传
  如果，你看到下面这样的页面，那么恭喜你，你成功了。congratulation！！！
  

---

阿里云 OSS 端自动以时间戳命名文件夹和文件

• 首先需要找到 Typora 自动下载的 PicGo-Core 的执行文件路径。点击验证图片上传选项，验证结果里会有地址
  
• 之后 cd 到改目录下按照 super-prefix 插件即可

cd C:\Users\你自己的用户名\AppData\Roaming\Typora\picgo\win64
.\picgo.exe install super-prefix

• 最后再修改下 PicGo-Core 的配置文件：

{
  "picBed": {
    "uploader": "aliyun",
    "aliyun": {
    "accessKeyId": "你自己的accessKeyId",
    "accessKeySecret": "你自己的accessKeySecret",
    "bucket": "", 		// 存储空间名
    "area": "找到对应的，比如：oss-cn-beijing", 		// 存储区域代号
    "path": "img/", 	// 自定义存储路径，什么都可以，也可以直接为：""
     "customUrl": "", 	// 自定义域名，注意要加 http://或者 https://
     "options": "" 		// （可以空着）针对图片的一些后缀处理参数 PicGo 2.2.0+ PicGo-Core 1.4.0+
    }
  },
  // 插件设置
  "picgoPlugins": {
    "picgo-plugin-super-prefix": true
  },
  "picgo-plugin-super-prefix": {
    "prefixFormat": "YYYY/MM/DD/",
    "fileFormat": "YYYYMMDD-HHmmss"
  }
}

References

• GitHub Pages Documentation
• 静态模板系统:
  • jekyll (Ruby) (Themes 1, Themes 2, Themes 3)
  • Hexo (Node.js) (Themes, theme-NexT, theme-Ayer, theme-Fluid)
  • Hugo (GO) (Themes 1, Themes 2, Themes 3)
  • Pelican (Python)
  • Gridea
• Hexo 的多种 Markdown 渲染器对比分析
• 最强 markdown 编辑器 typora 图床教程 - 阿里云版
• Typora + 阿里云 OSS 实现图片上传云端