如何用Hexo搭建个人Blog

Hexo是一个非常好用的博客框架。提供将Markdown渲染成Html博客的功能，并兼具丰富的主题。本文简单整理部署Hexo博客流程，以供参考。

使用Github Pages

新建一个以<username>.github.io为名的repository，public和private都可。

之后，在Settings中找到Github Pages选项：

打开对应开关并选择主题即可。

注意：空的Repo不存在master branch，无法开启Github Pages，至少需要加入一个文件（如README.md）。

<username>.github.io 已被占用

如果默认的链接已经存在个人主页了，可以另起一个任意名称的Repo（这里以test为例）。

此时Pages则会自动被放到<username>.github.io/test/域名下。

选择主题后，可以很快捷地生成一个pages页面。

Remarks

• 可以在test > environment中查看编译情况。确定最新的commit已经编译完成后，若浏览器没有刷新，建议用Incognito window查看。
• <username>.github.io的页面只能编译master branch，其他页面也可编译master下的/docs目录。但是多branch是不支持的。推荐Enforce HTTPS。

---

使用Hexo

安装Git Bash

从官网下载Git Bash。

$ git --version
git version 2.45.1.windows.1

顺便设置Git

$ git config --global user.name <YourName>
$ git config --global user.email <YourEmail>
$ git config --global user.password <YourPassword>

安装Node.js

从官网下载Node.js。

$ node -v
v20.13.1

$ npm -v
10.5.2

安装Hexo

$ npm install -g hexo-cli
$ hexo -v

初始化工作目录

注意，目录必须为空，否则会报错。

$ mkdir blog
$ cd blog
$ hexo init
$ npm install

目录结构如下

.
├── _config.yml                     // 全局设置
├── package.json                    // npm依赖包
├── public                          // 部署的网页
├── scaffolds                       // 新建模板
├── source                          // 编译public的源文件
│   ├── _drafts
│   └── _posts
└── themes

预览网页

可以执行以下指令

hexo clean && hexo g && hexo s 

作用分别是清除缓存（clean）、由md生成html文件（generate），以及部署到本地4000端口（server）。
在浏览器中键入localhost:4000以预览网页。

至此，本地Hexo的部署基本完成。按Ctrl+C以可以关闭部署。

Remark：

• 如果4000端口被占用，部署时用hexo s -p 5000指定空闲的端口。
• 如果只修改md文件，只执行hexo g重新生成Html即可。

---

修改主题

本次使用主题为Icarus。具体按照文档安装即可。

$ npm install hexo-theme-icarus
$ hexo config theme icarus

该主题的配置文件主要在./_config.yml与./_config.icarus.yml中。

_config.yml >folded

title: <Title>                # 显示在标签栏
subtitle: <SubTitle>          # 暂不清楚在哪里显示
description: ''
keywords: null
author: <Author>              # 文章作者及底部版权
language: zh-CN               # 语言
timezone: Hongkong            # 时区
url: <URL>                    # 链接
permalink: ':year/:month/:day/:title/'
permalink_defaults: null
pretty_urls:
  trailing_index: true
  trailing_html: true
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories
code_dir: downloads/code
i18n_dir: ':lang'
skip_render: null
new_post_name: ':title.md'
default_layout: post
titlecase: false
external_link:
  enable: true
  field: site
  exclude: ''
filename_case: 0
render_drafts: false
post_asset_folder: true
relative_link: false
future: true
syntax_highlighter: highlight.js
highlight:
  line_number: true
  auto_detect: false
  tab_replace: ''
  wrap: true
  hljs: false
prismjs:
  preprocess: true
  line_number: true
  tab_replace: ''
index_generator:
  path: ''
  per_page: 10
  order_by: '-date'
default_category: uncategorized
category_map: null
tag_map: null
meta_generator: true
date_format: YYYY-MM-DD
time_format: HH:mm:ss
updated_option: mtime
per_page: 10
pagination_dir: page
include: null
exclude: null
ignore: null
theme: icarus               # 主题自动配置
deploy:
  type: git
  repository: <URL>         # Git Pages 链接
  branch: master

_config.icarus.yml >folded

...
# Path or URL to the website's logo
logo: /img/<LogoFile>.png
...
# Article related configurations
article:
    # Code highlight settings
    highlight:
        # Code highlight themes
        # https://github.com/highlightjs/highlight.js/tree/master/src/styles
        theme: atom-one-dark
        # Show copy code button
        clipboard: true
        # Default folding status of the code blocks. Can be "", "folded", "unfolded"
        fold: unfolded
    # Whether to show estimated article reading time
    readtime: true
    # Whether to show updated time. For "auto", shows article update time only when page.updated is set and it is different from page.date
    update_time: true
    # Article licensing block
    licenses:
        Creative Commons:
            icon: fab fa-creative-commons
            url: https://creativecommons.org/
        Attribution:
            icon: fab fa-creative-commons-by
            url: https://creativecommons.org/licenses/by/4.0/
        Noncommercial:
            icon: fab fa-creative-commons-nc
            url: https://creativecommons.org/licenses/by-nc/4.0/
...
# Sidebar configurations.
# Please be noted that a sidebar is only visible when it has at least one widget
sidebar:
    # Left sidebar configurations
    left:
        # Whether the sidebar sticks to the top when page scrolls
        sticky: false
    # Right sidebar configurations
    right:
        # Whether the sidebar sticks to the top when page scrolls
        sticky: false
# Sidebar widget configurations
# http://ppoffice.github.io/hexo-theme-icarus/categories/Widgets/
widgets:
    # Profile widget configurations
    -
        # Where should the widget be placed, left sidebar or right sidebar
        position: left
        type: profile
        # Author name
        author: <Name>
        # Author title
        author_title: <Title>
        # Author's current location
        location: <Location>
        # URL or path to the avatar image
        avatar: <Icon>
        # Whether show the rounded avatar image
        avatar_rounded: false
        # Email address for the Gravatar
        gravatar: 
        # URL or path for the follow button
        follow_link:
        # Links to be shown on the bottom of the profile widget
        social_links:
            Github:
                icon: fab fa-github
                url: <URL>
            Facebook:
                icon: fab fa-facebook
                url: <URL>
            Linkedin:
                icon: fa-brands fa-linkedin
                url: <URL>
            ORCID:
                icon: fa-brands fa-orcid
                url: <URL>
            # RSS:
            # icon: fas fa-rss
            # url: /
...

部署到Github上

首先确认安装npm install hexo-deployer-git，之后修改./_config.yml中

deploy:
  type: git
  repository: https://github.com/<user>/<repo>
  branch: master

最后执行

hexo clean && hexo g && hexo d

可以在github网页上看到效果。

备份源文件

建议将md源文件与网页分开部署，例如使用不同的分支或不同的repo，否则源文件可能丢失。

$ cd blog
$ git init
$ git add source
$ git add _config.*
$ git commit -m "initial commit"
$ git remote add origin https://<YourName>@github.com/<YourName>/<Repo>
$ git push -u origin master

---

撰写文章

基本命令是hexo new [post/page/draft] "<title>"，在config中默认了default_layout: post，因此也可以hexo new "<title>"来新建一篇文章。

执行后，会在./source/_posts目录中新建一个<title>文件夹与<title>.md文件。默认的格式来源于./scaffolds/post.md。文件头一般是

---
title: 
date: 
toc: true
tags:
  - TAG
categories:
  - [1ST, 2ND]
relative_link: true
---

插入图片

要依照相对路径引用对应目录的图片比较复杂，需要在文章头开启relative_link，并通过如下方式。

...setting...
relative_link: true
---
...text...
{% asset_img img_name "NAME" %}

插入Bilibili播放器

官方分享连接是

<iframe src="//player.bilibili.com/player.html?isOutside=true&aid=AID&bvid=BVID&cid=CID&p=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"></iframe>

但是不太好用。可以先在md文件中用JavaScript定义如下函数

putBilibili >folded

<script type="text/javascript">
  function putBilibili(aid, pid) {
    const player = new URL('https://www.bilibili.com/blackboard/html5mobileplayer.html');
    player.searchParams.append('aid', aid);
    player.searchParams.append('p', pid || 1);
    player.searchParams.append('danmaku', 0);

    var iframe = document.createElement('iframe');
    iframe.setAttribute('src', player.toString());
    iframe.setAttribute('scrolling', "no");
    iframe.setAttribute('border', "0");
    iframe.setAttribute('frameborder', "no");
    iframe.setAttribute('framespacing', "0");
    iframe.setAttribute('allowfullscreen', "true");
    iframe.setAttribute('width', "100%");
    iframe.setAttribute('onload',"javascript:(function(o){o.style.height=o.scrollWidth*0.64+'px';}(this));");

    document.write(iframe.outerHTML);
  }
</script>

然后在文中可以通过以下命令插入

<script>putBilibili(aid, pid)</script>

具体区别如下

外链播放器

新版本外链播放器player.bilibili.com/player.html点任何地方都会跳转到B站，此外，代码中有如下片段

const mobileUrl = '//www.bilibili.com/blackboard/webplayer/mbplayer.html';

在手机上会回溯到mbplayer，导致各种参数失效。
换成了旧版播放器https://www.bilibili.com/blackboard/html5mobileplayer.html，比较简单实用。

配置项

只通过番号aid和P号pid来定位视频，P号从1P开始。关闭了弹幕，其他参数一致。

宽高调整

为了在手机与电脑上都有合适的长宽，将宽设置成100%，并通过onload函数动态调整高为0.64宽。因为包含脚本，需要以document.write来实现。