致远

致远是一款 Hexo 主题，专门为个人主页及多学科领域博主设计

演示站：

特点

主页风格，聚焦个性展示
“子页”设计，适应多领域写作
三端自适应，舒适阅读
自定义字体及提取压缩，兼具美观和性能
简历制作、时间线、相关文章、数学公式、Gitalk 评论、赞赏、SEO
等

安装

前置条件：node(>=16)、Git、Hexo 以及使用 Hexo 博客文件。如果你还不了解以上内容，请从这里获取相关帮助。

下载本仓库的文件到你的 Hexo 目录的 themes\tranquility 文件夹下:

cd hexo
git clone https://github.com/hooozen/hexo-theme-tranquility.git themes/tranquility

并配置根目录下 _config.yml 中的 theme 字段为 tranquility（参考主题 | Hexo)。

移除冲突的依赖，并安装必要依赖:

npm uninstall hexo-generator-category hexo-generator-archive
npm install hexo-pagination moment opentype.js

主题配置将主题目录下的配置文件 themes/tranquility/_config-template.yml 复制到博客文件根目录下，并重命名为 _config.tranquility.yml。在 _config.tranquility.yml 个性化主题配置，具体的配置项查看配置或阅读配置文件的注释。
补充(针对非开发者)
阅读报错可以使我们更快的定位问题，例如：
- 缺少依赖
  
  随着主题的更新可能会依赖更多的第三方模块，此时用户需要自己添加新的依赖。例如，运行报错内容如下：
```
...
Error: Cannot find module 'a_third_module'
...
```
  显然根据提示，缺少名为 a_third_module 的模块，只需要安装该依赖即可：
```
npm install a_third_module
```
  参考 npm-install | npm Docs

升级

本主题在不停迭代，当使用过程中遇到问题时可以查看主题是否已经有了更新。主题升级的步骤如下：

进入主题目录拉取更新
```
cd themes/tranquility
git pull
```
阅读更新说明，并查看 themes/tranquility/_config-template.yml 的新增和修改项，对应修改你的 _theme.tranuility.yml 文件

设计逻辑

本主题改变了 Hexo 的默认设计逻辑，所以与大多数的 Hexo 主题的用法不同，请参考下文。

大多数的 Hexo 主题的设计目的是在于纯粹的博客记录，并且博主的博客内容往往集中于单一学科领域（如互联网技术）。因此在这个需求驱动下，大多数 Hexo 主题被设计为主页展示文章列表，并使用繁多的分类（Category）为文章进行细分。这种设计很好的满足了需求。

当用户需要一个能够展示个人特点的主页，并且需要对博客的内容进行明确的领域划分时，这些主题并不能很好的满足这些需求。因此“致远”主题被设计出来，同时也规定了用户群体。

改变

主页并不展示文章列表，而是展示具有个人特点的内容，如“关于”和“时间线”模块。

引入“子页”的概念来取代“分类”（Category），所有的子页都在导航栏具有一级入口。基于此，子页的概念应该更广，往往为某一个学科大类或者领域，例如所有的互联网技术博文应该被划分为一个“子页”中，不管它属于“前端技术”还是“服务端技术”。

对于同属一个“子页”的文章，借鉴了微信公众号的分类逻辑，使用标签（Tag）来对文章进行分类和聚合。因此主题中没有了默认的 Category 的概念和入口，取而代之的是“子页”（Subpage）与“标签”（Tag）的概念。

有关该主题的设计理念，如果这里的描述不够清楚，打开演示站浏览一下应该就明白了。如果无法理解这种改变，可能是因为您并没有这种需求，使用其他 Hexo 主题可能会是更好的选择。

配置

经过安装步骤，你在博客根目录下已经有了一个 _config.tranquility.yml 文件。如没有，请阅读并检查安装步骤。如不加说明，该部分的配置均在博客更目录下的 _config.tranquility.yml 文件进行。

本章所有的配置内容你都可以在致远网站找到对应的测试文章，并在 hooozen/hexo-theme-test 仓库中找到对应的配置文件。所以当哪个配置项说明读不懂时不妨去找一下对应的例子。

子页

子页的配置在 subpage 下进行：

subpage: # 开启“子页”功能，详见 README
  enable: true  # 是否开启子页功能
  pages:  # 子页数组
    - name: # 子页标识，如 developer
      path: # 若不设置则默认使用 name
      title: # 显式在导航栏的菜单名，如 开发者
      icon: # 图标的路径
      description: # 描述

若关闭子页功能（enbale: false），则导航栏只会有一个“博客”按钮，点击该按钮就会进入所有文章列表。

若开启子页功能（enbale: true），则必须配置 pages 数组。该数组中使用 name 标识子页。path 指定子页的路径，默认使用 name。该数组的 title 会展示在导航栏的菜单中。配置完毕后，pages 数组中的所有项都会以 title 为名展示在网页的头部导航栏，点击每一项进入相应的子页。icon 和 description 用于配置子页中的图标和表述。

例如，致远所使用的子页配置。

新建文章后，只需要把文章头部的 category 字段设置为某子页的 name 即可将该文章划分到该子页下。

时间线

时间线的设计初衷是为了展示博主的重要事件或履历，如荣誉、宿醉、死亡等^[1]。

你也可以用它来展示精选文章或其他内容，时间线支持自定义配置。

timeline

时间线的配置在 timeline 下进行

timeline:
  enable: true  # 是否开启时间线
  reversed_order: true # 是否按时间倒序展示
  items:  # 配置时间线分类
    - name: article  # 分类名称
      color: "#ee936c"  # 分类主题色
      icon: /images/icon/icon-article.svg  # 分类图标
      checked: false  # 是否默认展示
    - name: apps
      color: "#60a465"
      icon: /images/icon/icon-app.svg
      checked: true
    - name: event
      color: "#568dc4"
      icon: /images/icon/icon-event.svg
      checked: false

在文章中配置 timeline 字段并指定时间线分类名称后，该文章会展示在时间线列表中，例如：

---
id: 57
title: 多少冬天
date: 2022-11-30 23:23:48
tags: 
  - 散文
categories: life  # 属于 life 子类下
cover: /assets/images/57-1.jpg
timeline: article  # 展示在时间线列表中
---

有关时间线的配置修改可能需要重新启动服务才会生效

简历

此功能提供一个线上简历页面，通过浏览器的打印功能可以导出 PDF，并且通过超链接保持简历的时效。通过主题配置文件的 cv 字段配置。

首先需要安装以下依赖：

npm install hexo-fontawesome-icons

博客的基础配置如下：

enable: true 是否开启简历功能
showInNav: true 是否在网站导航栏显示(需 enable 为 true)
keywords: ... 简历页的关键词(SEO)
description: ... 简历页的描述(SEO)
title: ...'cv 简历页的标题
iconPrefix: fas 简历中 fontawesome 图标使用的风格

博客的内容配置(cv.content)分为以下几块：

标题(title)
基本信息(baseInfo)
教育背景(edu)
超链接(tel | email | github | (blog & blogHref))
自定义模块(chapters)

其中前 4 个配置是必需的(超链接可任选若干)，配置比较简单请参考演示项目的配置。

对于自定义模块用户根据自身情况自行添加，例如“工作经历”、“项目经历”、“自我评价”等。其配置方法如下：

任何一个自定义模块视为 chapters 数组中的一个章节，有以下基本属性：

title: string 标题
icon: string 图标
tips?: string 提示，可选
content?: string[] 内容(与 sections 二选一)
sections?: Section[] 分节(与 content 二选一)

其中图标使用 fontawesome 的图标插件，去它的图标库搜索你想使用的图标名称即可。

内容的配置分为 content 和 sections 两种，若使用 content 则在该字段下输入分段数组来构成所在模块的内容。适合简单的场景，例如自我评价.

chapters:
  - ...
    ...
  - title: 个人小结
    icon: ranking-star
    content:
      - 第一段文本
      - 第二段文本
      - ...

而对于工作经历等模块，需要在模块中分节来介绍若干个工作经历或项目经历，则使用 sections 配置:

  - ...
    ...
  - title: 个人小结
    icon: ranking-star
    sections:
      - ...

每个 section 的配置字段如下：

title: string 标题
link?: string 链接，可选
description: string 描述
content: string[] 内容

代码高亮

代码高亮依赖于博客根目录下的 _config.yml 的 highlight 配置，请配置如下：

highlight:
  enable: true
  line_number: true
  auto_detect: false
  tab_replace: ""
  wrap: true
  hljs: true
prismjs:
  enable: false
  preprocess: true
  line_number: true
  tab_replace: ""

数学公式

主题有两种方式开启对 Latex 数学公式的支持，但都需要先进行以下操作：

移除 Hexo 默认的 markdown 渲染插件 hexo-renderer-marked，并安装 hexo-renderer-pandoc。如果安装了其他的 markdown 渲染插件也请移除！
```
npm uninstall hexo-renderer-marked
npm install hexo-renderer-pandoc
```
安装 pandoc 软件，查看 pandoc.org。

第一种方法，使用主题预置的 Latex 解析，直接在配置文件中开启 mathjax 即可使用

mathjax: true # 加载 LateX 数学公式库

第二种方法，使用第三方插件 hexo-filter-mathjax 进行服务端渲染。并关闭配置文件中的 mathjax: false

从访问性能来讲，推荐使用第二种方法。

首页自定义

查看 index 配置项

页脚自定义

foot.title 配置页脚显式的标语
foot.linksRows 配置链接的行数, 参考 issue#44.
links 配置友链
social 配置社交帐户或其他链接
contacts 配置联系方式

标签云

标签云出现在每个子页的首页，用来展示该子页下文章的标签分布。标签云有两种形式：3D 动画云和静态标签云。

tagcloud.fancy 选择是否开启 3D 动画云
tagcloud 的其他选项用以配置 3D 标签云，参考 tagcloud

文章封面

文章列表封面图片的配置，通过设置文章头部的 cover 字段指定封面图片的 URL

文章目录

通过在文章头部配置 toc: true 来展示文章目录。具有较多层级结构的文章推荐开启，而散文等文本类可以关闭。

文章置顶

通过数字来指定文章头部的 sticky 属性对文章进行置顶，数字越大置顶优先级越高。数字都需要大于 0。

文章赞赏

配置项 reward 进行文章赞赏配置，包括头像、二维码和语句等。

相关文章用来在每篇文章底部展示与本篇文章相关的推荐文章。

首先安装依赖
```
npm install hexo-related-popular-posts
```
通过 related_post 配置项进行配置，具体配置查看插件文档。

自定义字体

主题的部分区域为了设计感使用了第三方的汉字字体。但由于汉字字体包太大，因此本主题对用户使用的部分字体进行了提取打包成子字体。

通过 zh_font 配置项进行开启或关闭

Mermaid 增强

Mermaid 是一个基于 Javascript 的图表绘制工具，通过解析类 Markdown 的文本语法来实现图表的创建和动态修改。

首先安装依赖

npm install hexo-filter-mermaid-diagrams

在配置文件中启用

mermaid:
  enable: true # 启用 Mermaid 增强
  version: latest
  options: 
    startOnload: true

然后就可以在 markdown 文章中绘图了（GitHub 会自动渲染，用法就是代码块设置为 mermaid）
```
graph LR
  A --> B
  A --> D
```
如果想要在本地预览 mermaid 的渲染结果，需要支持 mermaid 的 markdown 编译器。如果使用 vscode，需要下载 Markdown Preview Mermaid Support 这个插件。
Mermaid 的具体的用法可参考 Mermaid 指引。

文章搜索

新增搜索功能，通过如下配置主题配置文件启用：

search:
  path: search.json
  enable: true
  field: post
  content: true

文章摘要

我们都知道通过在 markdown 文件中使用  可以截断文章，使得在这之前的内容可以作为 excerpt 显示在文章列表页。另外，也可以在Front-matter中设置 abstract 字段来设置隐藏式摘要。

abstract 的设置不同于通过在正文使用隔断的节录（excerpt）。abstract 的内容不会再出现在正文中，并且设置 abstrct 后会覆盖 excerpt 在文章列表的中的展示。

abstract 功能功能类似微信公众号的摘要表现。

---
title: 隐藏式摘要测试
date: 2024-01-27 11:58:32
tags: text
category: featTest
cover: assets/hozen-durdledoor.jpg
abstract: "该文章测试隐藏式摘要功能，此文本只会在文章列表展示，文章正文中不再出现。"
---

其他

请他配置请查看配置文件注释

gitalk 文章评论
百度 SEO
等

[1]. 引用了英雄联盟角色亚索的台词：“生命中有三件必经之事，荣誉、死亡，还有……宿醉……”

hooozen / hexo-theme-tranquility

readme

致远

特点

目录

安装

升级