Awesome
hexo-theme-archer
在线预览
🎯 主题预览:Demo
文档
说明
由于作者精力有限,无法保证此主题继续维护,欢迎您 Fork 👋🏻 本仓库或申请成为维护者 👩🔧。
- 本主题受 yilia 主题和 huxpro 主题的启发,结合了前者的 sidebar 设计及后者的 UI 设计。通过 sidebar 能够快速执行 archive, tag 以及 categories 导航。
- 兼容性:现代浏览器及 IE10+。
- 有任何使用上的问题欢迎发起 issue。
快速安装
拉取主题文件
拉取 Archer 主题文件到 themes/archer
目录:
git clone https://github.com/fi3ework/hexo-theme-archer.git themes/archer --depth=1
如果您没有安装 Git,也可以在 Hexo 根目录下手动创建 themes/archer
文件夹,下载此仓库的所有代码到该目录下。
安装必要依赖
Archer 主题依赖于 hexo-generator-json-content
插件生成侧边栏索引,需要在 Hexo 根目录安装此插件:
npm install hexo-generator-json-content
同时,在 _config.yml
中添加如下字段:
jsonContent:
meta: true
pages: false
posts:
title: true
date: true
path: true
text: false
raw: false
content: false
slug: false
updated: false
comments: false
link: false
permalink: true
excerpt: false
categories: true
tags: true
启用 Archer 主题
最后,配置 _config.yml
,设置 Hexo 主题为 Archer:
theme: archer
您成功设置了博客主题 🎇!现在就执行 hexo s
命令,在本地预览主题效果吧。
主题个性化配置
现在您的项目目录结构应当如下所示:
. # 「Hexo 根目录」
├── themes
│ └── archer # 「Archer 主题目录」
│ └── _config.yml # Archer 主题配置文件
└── _config.yml # Hexo 配置文件
您可以通过 hexo -v
命令,或在 Hexo 根目录下的 package.json
中查看您当前使用的 Hexo 版本。
- 如果 Hexo 版本 >= 5.0.0,复制 Archer 主题目录下的
_config.yml
到 Hexo 根目录,重命名为_config.archer.yml
,修改此文件即可对主题进行配置。删除 Archer 主题目录下的_config.yml
文件,或将它重命名为_config.yml.template
,避免配置合并或冲突。 - 如果 Hexo 版本 >= 2.8.2,修改 Archer 主题目录下的
_config.yml
文件对主题进行配置。
为了与 Hexo 全局配置文件 _config.yml
作区分,在后面的介绍中将 Archer 主题配置文件称为 _config.archer.yml
。
这个维基页面包含了主题配置属性的完整中文参考。
可选的 Archer 主题配置内容如下:
- 启用字数统计
- 配置 About 页面
- 配置 404 页面
- 启用 RSS 订阅
- 启用 Mermaid
- 启用 LaTeX 数学公式
- 启用自定义字体
- 自定义单独文章页头图
- 将 Unsplash 的随机图片作为头图
- 自定义文章在首页的摘要
- 自定义主题颜色
- 切换代码配色方案
- 设置文章版权信息
- 启用 Algolia 搜索
- 切换为英文界面
启用字数统计
在 Hexo 根目录下安装依赖插件:
npm install hexo-wordcount
配置 _config.archer.yml
启用字数统计能力:
reading_info: true
现在,字数统计信息将显示在博客页面的标题下方。
配置 About 页面
在 Hexo 根目录下执行如下命令:
hexo new page "about"
在 Hexo 根目录下 source/about/index.md
中添加以下内容:
---
title: 您的自我介绍标题
layout: about
---
您的自我介绍正文
其中 layout: about
字段为必要的且不可修改为其它值。
配置 _config.archer.yml
以开启 About 页面:
about:
enable: true
image: /intro/about-page.jpg
配置 404 页面
在 Hexo 根目录下 source
中创建 404.md
,添加字段如下:
---
layout: 404
title: "[404]"
description: "May the Force be with you :)"
---
其中 Front-matter 的 layout: 404
字段为必要的且不可修改为其它值,title
字段为您自定义的标题,description
字段为 404 页面的自定义描述。
您可以通过配置 _config.archer.yml
来修改 404 页面的背景图片:
_404_image: /intro/404-bg.jpg
启用 RSS 订阅
在 Hexo 根目录下安装依赖插件:
npm install hexo-generator-feed --save
配置 _config.archer.yml
:
social:
rss: /atom.xml
启用 Mermaid
Mermaid 是一款基于 JavaScript 的流程图和图表工具,它使用 Markdown 定义并渲染各种图表,帮助构建软件工程或各类技术文档。
为了启用 Mermaid,您需要首先在 Hexo 根目录下安装插件 hexo-filter-mermaid-diagrams
:
npm install hexo-filter-mermaid-diagrams --save
配置 _config.archer.yml
以启用 Mermaid:
mermaid:
enable: true
version: 8.11.0
theme: dark
测试 Mermaid 是否启用成功,您可以在任意文章中添加下面的内容(您需要取消缩进):
``` mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
❗️❗️❗️ 注意:如果您需要使用类图,请编辑您 Hexo 根目录下的
_config.yml
,设置external_link: false
。请确保这个设置对您原来的页面功能没有影响,这是 Hexo 本身的 bug。
启用 LaTeX 数学公式
这个维基页面包含启用 LaTeX 数学公式支持的完整介绍。
Archer 主题已经内置了 MathJax,但是您需要替换 Hexo 默认的 Markdown 渲染引擎来支持解析 LaTeX 数学公式语法。此示例中将替换为 hexo-renderer-pandoc
。
请留意:替换渲染引擎为 hexo-renderer-pandoc
会带来编写上的区别,可能导致一些潜在的问题。
首先,确保系统中已经安装了 pandoc
,版本不低于 2.0。
在 Hexo 根目录下执行下面的命令:
# 卸载默认的渲染引擎
npm uninstall hexo-renderer-marked --save
# 安装 hexo-renderer-pandoc
npm install hexo-renderer-pandoc --save
配置 _config.archer.yml
以启用 LaTeX 数学公式:
math:
mathjax:
enable: true
version: 3.2.0
Archer 默认不启用 MathJax 渲染 LaTeX 数学公式,因此需要在文章的 Front-matter 中添加 mathjax: true
字段。
测试是否启用成功,您可以文章中添加下面的内容进行测试:
\begin{equation}
\left\{
\begin{array}{lr}
x=\dfrac{3\pi}{2}(1+2t)\cos(\dfrac{3\pi}{2}(1+2t)), & \\
y=s, & 0 \leq s \leq L,|t| \leq1. \\
z=\dfrac{3\pi}{2}(1+2t)\sin(\dfrac{3\pi}{2}(1+2t)), &
\end{array}
\right.
\end{equation}
启用自定义字体
实验性功能,自定义字体依赖于 CSS Variables 能力,存在浏览器兼容性问题。注意:引入体积较大的字体文件(例如中文字体)会显著降低博客的访问速度。
配置 _config.archer.yml
启用自定义字体能力:
custom_font:
enable: true
name: 'Noto Sans SC:n3,n4,n5,n7'
url: 'https://fonts.googleapis.cnpmjs.org/css2?family=Noto+Sans+SC:wght@300;400;500;700&display=swap'
其中,name
为引入的自定义字体名称,:
后跟字体变体和字重,不同的变体和字重使用 ,
间隔。例如 name: 'Noto Sans SC:i5,n7'
表示引入 Noto Sans SC
的斜体 500 字重和正常 700 字重。
url
为引入的自定义字体的 CDN 链接或本地链接。
文章 Front-matter 配置
Archer 主题允许您在文章的 Front-matter 处配置如下内容:
- 置顶文章:
sticky: number
或top: boolean
- 文章打赏:
donate: boolean
- 文章目录:
toc: boolean
- 翻译的文章:
translated: { author: string; title: string; link: string; }
置顶文章
Archer 主题在主页为置顶的文章显示一个小标记。
在默认情况下,Hexo 使用 hexo-generator-index
生成文章索引。如果您想置顶某篇文章,只需在它的 Front-matter 处添加 sticky
属性即可:
---
title: Hello World
date: 2013/7/13 20:46:25
sticky: 100
---
如果您使用了其它的插件生成索引,也可以手动添加 top
属性以置顶文章:
---
title: Hello World
date: 2013/7/13 20:46:25
top: true
---
文章打赏
桌面端阅读文章时,会在文章左下角显示打赏按钮,点击后呈现您提供的打赏信息。
您可以配置 _config.archer.yml
自定义打赏信息和二维码:
donate:
enable: true # 全局启用打赏按钮
title: Buy Me A Coffee
description: If this post helped you, please consider buying the author a cup of sugar-free coffee ☕️.
qr_code:
- url: /path/to/wechat.png
alt: Wechat
- url: /path/to/alipay.png
alt: Alipay
在文章的 Front-matter 处设置的 donate
属性具有最高优先级,Archer 主题在渲染时会忽略全局的 donate.enable
配置:
---
title: Hello World
date: 2013/7/13 20:46:25
donate: false # 在当前文章隐藏打赏按钮
---
文章目录
桌面端阅读文章时,会在文章右侧显示文章目录。
您可以配置 _config.archer.yml
全局控制文章目录的显示或隐藏:
toc: true
在文章的 Front-matter 处设置的 toc
属性具有最高优先级,Archer 主题在渲染时会忽略全局的配置:
---
title: Hello World
date: 2013/7/13 20:46:25
toc: false # 在当前文章隐藏文章目录
---
翻译的文章
在文章的 Front-matter 中添加 translated
字段:
---
translated:
author: Stark-X
title: 你好,世界
link: https://github.com/
---
更新主题
主题的更新内容发布在仓库的 Release 页面。
提供两种方法供参考:
- 使用
git
命令进行更新。可能需要手动合并代码,解决冲突。 - 备份重要文件后重新克隆,简单粗暴。
使用 git
命令
在 Archer 主题目录下先执行 git stash
将本地的修改暂存,然后执行 git pull
获取主题的最新版本,再执行 git stash pop
将本地的修改还原,如果合并冲突报错 CONFLICT
,手动合并解决冲突。
如果自定义了主题,解决完冲突后,执行 npm run build
重新生成主题文件。
重新克隆主题
首先备份 Archer 主题目录下所有您自定义过的文件(包括 _config.yml
和 source
下自定义的文件等),然后删除 themes/archer
目录,参考文档重新安装主题,最后将备份的文件替换到原来的位置。
许可证
MIT