致远

致远是一款 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:
  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 进行文章赞赏配置，包括头像、二维码和语句等。

自定义字体

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

通过 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
```
Loading
如果想要在本地预览 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]. 引用了英雄联盟角色亚索的台词：“生命中有三件必经之事，荣誉、死亡，还有……宿醉……”

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
_font		_font
doc/images		doc/images
layout		layout
scripts		scripts
source		source
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
_config-template.yml		_config-template.yml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

致远

特点

目录

安装

升级

设计逻辑

改变

配置

子页

时间线

简历

代码高亮

数学公式

首页自定义

导航

页脚自定义

标签云

文章封面

文章目录

文章置顶

文章赞赏

相关文章

自定义字体

Mermaid 增强

文章搜索

文章摘要

其他

About

Releases 16

Packages

Contributors 4

Languages

License

hooozen/hexo-theme-tranquility

Folders and files

Latest commit

History

Repository files navigation

致远

特点

目录

安装

升级

设计逻辑

改变

配置

子页

时间线

简历

代码高亮

数学公式

首页自定义

导航

页脚自定义

标签云

文章封面

文章目录

文章置顶

文章赞赏

相关文章

自定义字体

Mermaid 增强

文章搜索

文章摘要

其他

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 16

Packages 0

Contributors 4

Languages

Packages