使用 hexo 部署个人博客网站

发表于 | 分类于

博文地址

我的GitHub 我的博客 我的微信 我的邮箱
baiqiantao baiqiantao bqt20094 baiqiantao@sina.com

目录

[TOC]

Hexo

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

Hexo 是基于 Node.js 的高效静态站点生成框架，通过 Hexo 你可以轻松地使用 Markdown 编写文章。

1
2
3
4
5
6
使用体验：不建议使用！
- 必须在文件头部至少加上一个包含 `title` 的 Front-matter，灵活性太差
- 生成的 public 目录下的冗余文件太多了，毫无结构可言
- 虽然主题和插件比较丰富，但是功能还是太弱，页面也不够美观
- bug 太多了，首页、分类、标签、导航...都有无尽的 bug
- 和其他同类产品相比，使用起来太过复杂

快速使用

  • 确保安装了 Node.js：node -v和npm -v
  • 确保配置了 ssh：ssh -T git@github.com
  • 全局安装 hexo：npm i -g hexo
  • 创建一个博客目录并初始化：hexo init
  • 安装所需要的组件：npm install
  • 创建一个文件：hexo new xxx，执行后会在目录/source/_posts/下生成一个文件xxx.md
  • 生成静态文件：hexo g，生成的文件都在/public/目录下
  • 启动本地服务：hexo s，或hexo server -p 端口号

启动服务后，可访问 http://localhost:4000 查看生成的静态文件。在服务启动期间，Hexo 会监视文件变动并自动更新，而无须重启服务器。

部署到 GitHub

  • 在 GitHub 上创建仓库
    • 如果部署到根目录，仓库名必须为：baiqiantao.github.io
    • 如果部署到子目录，仓库名可随意，比如：hexoBlog
  • 在 _config.yml 中设置正确的 url 和 root
    • 如果部署到根目录：url: https://baiqiantao.github.io，root: /
    • 如果部署到子目录：url: https://baiqiantao.github.io/hexoBlog，root: /hexoBlog/
  • 在 _config.yml 中设置正确的 deploy
    • 如果部署到根目录：repo: git@github.com:baiqiantao/baiqiantao.github.io.git，branch: master
    • 如果部署到子目录：repo: git@github.com:baiqiantao/hexoBlog.git，branch: gh-pages
  • 安装部署插件：npm i hexo-deployer-git
  • 执行命令hexo g -d即可自动完成 build、push 等操作
  • 然后就可以访问 baiqiantao.github.io 或 baiqiantao.github.io/hexoBlog/
1
2
3
4
deploy:
  type: git
  repo: git@github.com:baiqiantao/hexoBlog.git
  branch: gh-pages
1
2
3
4
deploy:
  type: git
  repo: git@github.com:baiqiantao/baiqiantao.github.io.git
  branch: master

目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
├── .deploy_git    # 在 _config.yml 中配置的 git 仓库，内容来自 public 目录
├── node_modules   # 依赖的模块，有些模块必须使用本地依赖，比如 hexo-deployer-git
├── public         # 存放自动生成的静态文件，这个目录的内容会拷贝到 .deploy_git 中
|   ├── images/css/js/lib  # 项目用到的静态资源，source 目录下的静态资源也会拷贝过来
|   ├── categories/tags    # 分类、标签文件
|   ├── archives/...       # 生成的博客文件
├── scaffolds      # 模板，通过 hexo new 新建文章时可使用默认模板 post、page、draft，也可自定义
├── source         # 源文件
|   ├── _posts     # 用来发布的文件，需确保文件头至少包含 title 的 Front-matter，否则可能出错
|   ├── _drafts    # 临时的草稿文件
├── themes         # 主题目录，每个主题放到一个单独的子目录汇总
|
├── _config.yml    # 【重要】网站的配置文件，配置博客的基础信息、模板、主题、部署等
├── package.json   # 项目的配置文件，这是 npm 项目通用的配置文件，例如项目名、版本、依赖
  • source 目录下的除_posts外，开头命名为_的文件、文件夹和隐藏的文件将会被忽略
  • source 目录下的 Markdown 文件，会被解析后放到public目录，其他文件，例如图片、css、js、lib 等，会被直接拷贝到public目录
  • source/images 中的图片可以通过相对路径引用，例如，对于source/images/logo.png：
    • source/_posts/README.md中引用方式：![](../images/logo.png)
    • source/_posts/blog/about.md中引用方式：![](../../images/logo.png)

确保 source 目录下的 MarkDown 文件以及 _config.yml 配置文件是以 utf-8 编码保存的。

常用命令

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
hexo init [folder]         # 初始化
hexo install               # 安装所需要的组件
hexo -v                    # 显示 Hexo 版本等信息

hexo g                     # generate，生成静态文件
hexo s                     # server，启动服务器
hexo d                     # deploy，部署网站
hexo g -d                  # 自动完成 generate + deploy 操作
hexo clean                 # 清除缓存文件和已生成的静态文件

hexo s -p <port>           # 更改部署端口，默认为 4000
hexo s -i 192.168.1.1      # 更改部署 ip，默认为 `0.0.0.0`
hexo list <type>           # 查看如下信息：page, post, route, tag, category
npm list                   # 查看当前模块本地依赖列表

hexo g --watch             # 监视文件变动并立即重新生成静态文件
hexo new [layout] xxx      # 新建一篇文章
hexo publish [layout] xxx  # 发表草稿
hexo render xxx            # 渲染文件。`-o`设置输出路径
hexo migrate <type>        # 从其他博客系统迁移内容

hexo --safe                # 安全模式，不会载入插件和脚本
hexo --debug               # 调试模式。在终端中显示调试信息并记录到`debug.log`
hexo --silent              # 简洁模式。隐藏终端信息
hexo --config custom.yml   # 自定义配置文件的路径
hexo --draft               # 显示`source/_drafts`文件夹中的草稿文章
hexo --cwd /path/to/cwd    # 自定义当前工作目录的路径

功能拓展

主题 themes

使用主题

  • 下载主题文件 git clone --branch v5.1.2 https://github.com/iissnan/hexo-theme-next themes/next
    • hexo 在 5.0 之后把 swig 给删除了，需要手动安装，否则页面会渲染失败：npm i hexo-renderer-swig
  • 下载完成后，在 themes 文件夹内，会新增一个名为当前主题的文件夹，比如 next
  • 修改 _config.yml 内的主题 theme: next，有些主题可能会需要添加一些必要的配置
  • 修改主题后，建议先 hexo clean，然后再 hexo g

几个流行的主题

插件 plugins

1
2
npm install 插件名称 --save     # 安装插件
npm uninstall 插件名称 -save    # 卸载插件

如果插件代码很简单，可以写 JavaScript 脚本，只需要脚本文件放到 scripts 文件夹中，在启动时就会自动载入。

permalink 直接翻译的意思是永久链接，但是其实在这里的意思仅仅是：MarkDown 文件生成的 html 被部署后，访问的链接的生成规则，没有什么永久不永久的意思。

设置规则

可以在 permalink 中设置网站的永久链接(也可以在文章的 Front-matter 中指定)，可在 permalink_defaults 参数下调整永久链接中各变量的默认值。

1
2
permalink: :title/      ## 文章链接，默认【:year/:month/:day/:title/】，要以/或.html结尾
permalink_defaults:     ## 链接中各部分的默认值，默认【】

permalink 中可以下列变量或 Front-matter 中定义的属性(例如title)

  • :title：文件名称
  • :category：文章分类。如果文章没有分类，则是 default_category 配置信息
  • :post_title：文章标题
  • :id：文章 ID
  • :year：文章的发表年份，4 位数
  • :month：文章的发表月份，2 位数
  • :i_month：文章的发表月份，去掉开头的零
  • :day：文章的发表日期，2 位数
  • :i_day：文章的发表日期，去掉开头的零

设置案例

假设文件 source/_posts/about.md 中包含以下 Front-matter：

1
2
3
4
5
title: about
bqtdir: 包青天
categories:
- foo
- bar
1
2
3
4
permalink: :year/:month/:day/:title/      # 生成的链接为【2018/07/14/about】，有多个层级
permalink: :year-:month-:day-:title.html  # 生成的链接为【2018-07-14-about.html】，只有一个层级
permalink: :category/:title               # 生成的链接为【foo/bar/about】
permalink: :bqtdir/                       # 生成的链接为【包青天/】

链接插件

  • permalink-pathed-title：使用文件的相对路径生成链接
  • hexo-abbrlink：在文章的front-matter中自动增加abbrlink属性，值为base64(md5(标题+时间))，例如abbrlink: 66c8

分类和标签

在 Hexo 中，分类具有顺序性和层次性，而标签没有

1
2
3
4
5
6
7
categories:
- 分类
- 具有顺序性
- 具有层次性
tags:
- 标签
- 没有顺序性和层次性

设置别名

在 _config.yml 中，我们可以通过 category_map 给一个 category 设置别名，然后在组合 url 的时候，用这个别名 来替代 category 名称。tag_map的功能类似。

1
2
3
4
5
6
default_category: blog   ## 当没有分类时的默认分类，默认【uncategorized】
category_map:            ## 分类别名，在配置文件中获取 category 的值请使用【:category】
  baiqiantao: bqt        ## 会将分类 baiqiantao 替换为 bqt
tag_map:                 ## 标签别名
  baiqiantao: bqt        ## 会将标签 baiqiantao 替换为 bqt
  白乾涛: bqt             ## 会将标签 白乾涛 替换为 bqt

自动分类插件

例如，对于博客 source/_post/web/framework/hexo.md，该插件会自动生成以下categories：

1
2
3
categories:
  - web
  - framework

修改配置文件_config.yml，添加如下内容：

1
2
3
4
## Generate categories from directory-tree
auto_category:
  enable: true     ## 是否启用
  depth: 3         ## 要生成的目录树的深度

修改插件源码 TODO

hexo-auto-category 可以在构建时，自动为生成的文件添加 categories 信息，我能不能在让他自动帮我生成title等信息呢？

配置文件 config

YAML 依靠缩进来确定元素间的从属关系，因此，请确保缩进长度相同，并且使用空格缩进

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
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
## Site 网站
title: 标题               ## 网站标题
subtitle: 副标题          ## 网站副标题，默认【''】
description: Android Java 前端 程序员 技术 博客 GitHub baiqiantao  ## 用于SEO
keywords: Android Java 前端 程序员 技术 博客 GitHub baiqiantao     ## 用于SEO
author: 白乾涛            ## 用于在主题中显示作者
language: zh-Hans        ## 语言，中文【zh-CN】【zh-Hans】，默认【en】，可用值决于 themes
_timezone: ''            ## 时区，默认【''】，使用电脑的时区


## URL 网址
url: https://baiqiantao.github.io/hexoBlog    ## 网站首页
root: /hexoBlog/         ## 存放在网站子目录中时才需要设置，默认【/】
permalink: :title/       ## 文章链接，默认【:year/:month/:day/:title/】，要以/或.html结尾
_permalink_defaults:     ## 链接中各部分的默认值，默认【】
_pretty_urls:
  trailing_index: true   ## 设置为 false 以删除尾随的 'index.html' from permalinks，默认【true】
  trailing_html: true    ## 设置为 false 以删除尾随的 '.html' from permalinks，默认【true】


## Directory 目录
_source_dir: source       ## 资源文件夹，用来存放内容，默认【source】
_public_dir: public       ## 公共文件夹，用于存放生成的站点文件，默认【public】
_tag_dir: tags            ## 标签文件夹，默认【tags】
_archive_dir: archives    ## 归档文件夹，默认【archives】
_category_dir: categories ## 分类文件夹，默认【categories】
_code_dir: downloads/code ## Include code 文件夹，默认【downloads/code】
_i18n_dir: :lang          ## 国际化文件夹，默认【lang】，会捕获网址中的第一段以检测语言
_skip_render:             ## 跳过指定文件的渲染，可使用 glob 表达式来匹配路径，默认【】


## Writing 通过 hexo new 写文章
_new_post_name: :title.md ## 新文章的文件名称，默认【:title.md】
_default_layout: post     ## 预设布局，默认【post】
_auto_spacing: false      ## 在中文和英文之间加入空格，默认【false】
_titlecase: false         ## 把标题首字母大写，默认【false】
_external_link:
  enable: true            ## 新标签中打开链接，默认【true】
  field: site             ## Apply to the whole site，默认【site】
  exclude: ''             ## 排除，默认【''】
_filename_case: 0         ## 把文件名称转换为小写(-1)或大写(-2)，默认【0】
_render_drafts: false     ## 显示草稿，默认【false】
_post_asset_folder: false ## 启动 Asset 文件夹，默认【false】
_relative_link: false     ## 把链接改为与根目录的相对位址，默认【false】
_future: true             ## 显示未来的文章，默认【true】
_highlight:               ## 代码块高亮设置
  enable: true            ## 启用，默认【true】
  line_number: true       ## 显示行号，默认【true】
  auto_detect: false      ## 自动侦测，默认【false】
  tab_replace: ''         ## 替换 tab，默认【''】
  wrap: true              ## 包裹，默认【true】
  hljs: false             ## 使用 hljs 渲染，默认【false】
_prismjs:                 ## 一个非常流行的代码块高亮工具
  enable: false           ## 启用，默认【false】
  preprocess: true        ## 预处理，默认【true】
  line_number: true       ##  显示行号，默认【true】
  tab_replace: ''         ##  替换 tab，默认【''】


## Home page setting 首页设置
_index_generator:        ## 生成索引
  path: ''               ## 博客索引页面(index)的根路径，默认【''】
  per_page: 10           ## 每页显示的帖子，0 代表禁用分页，默认【10】
  order_by: -date        ## 排序方式，默认【-date】，按日期降序排序


## Category&Tag 分类&标签
default_category: blog   ## 当没有分类时的默认分类，默认【uncategorized】
category_map:            ## 分类别名，在配置文件中获取 category 的值请使用【:category】
  baiqiantao: bqt        ## 会将分类 baiqiantao 替换为 bqt
tag_map:                 ## 标签别名
  baiqiantao: bqt        ## 会将标签 baiqiantao 替换为 bqt


## Metadata elements  元数据
_meta_generator: true    ## 生成元数据，默认【true】


## Date/Time format 日期/时间格式
_date_format: YYYY-MM-DD  ## 默认【YYYY-MM-DD】
_time_format: HH:mm:ss    ## 默认【HH:mm:ss】


## updated_option 更新选项，可选 'mtime', 'date', 'empty'
_updated_option: 'mtime'  ## 默认【'mtime'】


## Pagination 分页
per_page: 15              ## 每页显示的文章量，0 代表关闭分页功能，默认【10】
_pagination_dir: page     ## 分页目录，默认【page】


## Include / Exclude file(s) 选项 include:/exclude 仅应用于 'source/' 目录
_include:                 ## 包含哪些文件，默认【】
_exclude:                 ## 排除哪些文件，默认【】
_ignore:                  ## 忽略哪些文件，默认【】


## Extensions 插件【https://hexo.io/plugins/】，主题【https://hexo.io/themes/】
theme: next               ## 当前主题名称，值为 false 时禁用主题，默认【landscape】
auto_category:            ## Generate categories from directory-tree
  enable: true            ## 是否启用
  depth: 3                ## 要生成的目录树的深度


## Deployment 部署  可同时部署多个不同 type 的仓库
deploy:
  type: git
  repo: git@github.com:baiqiantao/hexoBlog.git
  branch: gh-pages

2019-3-15