利用GitHub Pages搭建Hexo静态博客教程

利用GitHub Pages搭建Hexo静态博客教程

Written By Tomy Stark.
E-mail: ro7enkranz@qq.com
Ver 1.0.0

Note:

  • 转载请注明本文出处链接、作者

什么是 Hexo

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

搭建 Hexo 博客需要什么

  • Visual Studio Code(用于作为 Markdown 编辑器,由于内部集成了终端,非常方便,必备!)
  • Node.js(Node.js 版本需不低于 8.6,建议使用 Node.js 10.0 及以上版本)
  • Git(用于将编译好的 Hexo 静态博客文件部署到 GitHub Pages)
  • GitHub 帐号(帐号注册请自行完成,注册流程本文不做叙述)

详细步骤

1. 安装必要软件

  • Visual Studio Code

    下载完成后安装即可,没有特别需要注意的地方(安装目录可自己手动指定

    建议安装完成后,在 VS Code 中安装以下扩展插件:

    • Chinese (Simplified) Language Pack for VS Code
    • changeEncode
    • GBKtoUTF8
    • markdownlint
    • Markdown All in One
  • Node.js

    按照默认设置一直 Next 安装即可(安装目录可自己手动指定

  • Git

    注意其中一步选择 VS Code 作为 Git 的默认编辑器,其它默认(安装目录可自己手动指定

选择VS Code作为Git的默认编辑器

2. 注册 GitHub 帐号

  • 注册链接:GitHub 帐号注册(帐号注册请自行完成,注册流程本文不做叙述)

    注意:请在注册完成后验证邮箱

3. 在 GitHub 上新建仓库

  • 登录账号后,页面右上角 + 号,选择 New repository

New repository

  • 如果你希望你的站点能通过 <你的 GitHub 用户名>.github.io 域名访问,你的 repository 应该直接命名为 <你的 GitHub 用户名>.github.io。例如,我的用户名为 SummerFalls,那么该仓库名就应该为 SummerFalls.github.io,详见下图:

新建 GitHub 仓库

  • 新建完成后出现如下图页面:

仓库新建完毕

4. 安装 Hexo

  • 打开 VS Code,按下 Ctrl + ` 打开内部集成的终端
  • 先测试 Node.js 是否被能够被 VS Code 的终端所调用
    • VS Code 的终端中输入命令 npm -v
      • 如果正常,则会显示其版本号,例如 6.9.0
      • 如果异常,则会提示类似错误:npm : 无法将“npm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写,如果包括路径,请确保路径正确, 然后再试一次。这时,请关闭 VS Code,然后将其设置为 以管理员身份运行此程序,之后重新运行 VS Code,如图所示:

设置 VS Code 管理员权限

  • 定位到你想用于存放博客源文件夹的目录,我这里以C盘根目录为例

    cd C:\

  • 执行 npm 命令进行全局安装 Hexo

    npm install hexo-cli -g

  • 初始化 Hexo 博客(此举会在当前目录创建名为 blog 的文件夹)

    hexo init blog

  • 进入 blog 文件夹

    cd blog

  • 通过 blog 目录下的 package.json 进一步安装依赖,之后会产生一个 node_modules 文件夹

    npm install

  • 启动 Hexo 本地服务器

    hexo s

  • 检查 Hexo 是否安装成功,在执行上面的命令之后,终端会返回如下信息,按住 Ctrl + 鼠标左键单击 该链接即可打开

    INFO Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.

  • 打开后的页面如图,即说明 Hexo 安装成功

Hexo 初始页面

  • 回到 VS Code,切换到终端,按下 Ctrl + C,之后输入 Y 以停止 Hexo 服务器

5. 配置 Hexo

  • VS Code 中按下快捷键 Ctrl + K + O,打开你的博客源文件夹,如图:

打开博客源文件夹

  • 打开左侧 侧边栏 中的 _config.yml 文件进行修改,如下所示,请认真阅读注释说明

    _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
    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
    # Hexo Configuration
    ## Docs: https://hexo.io/docs/configuration.html
    ## Source: https://github.com/hexojs/hexo/

    # Site
    title: Tomy Stark's Blog # 你的博客名
    subtitle: 四海茫茫 # 子标题
    description: STM32, TI C2000, S32K # 博客描述,SEO相关
    keywords: C, C++ # 关键词
    author: Tomy # 博主名字
    language: zh-CN # 语言,**关系到主题所显示的语言**
    timezone: # 时区,默认留空

    # URL
    ## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
    url: 'https://SummerFalls.github.io' # 域名设置,如果没有自己的域名,则地址应为 https://<你的 GitHub 用户名>.github.io 例如我的为: https://SummerFalls.github.io
    root: /
    permalink: :year-:month-:day-:title.html # 建议将永久链接改成如此
    permalink_defaults:

    # Directory
    source_dir: source
    public_dir: public
    tag_dir: tags
    archive_dir: archives
    category_dir: categories
    code_dir: downloads/code
    i18n_dir: :lang
    skip_render:

    # Writing
    new_post_name: :title.md # File name of new posts
    default_layout: post
    titlecase: false # Transform title into titlecase
    external_link: true # Open external links in new tab
    filename_case: 0
    render_drafts: false
    post_asset_folder: false
    relative_link: false
    future: true
    highlight:
    enable: true
    line_number: true
    auto_detect: false
    tab_replace:

    # Home page setting
    # path: Root path for your blogs index page. (default = '')
    # per_page: Posts displayed per page. (0 = disable pagination)
    # order_by: Posts order. (Order by date descending by default)
    index_generator:
    path: ''
    per_page: 5 # 设置主页中每页显示几篇文章
    order_by: -date

    # Category & Tag
    default_category: uncategorized
    category_map:
    tag_map:

    # Date / Time format
    ## Hexo uses Moment.js to parse and display date
    ## You can customize the date format as defined in
    ## http://momentjs.com/docs/#/displaying/format/
    date_format: YYYY-MM-DD
    time_format: HH:mm:ss

    # Pagination
    ## Set per_page to 0 to disable pagination
    per_page: 10 # 设置归档(archives)页面每页显示文章数
    pagination_dir: page

    # Extensions
    ## Plugins: https://hexo.io/plugins/
    ## Themes: https://hexo.io/themes/
    theme: landscape # 设置所用的主题,默认为 landscape

    # Deployment
    ## Docs: https://hexo.io/docs/deployment.html
    ## repository 之后的链接应为你之前创建的仓库的链接,后面跟上 .git 后缀,如下图,可直接复制仓库链接
    ## 类型为 git
    ## 分支为 master
    deploy:
    type: git
    repository: https://github.com/SummerFalls/SummerFalls.github.io.git
    branch: master

复制 repository 链接地址

6. 安装 Hexo 的必备扩展

  • 安装热更新支持包

    npm install hexo-browsersync –save

  • 安装 Hexo Git 支持包,以支持部署 Hexo 博客到 GitHub

    npm install hexo-deployer-git –save

  • 安装网站地图生成支持包(根目录生成 sitemap.xml 方便搜索引擎抓取)

    npm install hexo-generator-sitemap –save

7. 部署 Hexo 博客到 GitHub

  • 生成 Hexo 静态博客网页文件

    hexo g

  • 部署 Hexo 博客到 GitHub

    hexo d

    • 第一次执行本命令会弹出登录框,请登录你的 GitHub 帐号 如图所示:

登录 GitHub 帐号

  • 稍等片刻,待终端命令执行结束后,浏览器打开你的博客网页地址,如图:

    注意这一次网页地址为 _config.yml 文件中 url: 字段后跟随的网页地址(实际上就是你的 GitHub Pages 仓库名),在这里,我的地址就应该为:https://SummerFalls.github.io

部署后的博客

8. [可选] 设置 Hexo 博客域名解析

I. 设置域名解析

在设置自定义域名之前,请自行在域名服务商购买域名

这里以在阿里云购买的万网域名为例

  • 打开并登录 阿里云
  • 点击网页右上角的控制台
  • 找到 云解析 DNS,如图所示:

云解析 DNS

  • 点击自己购买的域名,进入 解析设置 页面
  • 点击 添加记录 按钮,设置如图所示:
    • 记录类型:CNAME
    • 主机记录:apex

      这里你可以改为自己喜欢的名称

    • 解析线路:默认
    • 记录值:summerfalls.github.io

      记录值改为你的 GitHub Pages 仓库名称

    • TTL:10分钟

解析设置

  • 点击 确定,之后解析添加成功

II. 修改 博客根目录 下的 _config.yml 文件

_config.yml
1
url: 'https://apex.linn.top'

III. 用 VS Code博客根目录 下的 source 目录下新建一个不带任何后缀名的 CNAME 文件

IV. 修改 CNAME 文件,文件内容为你的自定义博客网址

CNAME
1
apex.linn.top

V. 重新生成并部署 Hexo 博客

  • hexo clean

  • hexo g

  • hexo d

  • 之后便能通过自定义域名访问博客,如图所示:

自定义域名访问博客

9. [可选] 更换 Hexo 博客主题

这里推荐 Icarus 主题

GitHub 地址:https://github.com/ppoffice/hexo-theme-icarus

效果如图:

Icarus 主题效果

I. 更换步骤

  • 在终端中,确保为 博客根目录 的情况下,输入以下 git 命令,回车后等待安装完毕

    git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus

  • 修改 博客根目录 下的 _config.yml 文件

    _config.yml
    1
    theme: icarus
  • 清理之后重新生成并部署 Hexo 博客

    • hexo clean

    • hexo g

    • hexo d

  • 部署完毕后再刷新博客页面,发现主题更换成功,如图所示:

主题更换后的效果

II. 修改主题的 _config.yml 文件

Icarus 主题的根目录下,找到 _config.yml 文件,用 VS Code 修改

注意:关于文章末尾的打赏,也在本文件设置,同时需要指定支付宝微信收款码所处的地址,可以在 source 目录下新建一个 images 文件夹,在其中存放收款码图片,引用图片的方法如下所示:

_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
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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
# Version of the Icarus theme that is currently used
version: 2.6.0
# Path or URL to the website's icon
favicon: /images/favicon.svg
# Additional HTML meta tags in an array.
meta:
# Path or URL to RSS atom.xml
rss:
# Path or URL to the website's logo to be shown on the left of the navigation bar or footer
logo: /images/logo.svg
# Open Graph metadata
# https://hexo.io/docs/helpers.html#open-graph
open_graph:
# Facebook App ID
fb_app_id:
# Facebook Admin ID
fb_admins:
# Twitter ID
twitter_id:
# Twitter site
twitter_site:
# Google+ profile link
google_plus:
# Navigation bar link settings
navbar:
# Navigation bar menu links
menu:
主页: /
归档: /archives
分类: /categories
标签: /tags
关于: /about
# Navigation bar links to be shown on the right
links:
# GitHub:
# icon: fab fa-github
# url: 'https://github.com/SummerFalls'
# Footer section link settings
footer:
# Links to be shown on the right of the footer section
links:
# Creative Commons:
# icon: fab fa-creative-commons
# url: 'https://creativecommons.org/'
# Attribution 4.0 International:
# icon: fab fa-creative-commons-by
# url: 'https://creativecommons.org/licenses/by/4.0/'
# Download on GitHub:
# icon: fab fa-github
# url: 'https://github.com/ppoffice/hexo-theme-icarus'
# Article display settings
article:
# Code highlight settings
highlight:
# Code highlight themes
# https://github.com/highlightjs/highlight.js/tree/master/src/styles
# https://highlightjs.org/static/demo/
theme: vs2015
# Show code copying button
clipboard: true
# Default folding status of the code blocks. Can be "", "folded", "unfolded"
fold: unfolded
# Whether to show article thumbnail images
thumbnail: true
# Whether to show estimate article reading time
readtime: true
# Search plugin settings
# https://ppoffice.github.io/hexo-theme-icarus/categories/Plugins/Search
search:
# Name of the search plugin
type: insight
# Comment plugin settings
# https://ppoffice.github.io/hexo-theme-icarus/categories/Plugins/Comment
comment:
# Name of the comment plugin
type:
# Donation entries
# https://ppoffice.github.io/hexo-theme-icarus/categories/Donation/
donate:
-
# Donation entry name
type: alipay
# Qrcode image URL
qrcode: /images/Alipay.jpg
-
# Donation entry name
type: wechat
# Qrcode image URL
qrcode: /images/Wechat.jpg
# Share plugin settings
# https://ppoffice.github.io/hexo-theme-icarus/categories/Plugins/Share
share:
# Share plugin name
type:
# Sidebar settings.
# Please be noted that a sidebar is only visible when it has at least one widget
sidebar:
# left sidebar settings
left:
# Whether the left sidebar is sticky when page scrolls
# https://ppoffice.github.io/hexo-theme-icarus/Configuration/Theme/make-a-sidebar-sticky-when-page-scrolls/
sticky: true
# right sidebar settings
right:
# Whether the right sidebar is sticky when page scrolls
# https://ppoffice.github.io/hexo-theme-icarus/Configuration/Theme/make-a-sidebar-sticky-when-page-scrolls/
sticky: true
# Sidebar widget settings
# https://ppoffice.github.io/hexo-theme-icarus/categories/Widgets/
widgets:
-
# Widget name
type: profile
# Where should the widget be placed, left or right
position: left
# Author name to be shown in the profile widget
author: Tomy Stark
# Title of the author to be shown in the profile widget
author_title: 四海茫茫
# Author's current location to be shown in the profile widget
location: Earth, Solar System.
# Path or URL to the avatar to be shown in the profile widget
avatar: /images/avatar.jpg
# Email address for the Gravatar to be shown in the profile widget
gravatar:
# Whether to show avatar image rounded or square
avatar_rounded: true
# Path or URL for the follow button
follow_link: 'https://github.com/SummerFalls'
# Links to be shown on the bottom of the profile widget
social_links:
Github:
icon: fab fa-github
url: 'https://github.com/SummerFalls'
知乎:
icon: fab fa-zhihu
url: 'https://www.zhihu.com/people/TomyStark'
微博:
icon: fab fa-weibo
url: 'https://weibo.com/tomystark'
-
# Widget name
type: toc
# Where should the widget be placed, left or right
position: right
-
# Widget name
type: links
# Where should the widget be placed, left or right
position: left
# Links to be shown in the links widget
links:
博客 - 吴川斌: 'https://www.mr-wu.cn/'
博客 - 芯跳不止: 'http://www.mazirong.com/'
工作室 - Muse Lab: 'https://www.muselab-tech.com/'
工作室 - 屋脊雀: 'http://www.wujique.com/'
-
# Widget name
type: category
# Where should the widget be placed, left or right
position: right
-
# Widget name
type: tagcloud
# Where should the widget be placed, left or right
position: right
-
# Widget name
type: recent_posts
# Where should the widget be placed, left or right
position: left
-
# Widget name
type: archive
# Where should the widget be placed, left or right
position: right
-
# Widget name
type: tag
# Where should the widget be placed, left or right
position: right
# Other plugin settings
plugins:
# Enable page animations
animejs: true
# Enable the lightGallery and Justified Gallery plugins
# https://ppoffice.github.io/hexo-theme-icarus/Plugins/General/gallery-plugin/
gallery: true
# Enable the Outdated Browser plugin
# http://outdatedbrowser.com/
outdated-browser: false
# Enable the MathJax plugin
# https://ppoffice.github.io/hexo-theme-icarus/Plugins/General/mathjax-plugin/
mathjax: true
# Show the back to top button on mobile devices
back-to-top: true
# Google Analytics plugin settings
# https://ppoffice.github.io/hexo-theme-icarus/Plugins/General/site-analytics-plugin/#Google-Analytics
google-analytics:
# Google Analytics tracking id
tracking_id:
# Baidu Analytics plugin settings
# https://ppoffice.github.io/hexo-theme-icarus/Plugins/General/site-analytics-plugin/#Baidu-Analytics
baidu-analytics:
# Baidu Analytics tracking id
tracking_id:
# Hotjar user feedback plugin
# https://ppoffice.github.io/hexo-theme-icarus/Plugins/General/site-analytics-plugin/#Hotjar
hotjar:
# Hotjar site id
site_id:
# Show a loading progress bar at top of the page
progressbar: true
# BuSuanZi site/page view counter
# https://busuanzi.ibruce.info
busuanzi: true
# CDN provider settings
# https://ppoffice.github.io/hexo-theme-icarus/Configuration/Theme/speed-up-your-site-with-custom-cdn/
providers:
# Name or URL of the JavaScript and/or stylesheet CDN provider
cdn: jsdelivr
# Name or URL of the webfont CDN provider
fontcdn: google
# Name or URL of the webfont Icon CDN provider
iconcdn: fontawesome
  • 清理之后重新生成并部署 Hexo 博客
    • hexo clean

    • hexo g

    • hexo d

III. 添加自定义 404 Not Found 页面

  • 在终端中执行以下命令,创建一个 404page 页面

    hexo new page “404”

  • VS Code 编辑 \source\404\ 目录下的 index.md 文件

    • 其中字段 "thumbnail: " 后的图片需要自行存放在对应目录并改为对应名称,后缀名称大小写敏感

    • 文件内容如下所示(可自定义添加更丰富的内容)

      index.md
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      ---
      title: 404 Not Found 该页面不存在
      date: 2019-09-23 15:40:38
      thumbnail: /images/IMG_6274.JPG
      toc: false
      permalink: /404
      ---

      <div style = "text-align: center; margin: auto; width: 100%;">

      ## **很抱歉,您所访问的地址并不存在。**

      </div>
  • 清理之后重新生成并部署 Hexo 博客

    • hexo clean

    • hexo g

    • hexo d

  • 部署完毕后再次访问博客,地址后跟上不存在的文章,会自动跳转到刚刚自定义的 404 页面,如图:

404 页面

IV. 添加关于页面

  • 在终端中执行以下命令,创建一个 aboutpage 页面

    hexo new page “about”

  • VS Code 编辑 \source\about\ 目录下的 index.md 文件

    • 其中字段 "thumbnail: " 后的图片需要自行存放在对应目录并改为对应名称,后缀名称大小写敏感

    • 文件内容如下所示(可自定义添加更丰富的内容)

      index.md
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      ---
      title: 关于我 About Me
      date: 2019-09-19 15:59:10
      thumbnail: /images/Car.jpg
      ---

      - <i class="fab fa-fort-awesome-alt"></i> 职业: 复制粘贴工程师
      - <i class="fas fa-at"></i> 邮箱: xxxxx@qq.com
      - <i class="fab fa-qq"></i> QQ: 123456789
      - <i class="fab fa-weixin"></i> WeChat: XXXXXX
      - <i class="fab fa-playstation"></i> PSN ID: XXXXXX
      - 星座: 天蝎座
      - 语言: C/C++/Java/HTML/CSS
      - IDE: [VS Code](https://code.visualstudio.com/), [Vivado Design Suite HLx](https://china.xilinx.com/products/design-tools/vivado.html)
      - EDA: [Altium Designer](https://www.altium.com.cn/), [EasyEDA](https://lceda.cn/)
      - 兴趣: 开源硬件, 开源软件, HiFi, 美食, 音乐
      - 游戏平台: <i class="fab fa-playstation"></i> Play Station 4, Nintendo Switch
      - 运动: 游泳, 骑行
      - 正在学习中的: Altium Designer, TouchGFX
  • 清理之后重新生成并部署 Hexo 博客

    • hexo clean

    • hexo g

    • hexo d

  • 部署完毕后再次访问博客,关于 页面已经可以正常访问,如图:

关于页面

V. Icarus 主题小问题修改

  • footer 页脚高度过高的问题

    VS Code 编辑主题目录下的 style.styl 文件

    路径:\themes\icarus\source\css\style.styl

    为文件中的 .footer 类添加一行属性,如下所示:

    style.styl
    1
    padding-bottom: 3rem

    添加属性后的 .footer 类如下所示:

    style.styl
    1
    2
    3
    4
    5
    6
    .footer
    background: white
    padding-bottom: 3rem
    .field
    .button
    background: transparent

10. Hexo 模板

\scaffolds 目录下的 3 个文件分别为草稿模板页面模板文章模板,修改其内容以在每次新建文章或页面时,能够自动添加部分模板内容。

  • page.md

    page.md
    1
    2
    3
    4
    5
    6
    ---
    title: {{ title }}
    date: {{ date }}
    thumbnail: /images/flower.jpg
    toc: false
    ---
  • post.md

    post.md
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    ---
    title: {{ title }}
    date: {{ date }}
    thumbnail: /images/flower.jpg
    toc: true
    categories:
    - uncategorized
    tags:
    ---

    <!--more-->

    <div style = "text-align: center; margin: auto; width: 100%;">

    ![Car](../images/Car.jpg)

    </div>

11. 写文章

注意:关于文章图片,若还没有创建 images 文件夹,可以在 source 目录下新建一个 images 文件夹,在其中存放图片文件。

这里以创建一篇标题名称为 Hello Hexo 的文章为例:

  • 在终端中执行以下命令,创建一篇文章

    hexo new “Hello Hexo”

  • VS Code 编辑 \source\_posts 目录下的 Hello-Hexo.md 文件

    • 其中字段 "thumbnail: " 后的图片需要自行存放在对应目录并改为对应名称,后缀名称大小写敏感

    • 文件内容如下所示:

      Hello-Hexo.md
      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
      ---
      title: Hello-Hexo
      date: 2019-09-19 15:59:10
      thumbnail: /images/flower.jpg
      toc: true
      categories:
      - Blog
      - Hexo
      tags:
      - Hexo
      ---

      ## <i class="fab fa-fort-awesome-alt"></i> 你好 Hexo

      正文...

      <!--more-->

      这里是在主页被隐藏的内容...

      <div style = "text-align: center; margin: auto; width: 100%;">

      ![Car](../images/Car.jpg)

      </div>
  • 清理之后重新生成并部署 Hexo 博客

    • hexo clean

    • hexo g

    • hexo d

  • 部署完毕后再次访问博客,刚刚发布的文章已经出现在主页上,如图:

添加新文章

12. 至此所有步骤已完成

评论