Hexo 框架

介绍

使用

快速搭建

  • 快速搭建（以 butterfly 主题为例）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 安装 Hexo
npm install -g hexo-cli

# 项目初始化
hexo init hexo-demo & cd $_  # 方式 1
mkdir hexo-demo & cd $_ & hexo init  # 方式 2

# 安装依赖
npm i

# 安装主题
# 非 butterfly，建议将 theme 中的 .git 删除
git clone -b dev https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
# 拷贝主题配置文件到根目录；非 butterfly 不一定适用
cp /butterfly/_config.yml _config.butterfly.yml

# 安装主题依赖
npm i hexo-theme-butterfly --save

# 将 CNAME 文件放入 source 目录，以解析域名
  • 目录结构
1
2
3
4
5
6
├── _config.yml   # 配置文件
├── package.json  # 应用信息
├── scaffolds/    # 模板文件夹
├── source/       # 源文件夹
|   └── _posts/   # post 文件夹；md 文档可直接放于此，或归类成子目录
└── themes/       # 主题文件夹
  • 配置文件
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 配置文件
_config.yml              # 全局配置文件
themes/XXX/_config.yml   # 主题配置文件

# _config.yml 基本内容
title                    # 网站标题
subtitle                 # 副标题
description              # 网站描述
keywords                 # 网站关键词
author                   # 作者
language                 # 语言
timezone                 # 时区
url                      # 网址
theme                    # 主题；butterfly 等

# _config.theme.yml` 内容
# 自定义修改

常用命令

Hexo 命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 构建
hexo g  # hexo generate; npm run build
hexo g --watch  # 监视文件变动
hexo g --debug  # debug

# 实时预览
hexo s  # hexo server; npm run server
hexo s -p 5000  # 更改端口

# 部署
hexo d  # hexo deploy; npm run deploy
hexo g -d  # 构建后部署

# 清除缓存文件 db.json 和静态文件 public/
hexo clean  # hexo cl

部署

  • 设置 _config.yml 中的 deploy 选项（需安装 hexo-deployer-git 插件）
1
2
3
4
5
deploy:
  type: git
  # repo public private 都可以
  repository: [email protected]:username/repo.git
  branch: main
  • Github Actions 示例
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
name: Hexo deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - name: Use latest Node.js
        uses: actions/setup-node@v4
        with:
          node-version: latest
      - name: Cache NPM dependencies
        uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{ runner.OS }}-npm-cache
          restore-keys: |
            ${{ runner.OS }}-npm-cache
      - name: Install Dependencies
        run: npm install
      - name: Build
        run: npm run build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

插件

  • 参考：hexo 使用记录 - 鹤翔万里的笔记本

  • hexo-generator-index/archive/category/tag：初始化 Hexo 项目会自动安装；生成主页 / 归档 / 分类 / 标签文件夹

  • hexo-abbrlink：生成短链接，而非 post 中的 md 文件名

1
2
3
4
5
6
# permalink: :year/:month/:day/:title/
permalink: posts/:abbrlink.html
permalink_defaults:
pretty_urls:
  trailing_index: true # Set to false to remove trailing 'index.html' from permalinks
  trailing_html: true # Set to false to remove trailing '.html' from permalinks
  • hexo-blog-encrypt：文章加密，只需要在 md 的文件 Front Matter 加上：
1
password: ...
  • hexo-generator-feed：生成 RSS 订阅 xml 文件
1
2
3
4
5
feed:
  enable: true
  type: atom
  path: atom.xml
  limit: 20
  • hexo-generator-index-pin-top：文章置顶，只需要在 md 的文件 Front Matter 加上：
1
top: true

  • hexo-generator-search/searchdb：本地搜索设置

  • hexo-algoliasearch 或 hexo-algolia：Algolia 搜索；更美观（Hexo butterfy，Docusaurus 支持，MkDocs 将支持）

  • hexo-tag-publications：由 bib 文件生成论文统计与信息展示网页（可单个、全部论文）

    • 在页面添加论文概要图片，在 bib 文件中的论文对应条目下添加 image 参数

主题设置

  • butterfly 主题文章置顶 front-matter 参数：sticky，数值越大，置顶优先级越大
  • matery 主题文章置顶 front-matter 参数：top，数值为 true 或 false

butterfly

参考：

  • 菜单栏 menu（分类、标签、存档；友链、关于、音乐、视频、相册等暂无必要）
  • 网站 logo、个人头像、social 相关信息
  • 代码
  • 目录
  • banner 图片
  • 文章封面（Front Matter 中 cover 参数值为空，表示随机封面）
  • 评论系统（暂无必要）
  • 搜索系统（Algolia）
  • 页面加载效果
  • post 元信息（分类、标签、时间、字数统计、需阅读时间等）
  • 侧边栏（butterfly）
  • Footer 页脚信息
  • 内容复制时、文章底部版权相关信息（内容复制建议不加版权信息）
  • 日期过期提醒（noticeOutdate；失效？）
  • 图片懒加载
  • 相册（暂无必要）
  • 右下角功能按钮（深/浅色切换，直达页面顶部等功能）
  • 音乐、视频页面（音乐可全局吸底）
  • 添加 RSS 订阅功能：为Butterfly主题添加RSS订阅 - InsectMk的个人空间

自定义修改 Footer 页脚信息：themes/butterfly/layout/includes/footer.pug

matery

参考：

已解决/实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- markdown 中插入 B 站视频语法格式 --> 
<div 
     style="position: relative; width: 100%; height: 0; padding-bottom: 75%;">
    <iframe 
            src="//player.bilibili.com/player.html?aid=984726281&bvid=BV1Nt4y1n7hv&cid=807808976&page=1"
            scrolling="no" 
            border="0" 
            frameborder="no" 
            framespacing="0" 
            allowfullscreen="true" 
            style="position: absolute; width: 100%;height: 100%; left: 0; top: 0;"> 
    </iframe>
</div>

待解决/实现：