Skip to content

fi3ework/hexo-theme-archer

Repository files navigation

hexo-theme-archer

preview

在线预览

🎯 主题预览: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 主题配置内容如下:

启用字数统计

在 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 处配置如下内容:

置顶文章

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.ymlsource 下自定义的文件等),然后删除 themes/archer 目录,参考文档重新安装主题,最后将备份的文件替换到原来的位置。

许可证

MIT