Setting up Hexo Blog on github.io

Hexo

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

1
2
3
micromamba env create -n hexo
micromamba activate hexo
micromamba install conda-forge::nodejs
  • nodejs 22.8.0
  • git is installed

底下是官方寫的 Quick Start，只需要短短五行指令就可以讓部落格跑起來。

1
2
3
4
5
npm install hexo-cli -g
hexo init blog
cd blog
npm install
hexo server

display 

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

  • 如果你已經有部落格資料夾，那麼你可以跳過“hexo init blog”

Useful commands

  • 清理 hexo ,类似于清理编译结果，例如 执行命令 hexo clean
  • 生成静态页面, 执行命令 hexo g
  • 启动服务，执行命令 hexo s ,默认在 4000 端口启动，访问本地4000端口即可查看本地网站
1
2
3
4
5
hexo new 'post name'
hexo clean
hexo generate    # hexo g
hexo server      # hexo s
hexo deploy      # hexo d

Theme: Fluid

一款 Material Design 风格的主题

An elegant Material-Design theme for Hexo

Step 1

下载 最新 release 版本 解压到 themes 目录，并将解压出的文件夹重命名为 fluid。

Step 2

1
2
3
4
5
如下修改 Hexo 博客目录中的 **_config.yml**：

theme: fluid  # 指定主题

language: zh-CN  # 指定语言，会影响主题显示的语言，按需修改

Step 3

首次使用主题的「关于页」需要手动创建：

1
hexo new page about

创建成功后，编辑博客目录下 /source/about/index.md，添加 layout 属性。

修改后的文件示例如下：

1
2
3
4
5
6
---
title: about
layout: about
---

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

Filename

https://hexo.io/docs/writing

By default, Hexo uses the post title as its filename. You can edit the new_post_name setting in _config.yml to change the default filename. For example, :year-:month-:day-:title.md will prefix filenames with the post creation date. You can use the following placeholders:

1
2
3
# Writing
## new_post_name: :title.md # File name of new posts
new_post_name: :year-:month-:day-:title.md

in **_config.yml** under themes/fluid.

math

1
2
3
$ micromamba install conda-forge::pandoc
$ npm uninstall hexo-renderer-marked --save
$ npm install hexo-renderer-pandoc --save

and, 

1
2
3
4
math:
  enable: true
  specific: false
  engine: mathjax

mermaid

1
$ npm install hexo-filter-mermaid-diagrams

Deploy to github

设置部署类型和 github 仓库位置和主分支，到网站配置文件 _config.yml 中修改如下：

表示部署类型为 git；

仓库为 git@github.com:username/github.io.git ，替换成你的仓库即可；

分支为 master 主分支；

1
2
3
4
deploy:
  type: git
  repo: git@github.com:waipangsze/waipangsze.github.io.git
  branch: main

安装 git 扩展模块 hexo-deployer-git，到 blog 目录中执行命令：

1
$ npm install hexo-deployer-git --save

执行命令

1
$ hexo d

部署到上面创建的 github 仓库中。

这一步就是向 github 仓库的master 分支提交文件，所以本地要有权限向你的 github 仓库提交。需要 sshkey,至于怎么添加 sshkey，如果不清楚，查一下就知道了。

1
2
3
4
To github.com:waipangsze/waipangsze.github.io.git
 + 4aa63c5...24ec1e5 HEAD -> main (forced update)
Branch 'master' set up to track remote branch 'main' from 'git@github.com:waipangsze/waipangsze.github.io.git'.
INFO  Deploy done: git

hexo blog 多設備同步

From hexo博客多设备同步

github上的repo创建了两个分支，master保存静态页面，hexo用于保存网站的全部文件。

  • 将旧环境中的文件上传到github的hexo分支：
  • github上切换到hexo分支，git clone仓库到本地。
  • 此时本地会多出一个username.github.io文件夹，命令行cd进去，删除除.git文件夹（如果你看不到这个文件夹，说明是隐藏了。windows下需要右击文件夹内空白处，点选’显示/隐藏 异常文件’，Mac下我就不知道了）外的其他文件夹。
  • 命令行git add -A把工作区的变化（包括已删除的文件）提交到暂存区（ps:git add .提交的变化不包括已删除的文件）。
  • 命令行git commint -m "some description"提交。
  • 命令行git push origin hexo推送到远程hexo分支。此时刷下github，如果正常操作，hexo分支应该已经被清空了。
  • 复制本地username.github.io文件夹中的.git文件夹到hexo项目根目录下。此时，hexo项目已经变成了和远程hexo分支关联的本地仓库了。而username.github.io文件夹的使命到此为止，你可以把它删掉，因为我们只是把它作为一个“中转站”的角色。以后每次发布新文章或修改网站样式文件时，git add . & git commit -m "some description" & git push origin hexo即可把环境文件推送到hexo分支。然后再hexo g -d发布网站并推送静态文件到master分支。
1
2
3
4
5
6
7
8
9
10
11
git clone git@github.com:waipangsze/waipangsze.github.io.git
waipangsze.github.io/
git switch hexo 
git log 
cp -r .git ../../blog/ # delete all files except .git
cd ../../blog/
cat .gitignore 
git status
git add .
git commit -a # git commit -m "xxxx"
git push origin hexo

新环境

这部分应该要简单一点，如果你已经搭建过一个hexo博客的话。

  • 新电脑上安装node.js和git。
  • 安装hexo：npm install -g hexo-cli。
  • clone远程仓库到本地 git clone git@github.com:username/username.github.io.git。
  • 根据packge.json安装依赖npm install。
  • 本地生成网站并开启博客服务器：hexo g & hexo s。如果一切正常，此时打开浏览器输入http://localhost:4000/ 已经可以看到博客正常运行了。

在两台电脑上的同步操作

至此，迁移工作已完成，在两台电脑之间的同步操作如下：

  • git pull从远程hexo分支拉取最新的环境文件到本地，可以理解为svn的更新操作。比如在公司写了博客，回家在电脑上也要写需要先执行这一步操作。
  • 文章写完，要发布时，需要先提交环境文件，再发布文章。按以下顺序执行命令：git add .、git commit -m "some descrption"、git push origin hexo、hexo g -d。

Upload to github

1
2
3
4
5
6
git pull --rebase # do this at the beginning
git status
git add . # add all files
git commit --amend
# git push (-f)
git push -u origin hexo

相關連結 icon

官方的 icon 圖示，均引用自目前做網站最多人使用的免費 icon 圖庫 Font Awesome，Font Awesome 是一個基於CSS和LESS的字體和圖示工具套件。它由Dave Gandy製作，用於Twitter Bootstrap，後來被整合到BootstrapCDN 中。Font Awesome在使用第三方Font Scripts的網站中佔有20％的市場份額，排在Google字體之後的第二位。

便签

可选便签：

  • primary
  • secondary
  • success
  • danger
  • warning
  • info
  • light

primary: 文字 或者 markdown 均可

secondary: 文字 或者 markdown 均可

success: 文字 或者 markdown 均可

danger: 文字 或者 markdown 均可

warning: 文字 或者 markdown 均可

info: 文字 或者 markdown 均可

light: 文字 或者 markdown 均可

1
2
3
{% note primary %}
primary: 文字 或者 `markdown` 均可
{% endnote %}

折叠块

使用折叠块，可以折叠代码、图片、文字等任何内容，你可以在 markdown 中按如下格式：

需要折叠的一段内容，支持 markdown

1
2
3
{% fold info @title %}
需要折叠的一段内容，支持 markdown
{% endfold %}

多张图片按一定布局组合显示

1
2
3
4
5
6
7
{% gi 5 3-2 %}
![1](https://i.imgur.com/RwpxULg.png)
![2](https://i.imgur.com/RwpxULg.png)
![3](https://i.imgur.com/RwpxULg.png)
![4](https://i.imgur.com/RwpxULg.png)
![5](https://i.imgur.com/RwpxULg.png)
{% endgi %}
1
2
3
4
5

展示PDF

1
npm install --save hexo-pdf

and

1
{% pdf ../pdf/xxx.pdf %}

統計網站的造訪地區和IP

  1. 通过 clustermaps 统计 Hexo 网站的访问地区和 IP

clustrmaps.com 是美國的資料網站。

網址提供了產生訪客地址分佈圖的程式碼，可以嵌入到網站或部落格中，來顯示來自世界各地訪客的即時地圖，有助於發展您隱藏的興趣社群。最重要的是，這個功能是免費的，能夠滿足個人網站的需求。

  • 配置 clustrmaps
    • 網站註冊後，請造訪 Enter your website address 新增自己的網站地址，選擇免費的服務。
    • 選擇自己喜歡的外掛格式，現在 Hexo 的 Next 兩個主題都是支援的，比較喜歡 Map widget 的主題。
    • 點選選擇後，拷貝網站出現的腳本 javascript 程式碼，貼到主題下某個位置。
    • 我把它放在 about.ejs or index.md 的最後。
    • 重新部署網站，您就可以在首頁看到即時訪客來源圖，如我的網站首頁所示。另外，點擊地圖，可以看到更詳細的信息，包括訪客的地圖、瀏覽設備以及 IP。

導入影片

The easiest way to get the correct link is to right-click on the YouTube video and select copy embed code.

1
<iframe width="560" height="315" src="xxx" ......></iframe>

支持二级菜单（下拉菜单）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 导航栏菜单，可自行增减，key 用来关联 languages/*.yml，如不存在关联则显示 key 本身的值；icon 是 css class，可以省略；增加 name 可以强制显示指定名称
# Navigation bar menu. `key` is used to associate languages/*.yml. If there is no association, the value of `key` itself will be displayed; if `icon` is a css class, it can be omitted; adding `name` can force the display of the specified name
menu:
  - { key: "home", link: "/", icon: "iconfont icon-home-fill" }
  - { key: "archive", link: "/archives/", icon: "iconfont icon-archive-fill" }
  - { key: "category", link: "/categories/", icon: "iconfont icon-category-fill" }
  - { key: "tag", link: "/tags/", icon: "iconfont icon-tags-fill" }
  - { key: "links", link: "/links/", icon: "iconfont icon-link-fill" }
  - { key: "Bookmarks", link: "/bookmark/", icon: "iconfont icon-bookmark"}
  - { key: "about", link: "/about/", icon: "iconfont icon-user-fill", name: 'About Me'}
  - {
  key: 'Docs',
  icon: 'iconfont icon-books',
  submenu: [
    #{ key: 'Physics', link: '/archives/' },
    #{ key: 'Mathematics', link: '/tags/' },
    { key: 'Meteorology', link: '/categories/Meteorology/', icon: "iconfont icon-plan" }
  ]
  }

這裡我們使用/categories/Meteorology/中的鏈接，但它只是標題，沒有封面圖片。如何顯示封面圖片？

On category.ejs

這裡我們使用/categories/Meteorology/中的鏈接，但它只是標題，沒有封面圖片。如何顯示封面圖片？

它調用了程式碼,

1
<%- partial('_partials/archive-list.ejs', { params: { key: page.layout, postTotal: cat ? cat.posts.length : 0 } }) %>

建立一個 my-list.ejs 並使用它的程式碼，

1
<%- partial('_partials/my-list.ejs', { params: { key: page.layout, postTotal: cat ? cat.posts.length : 0 } }) %>

my-list.ejs 是什麼？ （複製自index.ejs，其中一部分）

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
<div class="list-group">
  <p class="h4"><%= __(params.key + '.post_total', params.postTotal) %></p>
  <hr>
  <% var dateCursor %>
  <% page.posts.each(function (post) { %>
    <div class="row mx-auto index-card">
      <% var post_url = url_for(post.path), index_img = post.index_img || theme.post.default_index_img %>
      <% if (index_img) { %>
        <div class="col-12 col-md-4 m-auto index-img">
          <a href="<%= post_url %>" target="<%- theme.index.post_url_target %>">
            <img src="<%= url_for(index_img) %>" alt="<%= post.title %>">
          </a>
        </div>
      <% } %>
      <article class="col-12 col-md-<%= index_img ? '8' : '12' %> mx-auto index-info">
        <h2 class="index-header">
          <% if (theme.index.post_sticky && theme.index.post_sticky.enable && post.sticky > 0) { %>
            <i class="index-pin <%= theme.index.post_sticky && theme.index.post_sticky.icon %>" title="Pin on top"></i>
          <% } %>
          <a href="<%= post_url %>" target="<%- theme.index.post_url_target %>">
            <%= post.title %>
          </a>
        </h2>
  
        <% var excerpt = post.description || post.excerpt || (theme.index.auto_excerpt.enable && !post.encrypt && post.content) %>
        <a class="index-excerpt <%= index_img ? '' : 'index-excerpt__noimg' %>" href="<%= post_url %>" target="<%- theme.index.post_url_target %>">
          <div>
            <%- strip_html(excerpt).substring(0, 200).trim().replace(/\n/g, ' ') %>
          </div>
        </a>
  
        <div class="index-btm post-metas">
          <% if (theme.index.post_meta.date) { %>
            <div class="post-meta mr-3">
              <i class="iconfont icon-date"></i>
              <time datetime="<%= full_date(post.date, 'YYYY-MM-DD HH:mm') %>" pubdate>
                <%- date(post.date, config.date_format) %>
              </time>
            </div>
          <% } %>
          <% if (theme.index.post_meta.category && post.categories.length > 0) { %>
            <div class="post-meta mr-3 d-flex align-items-center">
              <i class="iconfont icon-category"></i>
              <%- partial('_partials/category-chains', { categories: post.categories, limit: 1 }) %>
            </div>
          <% } %>
          <% if (theme.index.post_meta.tag && post.tags.length > 0) { %>
            <div class="post-meta">
              <i class="iconfont icon-tags"></i>
              <% post.tags.each(function(tag){ %>
                <a href="<%= url_for(tag.path) %>">#<%- tag.name %></a>
              <% }) %>
            </div>
          <% } %>
        </div>
      </article>
    </div>
  <% }) %>
</div>

<%- partial('_partials/paginator') %>

範例網站

  1. zkqiang's blog
  2. 秉烛夜读
    1. https://github.com/fantasyhh/fantasyhh.github.io
  3. 來點鳥 blog
  4. 吃白饭的休伯利安号
  5. Yu's Space
  6. Justlovesmile
  7. zsyyblog.com
  8. Yangyy's Life
  9. Bensz’s blog
  10. 七号中微子
  11. 张赛东
  12. Fl0w3r | Hexo-Fluid 博客建站記錄
  13. 南科大地空系空间物理研究生

References:

  1. Hexo Fluid Docs
  2. 一个简单而轻量级的 Hexo 主题
  3. 用 Hexo 和 Github Pages 建立部落格吧
  4. 用 GitHub + Hexo 免费搭建博客，保姆级教程
  5. Hexo中插入mermaid diagrams
  6. hexo博客多设备同步
  7. 多台电脑同步更新Hexo博客
github
#github.io #blog #Hexo
Setting up Hexo Blog on github.io
https://waipangsze.github.io/2024/09/13/Hexo/
Author
wpsze
Posted on
September 13, 2024
Updated on
January 15, 2025
Licensed under