Merge pull request fi3ework#305 from fi3ework/dev-1.6.3

🛎️ One-click translation by Google. [中文更新内容](https://github.com/fi3ework/hexo-theme-archer/pull/305)。

## Merge PR

Merged fi3ework#268 and fi3ework#300.

## Feature

- Added **Dark mode** support, and can be switched by the button at \<header \/\>.
  Regarding the mode switch button, considering that the user is less likely to use it after use, it is put together with the link back to the home page and disappears after scrolling. In the future, you can put the same less frequently used search button or other helpful things here.
- Add **MathJax mathematical formula** support, and update related documents (fi3ework#266).
- Added **Mermaid chart** support (fi3ework#186).
- Add support for the personal information `sticky` of the homepage to scroll with the page (fi3ework#202).
-Now you can set the category information of the corresponding article to be displayed on the homepage and article page (fi3ework#188).
- It is now possible to hide the catalog of specific articles (fi3ework#244).

## Change

- Adapt to Dark mode, adjust the spacing of text `padding`.
- For mobile, when scrolling to the top part of the page, add a dark background to the \<header \/\> part. Helps to avoid buttons being disturbed by page title information.
- The critical point of page scroll switching is selected as the junction of the header image and \<container \/\>.

## Optimization

- Add a fade-in and fade-out animation effect to the floating button.
- Add more configuration content for the timeliness of `outdated_threshold` articles. And keep the style sheet design consistent with the quote block part of the article.
- Add support for Hexo's `comments` property to the article. When set to `false`, the comment plugin will not be displayed for the article.
- When setting the post `sticky` property, the sticky icon will also be displayed.
- The Toc of the article page will be ready sooner.
- Optimize the configuration of Babel and Eslint.

## Fix

- When Algolia is enabled, the unprocessed icon content will no longer be displayed when the page has not been loaded.
- When opening the Algolia search interface, prevent page scrolling.
- Fix the alignment of social icon including Steam icon (fi3ework#301).

## Chore

- Fixed the code format and indentation of all `.ejs` files in the `layout` directory.
- Use `const` instead of unnecessary `let` in the script file to make the code look more clever.
- Unify most of the CDN links as `cdn.jsdelivr.net`.
- Update third-party dependency packages including jQuery to fix compatibility issues; remove unnecessary or deprecated dependencies.
- Update the warehouse documentation and secondary development documentation.

## Known issues

In dark mode, when switching or refreshing the page, due to the reload of the `layout.ejs` file, the component \<div class="contain" \/\> will cause a short white screen. The expected situation is that in Dark mode, set its background color to dark before loading (such as \#121212)

Author: LolipopJ

.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