Dev 1.6.3: add support to Dark Mode, Mathjax and Mermaid

.eslintrc.json

@@ -1,7 +1,9 @@
 {
+    "parser": "@babel/eslint-parser",
     "extends": [
-        "eslint-config-alloy",
-        "plugin:prettier/recommended"
+        "alloy",
+        "plugin:prettier/recommended",
+        "prettier"
     ],
     "globals": {
         "siteMeta": true

README.md

@@ -17,19 +17,26 @@
 
 - 本主题受 [yilia](https://github.com/litten/hexo-theme-yilia) 主题和 [huxpro](https://github.com/Huxpro/huxpro.github.io) 主题的启发，结合了前者的 sidebar 设计及后者的 UI 设计。通过 sidebar 能够快速执行 archive, tag 以及 categories 导航。
 - 兼容性：现代浏览器及 IE10+。
-- 有任何使用上的问题欢迎 [**发起 issue**](https://github.com/fi3ework/hexo-theme-archer/wiki/%E5%90%AF%E7%94%A8-Algolia-%E6%90%9C%E7%B4%A2)。
+- 有任何使用上的问题欢迎 **发起 issue**。
 
 ## 安装主题
 
-### 安装依赖，拉取 Archer 主题文件
+### 安装主题依赖
 
-在 Hexo 根目录下执行以下命令：
+Archer 主题依赖于 `hexo-generator-json-content` 和 `hexo-wordcount`，因此需要在 Hexo 根目录执行以下命令：
 
 ``` bash
-npm i hexo-generator-json-content --save && npm i --save hexo-wordcount && git clone https://github.com/fi3ework/hexo-theme-archer.git themes/archer --depth=1
+npm install hexo-generator-json-content --save
+npm install hexo-wordcount --save
 ```
 
-现在，Archer 主题已经顺利拉取到 `themes/archer` 目录下。
+### 拉取主题文件
+
+依赖安装完成后，拉取 Archer 主题到 `themes/archer` 目录，在 Hexo 根目录执行下面的命令：
+
+``` bash
+git clone https://github.com/fi3ework/hexo-theme-archer.git themes/archer --depth=1
+```
 
 ### 设置 Hexo 主题为 Archer
 
@@ -64,47 +71,248 @@ jsonContent:
     tags: true
 ```
 
+### 启动本地预览
+
+在 Hexo 根目录下执行 `hexo s`，即可启动本地预览。
+
 ## 主题配置
 
-现在您的博客项目的目录目录结构应当如下：
+现在您的项目目录结构应当如下所示：
 
 ``` bash
-. # Hexo 根目录
+. # 「Hexo 根目录」
 ├── themes
-│   └── archer # Archer 主题目录
+│   └── archer # 「Archer 主题目录」
 │       └── _config.yml # Archer 主题配置文件
 │
 └── _config.yml # Hexo 配置文件
 ```
 
-如果 Hexo 版本 >= 5.0.0，建议首先复制 Archer 主题目录下的 [`_config.yml`](./_config.yml) 到 Hexo 根目录，并命名为 `_config.archer.yml`。接下来修改 Hexo 根目录下的这个 `_config.archer.yml` 文件即可对主题进行配置。
+您可以通过 `hexo -v` 命令，或在 Hexo 根目录下的 `package.json` 中查看您当前使用的 Hexo 版本。
 
-如果 Hexo 版本 >= 2.8.2，修改 Archer 主题目录下的 [`_config.yml`](./_config.yml) 文件即可对主题进行配置。
+如果 Hexo 版本 >= 5.0.0，建议复制 Archer 主题目录下的 [`_config.yml`](./_config.yml) 到 Hexo 根目录，并命名为 `_config.archer.yml`，接下来修改此文件即可对主题进行配置。现在，您可以删除 Archer 主题目录下的 `_config.yml` 文件，避免配置合并或冲突。
 
-如果 Hexo 版本 < 2.8.2，请参考 Archer 主题目录下的 [`_config.yml`](./_config.yml) 中的配置，在 Hexo 根目录下的 `_config.yml` 添加相应字段即可进行配置。请注意不要添加重复字段。
+如果 Hexo 版本 >= 2.8.2，修改 Archer 主题目录下的 `_config.yml` 文件即可对主题进行配置。
 
-您可以在 Hexo 根目录下的 `package.json` 查看您当前使用的 Hexo 版本。
+如果 Hexo 版本 < 2.8.2，请参考 Archer 主题目录下的 `_config.yml` 中的配置，在 Hexo 根目录下的 `_config.yml` 添加相应字段即可进行配置。
+
+上面三种情况的 Archer 主题配置文件 `_config.archer.yml` 或 `_config.yml`，为了与 Hexo 根目录下的全局配置文件 `_config.yml` 作区分，在后面的介绍中统称为「Archer 主题目录下的 `_config.yml`」。
 
 这个[维基页面](https://github.com/fi3ework/hexo-theme-archer/wiki/Archer-%E4%B8%BB%E9%A2%98%E9%85%8D%E7%BD%AE%E4%BF%A1%E6%81%AF%E4%B8%AD%E6%96%87%E5%8F%82%E8%80%83)包含了主题配置属性的中文参考。
 
 **警告**：不要把自己 api-token 之类的私密信息添加到配置中，更不要推送到公共仓库。
 
-### 可选配置
+可选的 Archer 主题配置内容如下：
 
-- [启用 about 页](https://github.com/fi3ework/hexo-theme-archer/wiki/%E5%90%AF%E7%94%A8about%E9%A1%B5)
-- [启用 404 页](https://github.com/fi3ework/hexo-theme-archer/wiki/%E5%90%AF%E7%94%A8404%E9%A1%B5)
-- [启用 rss 订阅](https://github.com/fi3ework/hexo-theme-archer/wiki/%E5%90%AF%E7%94%A8rss)
+- [配置 About 页面](#配置-about-页面)
+- [配置 404 页面](#配置-404-页面)
+- [启用 RSS 订阅](#启用-rss-订阅)
+- [启用 Mermaid](#启用-mermaid)
+- [启用 LaTeX 数学公式](#启用-latex-数学公式)
 - [自定义单独文章页头图](https://github.com/fi3ework/hexo-theme-archer/wiki/%E8%87%AA%E5%AE%9A%E4%B9%89%E6%96%87%E7%AB%A0%E9%A1%B5%E5%A4%B4%E5%9B%BE)
 - [将 Unsplash 的随机图片作为头图](https://github.com/fi3ework/hexo-theme-archer/wiki/%E5%B0%86-Unsplash-%E9%9A%8F%E6%9C%BA%E5%9B%BE%E7%89%87%E4%BD%9C%E4%B8%BA%E5%A4%B4%E5%9B%BE)
 - [自定义文章在首页的摘要](https://github.com/fi3ework/hexo-theme-archer/wiki/%E8%87%AA%E5%AE%9A%E4%B9%89%E6%96%87%E7%AB%A0%E5%9C%A8%E9%A6%96%E9%A1%B5%E7%9A%84%E6%91%98%E8%A6%81)
 - [自定义主题颜色](https://github.com/fi3ework/hexo-theme-archer/wiki/%E8%87%AA%E5%AE%9A%E4%B9%89%E4%B8%BB%E9%A2%98%E9%A2%9C%E8%89%B2)
 - [切换代码配色方案](https://github.com/fi3ework/hexo-theme-archer/wiki/%E5%88%87%E6%8D%A2%E4%BB%A3%E7%A0%81%E9%85%8D%E8%89%B2%E6%96%B9%E6%A1%88)
-- [置顶文章](https://www.jianshu.com/p/42a4efcdf8d7)
 - [设置文章版权信息](https://github.com/fi3ework/hexo-theme-archer/wiki/%E8%AE%BE%E7%BD%AE%E6%96%87%E7%AB%A0%E7%89%88%E6%9D%83%E4%BF%A1%E6%81%AF)
-- [启用站内搜索](https://github.com/fi3ework/hexo-theme-archer/wiki/%E5%90%AF%E7%94%A8-Algolia-%E6%90%9C%E7%B4%A2)
-- [启用 Latex 支持](https://github.com/fi3ework/hexo-theme-archer/wiki/%E5%90%AF%E7%94%A8-Latex-%E6%94%AF%E6%8C%81)
+- [启用 Algolia 搜索](https://github.com/fi3ework/hexo-theme-archer/wiki/%E5%90%AF%E7%94%A8-Algolia-%E6%90%9C%E7%B4%A2)
 - [切换为英文界面](https://github.com/fi3ework/hexo-theme-archer/wiki/%E8%8B%B1%E6%96%87%E7%95%8C%E9%9D%A2)
 
+### 配置 About 页面
+
+在 Hexo 根目录下执行：
+
+``` bash
+hexo new page "about"
+```
+
+在 Hexo 根目录下 `source/about/index.md` 文件中添加下面的字段：
+
+``` markdown
+---
+title: 自我介绍标题
+layout: about
+---
+自我介绍正文
+```
+
+其中 Front-matter 的 `layout: about` 字段为**必要的**且**不可修改**为其它值；Front-matter 的 `title` 和正文内容由您自定义编写。
+
+您可以修改 Archer 主题目录下的 `_config.yml` 文件的 `about` 字段：
+
+``` yml
+about:
+  enable: true
+  image: '/intro/about-page.jpg'
+```
+
+其中，如果设置 `enable: false`，则不显示 About 页面；`image` 为 About 页面 Banner 图像地址，若不填写则默认使用首页的 Banner 图像。
+
+### 配置 404 页面
+
+在 Hexo 根目录下 `source` 中创建 `404.md` 文件，添加字段如下：
+
+``` markdown
+---
+layout: 404
+title: "[404]"
+description: "May the Force be with you :&#41;"
+---
+```
+
+其中 Front-matter 的 `layout: 404` 字段为**必要的**且**不可修改**为其它值，`title` 字段为您自定义的标题，`description` 字段为 404 页面的自定义描述。
+
+您可以配置 Archer 主题目录下的 `_config.yml` 文件的 `_404_image` 字段来修改 404 页面的背景图片：
+
+``` yml
+_404_image: '/intro/404-bg.jpg'
+```
+
+### 启用 RSS 订阅
+
+在 Hexo 根目录下执行：
+
+``` bash
+npm install hexo-generator-feed --save
+```
+
+修改 Archer 主题目录下的 `_config.yml` 文件中的 `social` 字段，配置内容如下：
+
+```yml
+social:
+  rss: /atom.xml
+```
+
+### 启用 Mermaid
+
+[Mermaid](https://github.com/mermaid-js/mermaid) 是一款基于 JavaScript 的流程图和图表工具，它使用 Markdown 定义并渲染各种图表，帮助构建软件工程或各类技术文档。
+
+为了启用 Mermaid，您需要首先在 Hexo 根目录下安装 [`hexo-filter-mermaid-diagrams`](https://github.com/webappdevelp/hexo-filter-mermaid-diagrams) 依赖：
+
+``` bash
+npm install hexo-filter-mermaid-diagrams --save
+```
+
+然后在 Archer 主题目录下的 `_config.yml` 设置以启用 Mermaid：
+
+``` yml
+mermaid:
+  enable: true
+  version: 8.11.0
+  theme: dark
+```
+
+测试 Mermaid 是否启用成功，您可以在任意文章中添加下面的内容（您需要取消缩进）：
+
+``` markdown
+    ``` mermaid
+    graph TD;
+      A-->B;
+      A-->C;
+      B-->D;
+      C-->D;
+    ```
+```
+
+> ❗️❗️❗️ 注意：如果您需要使用**类图**，请编辑您 Hexo 根目录下的 `_config.yml` 文件，设置 `external_link: false`。请确保这个设置对您原来的页面功能没有影响，这是 Hexo 本身的 bug。
+
+## 启用 LaTeX 数学公式
+
+这个[维基页面](https://github.com/fi3ework/hexo-theme-archer/wiki/%E5%90%AF%E7%94%A8-Latex-%E6%94%AF%E6%8C%81)包含启用 LaTeX 数学公式支持的完整介绍。
+
+Archer 主题已经内置了 MathJax，但是您需要**替换 Hexo 默认的 Markdown 渲染引擎**来支持解析 LaTeX 数学公式语法。此示例中将替换为 [`hexo-renderer-pandoc`](https://github.com/wzpan/hexo-renderer-pandoc)。
+
+请留意：替换渲染引擎可能会带来编写上的区别，或导致一些潜在的问题。
+
+首先，确保系统中已经[安装](https://pandoc.org/installing.html)了 `pandoc`，版本不低于 2.0。
+
+在 Hexo 根目录下执行下面的命令：
+
+``` bash
+# 卸载默认的渲染引擎
+npm uninstall hexo-renderer-marked --save
+# 安装 hexo-renderer-pandoc
+npm install hexo-renderer-pandoc --save
+```
+
+在 Archer 主题目录下的 `_config.yml` 设置以启用 LaTeX 数学公式：
+
+``` yml
+math:
+  mathjax:
+    enable: true
+    version: 3.2.0
+```
+
+Archer 默认不启用 MathJax 渲染 LaTeX 数学公式，因此需要在文章的 Front-matter 中添加 `mathjax: true` 字段。
+
+测试是否启用成功，您可以在这篇文章中添加下面的内容：
+
+``` markdown
+\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}
+```
+
+## 文章撰写增强
+
+Archer 主题为您撰写的文章提供了一些增强的展示内容，这需要您手动在文章的 Front-matter 处配置。包括如下：
+
+- [置顶文章](#置顶文章)
+- [隐藏文章目录](#隐藏文章目录)
+
+### 置顶文章
+
+Archer 主题在主页为置顶的文章显示一个小标记。
+
+在默认情况下，Hexo 使用 [`hexo-generator-index`](https://github.com/hexojs/hexo-generator-index) 生成文章索引。假如您需要置顶某篇文章，只需要在它的 Front-matter 处添加 `sticky` 属性即可：
+
+```md
+---
+title: Hello World
+date: 2013/7/13 20:46:25
+sticky: 100
+---
+```
+
+您可以在 Hexo 根目录下的 `package.json` 文件中找到您是否使用 `hexo-generator-index` 插件作为项目依赖。
+
+假如您使用其它的插件生成索引，也可以手动添加 `top` 属性以显示小标记：
+
+```md
+---
+title: Hello World
+date: 2013/7/13 20:46:25
+top: true
+---
+```
+
+### 隐藏文章目录
+
+在默认情况下，使用宽屏幕阅读文章时，会在文章右侧显示其目录信息。
+
+您可以通过配置 Archer 主题目录下的 `_config.yml` 以**全局**关闭文章目录：
+
+```yml
+toc: false
+```
+
+或者，您也可以指定某些文章不显示目录。只需要在文章的 Front-matter 部分设置 `toc` 属性即可：
+
+```md
+---
+title: Hello World
+date: 2013/7/13 20:46:25
+toc: false
+---
+```
+
 ## 更新主题
 
 提供两种方法供参考：
@@ -114,13 +322,13 @@ jsonContent:
 
 ### 使用 `git` 命令
 
-在 Archer 主题目录下先执行 `git stash` 将本地的修改暂存，然后执行 `git pull` 获取主题的最新版本，再执行 `git stash pop` 将本地的修改还原，如果合并冲突报错 `CONFLICT`，可以参考[这篇文章](http://www.01happy.com/git-resolve-conflicts/)手动解决合并冲突，手动解决。
+在 Archer 主题目录下先执行 `git stash` 将本地的修改暂存，然后执行 `git pull` 获取主题的最新版本，再执行 `git stash pop` 将本地的修改还原，如果合并冲突报错 `CONFLICT`，手动合并解决冲突即可。
 
-如果自定义了主题，在合并冲突时可以手动解决冲突的部分后，重新生成主题即可。
+如果自定义了主题，解决冲突后，执行 `npm run build` 重新生成主题即可。
 
 ### 重新克隆主题
 
-首先备份 Archer 主题目录下所有您自定义过的文件（包括 `_config.yml` 和 `source` 文件夹下添加的文件等），然后删除 Archer 主题目录目录，再重新安装，最后将备份的文件替换到原来的位置即可。
+首先备份 Archer 主题目录下所有您自定义过的文件（包括 `_config.yml` 和 `source` 文件夹下添加的文件等），然后删除 Archer 主题目录，再重新安装，最后将备份的文件替换到原来的位置即可。
 
 ## 更新日志
 

_config.yml

@@ -31,9 +31,8 @@ social:
   rss: 
 # friends
 friends:
-  friendA: //www.baidu.com
-  friendB: //www.google.com
-  friendC: 
+  # friendA: //www.baidu.com
+  # friendB: //www.google.com
 about:
   enable: true
   image: '/intro/about-bg.jpg'
@@ -57,6 +56,18 @@ post_header_image: '/intro/post-bg.jpg'
 # 404 image
 _404_image: '/intro/404-bg.jpg'
 
+# ========== Theme ========== #
+# Blog float button theme ('default' or 'rounded')
+float_button_theme: default
+# Blog read progress color ('default' for black or 'feature' for feature-color)
+read_progress_color: default
+# Blog post banner theme ('default' or 'clean')
+post_banner_theme: default
+# Stick profile info
+profile_sticky: false
+# Show categories info in index and post page
+show_categories: false
+
 # ========== Search ========== #
 algolia_search:
   enable: false
@@ -139,11 +150,25 @@ website_approve:
   icp_approve: 
   beian_approve: 
   beian_img: /assets/beian.png
-# Blog page article timeliness days reminder, 0 for no threshold
-outdated_threshold: 0
-# Blog float button theme ('default' or 'rounded')
-float_button_theme: default
-# Blog read progress color ('default' for black or 'feature' for feature-color)
-read_progress_color: default
-# Blog post banner theme ('default' or 'clean')
-post_banner_theme: default
+# Blog page article timeliness note
+outdated_threshold:
+  enable: false
+  days: 180
+  # By default, timeliness reminder will be displayed for each article. That's not necessarily what you want.
+  # If true, you can set `timeliness: true` for specified article to enable the reminder.
+  specify_article: false
+# Mermaid Chart: https://github.com/knsv/mermaid
+mermaid:
+  enable: false
+  # Version number '8' is for the latest '8.x' version of Mermaid.
+  version: 8.11.0
+  theme: dark
+  # find more api options from https://github.com/knsv/mermaid/blob/master/src/mermaidAPI.js
+  options:
+# LaTeX Math Equations Support
+math:
+  mathjax:
+    enable: false
+    # Specified version number no less than '3.0.0', or you need to modify the CDN link manually.
+    # Version number '3' is for the latest '3.x' version of MathJax.
+    version: 3.2.0