tsanie/blog
1
1
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

initial

Browse Source
This commit is contained in:
Tsanie Lily
2019-05-30 18:52:14 +08:00
commit aa360a22bf
341 changed files with 30369 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
themes/next/docs/zh-CN/ALGOLIA-SEARCH.md Normal file
View File

@ -0,0 +1,84 @@
<h1 align="center">Algolia 搜索</h1>
NexT 内部提供 Algolia 的搜索功能，要使用此功能请确保所使用的 NexT 版本在 `v5.1.0` 之后。需要注意的是，仅仅将 `next/_config.yml` 中 `algolia_search` 的 `enable` 打开**并不能让你使用 Algolia 搜索**，你还需要**使用对应的 Hexo-Algolia 插件** 才能真正在博客页面中使用 Algolia 搜索。按照下面介绍的步骤操作即可完成 Algolia 搜索的安装。
1. 前往 [Algolia 注册页面](https://www.algolia.com/)，注册一个新账户。 可以使用 GitHub 或者 Google 账户直接登录，注册后的 14 天内拥有所有功能（包括收费类别的）。之后若未续费会自动降级为免费账户，免费账户 总共有 10,000 条记录，每月有 100,000 的可以操作数。注册完成后，创建一个新的 Index，这个 Index 将在后面使用。
![](http://theme-next.iissnan.com/uploads/algolia/algolia-step-2.png)
1. Index 创建完成后，此时这个 Index 里未包含任何数据。接下来需要安装 [Hexo Algolia](https://github.com/oncletom/hexo-algolia) 扩展，这个扩展的功能是搜集站点的内容并通过 API 发送给 Algolia。前往站点根目录，执行命令安装：
```
$ cd hexo
$ npm install --save hexo-algolia
```
1. 在 `API Keys` 页面找到需要使用的一些配置的值，包括 `ApplicationID` 和 `Search-Only API Key`。注意，`Admin API Key` 需要保密保存，不要外泄。
![](https://user-images.githubusercontent.com/8521181/35479066-64e35aec-0428-11e8-91f9-1ec3afa45c5c.png)
1. 在 `API Keys` 页面，点击 `ALL API KEYS` 找到新建 INDEX 对应的 key，**编辑权限**，在弹出框中找到 ACL ，**勾选 Add records、 Delete records、List indices、Delete index 权限**，点击 `update` 更新。
![](https://user-images.githubusercontent.com/8521181/35479064-611aa0b4-0428-11e8-85a1-cfb449b486ec.png)
![](https://user-images.githubusercontent.com/8521181/35479084-d4f7ac02-0428-11e8-95a6-c4e3b1bef47b.png)
1. 编辑 `站点配置文件`，新增以下配置，除了 `chunkSize` 字段，替换成在 Algolia 获取到的值：
```yml
algolia:
applicationID: 'applicationID'
apiKey: 'apiKey'
indexName: 'indexName'
chunkSize: 5000
```
1. 当配置完成，在站点根目录下执行一下命令来更新上传 Index。请注意观察命令的输出。
```
$ export HEXO_ALGOLIA_INDEXING_KEY=Search-Only API key # 使用 Git Bash
# set HEXO_ALGOLIA_INDEXING_KEY=Search-Only API key # 使用 Windows CMD 命令行
$ hexo clean
$ hexo algolia
```
![](http://theme-next.iissnan.com/uploads/algolia/algolia-step-4.png)
1. 切换到 NexT 目录，并安装 algolia-instant-search 到 `source/lib` 目录。
```
$ cd themes/next
$ git clone https://github.com/theme-next/theme-next-algolia-instant-search source/lib/algolia-instant-search
```
如果你想直接使用 CDN 设置 Algolia Search，则需要在`主题配置文件`中添加 vendors 字段：
```yml
vendors:
...
# Internal version: 1
# https://www.algolia.com
algolia_instant_js: https://cdn.jsdelivr.net/npm/instantsearch.js@2.4.1/dist/instantsearch.js
algolia_instant_css: https://cdn.jsdelivr.net/npm/instantsearch.js@2.4.1/dist/instantsearch.min.css
...
```
1. 更改`主题配置文件`，找到 Algolia Search 配置部分，将 `enable` 改为 `true`。同时你需要**关闭**其他搜索插件，如 Local Search 等。你也可以根据需要调整 `labels` 中的文本：
```yml
# Algolia Search
algolia_search:
enable: true
hits:
per_page: 10
labels:
input_placeholder: Search for Posts
hits_empty: "We didn't find any results for the search: ${query}"
hits_stats: "${hits} results found in ${time} ms"
```
<h2 align="center">已知的问题</h2>
1. 考虑到 Algolia 免费账户的限制，目前 [Hexo-Algolia](https://github.com/oncletom/hexo-algolia) 插件最新版本去掉了正文索引功能。
1. [Hexo-Algoliasearch](https://github.com/LouisBarranqueiro/hexo-algoliasearch) 插件提供了正文索引功能，不过需要替换 NEXT 主题中的关键字。对于免费账户，`Record Too Big` 的问题同样存在。
- 替换 `source/js/algolia-search.js` 中所有的 `applicationID` 为 `appId`
- 替换 `layout/_partials/head/head.swig` 中所有的 `applicationID` 为 `appId`

99
themes/next/docs/zh-CN/CODE_OF_CONDUCT.md Normal file
View File

@ -0,0 +1,99 @@
<div align="right">Language: :us:
<a title="Chinese" href="../docs/zh-CN/CODE_OF_CONDUCT.md">:cn:</a>
<a title="Russian" href="../docs/ru/CODE_OF_CONDUCT.md">:ru:</a></div>
# <div align="center"><a title="Go to homepage" href="https://theme-next.org"><img align="center" width="56" height="56" src="https://raw.githubusercontent.com/theme-next/hexo-theme-next/master/source/images/logo.svg?sanitize=true"></a> e x T</div>
[NexT](https://theme-next.org) 是一个优雅而强大的 [Hexo](https://hexo.io/)主题。在这里，您可以构建一个托管在 [GitHub Pages](https://pages.github.com/) 上的静态博客，分享您的生活，并与新朋友进行交流。
参与者公约用来约束在 [NexT](https://github.com/theme-next/hexo-theme-next) 社区中代码更新、问题交流、请求合并等行为。我们期望所有用户相互尊重，礼貌待人。任何违反这些规则的人都将不会被审核，并会在发现后立即被阻止和驱逐。
## 目录
- [我们的保证](#our-pledge)
- [我们的责任](#our-responsibilities)
- [我们的标准](#our-standards)
- [使用范围](#scope)
- [强制执行](#enforcement)
- [联系项目维护者](#contacting-maintainers)
- [来源](#attribution)
<a name="our-pledge"></a>
## 我们的保证
作为此项目的贡献者和维护者，我们承诺尊重所有做出贡献的用户，这些贡献包括了报告问题、发布功能请求、更新文档、提交合并请求以及其他活动。
为了促进一个开放透明且友好的环境，我们作为贡献者和维护者保证：无论年龄、种族、民族、性别认同和表达（方式）、体型、身体健全与否、经验水平、国籍、个人表现、宗教或性别取向，参与者在我们项目和社区中都免于骚扰。
<a name="our-responsibilities"></a>
## 我们的责任
项目维护者有责任为「可接受的行为」标准做出诠释，有权利及责任去删除、编辑、拒绝与本行为标准有所违背的评论（comments）、提交（commits）、代码、wiki 编辑、问题（issues）和其他贡献，以及项目维护者可暂时或永久性的禁止任何他们认为有不适当、威胁、冒犯、有害行为的贡献者。
<a name="our-standards"></a>
## 我们的标准
作为 GitHub 上的一个项目，本项目受到 [GitHub 社区准则](https://help.github.com/articles/github-community-guidelines/)的约束。 此外，作为 npm 托管的项目，[npm 公司的行为准则](https://www.npmjs.com/policies/conduct)也涵盖了本项目。
有助于创造正面环境的行为包括但不限于：
* 使用友好和包容性语言
* 尊重不同的观点和经历
* 耐心地接受建设性批评
* 关注对社区最有利的事情
* 友善对待其他社区成员
身为参与者不能接受的行为包括但不限于：
* 使用与性有关的言语或是图像，以及不受欢迎的性骚扰
* 捣乱/煽动/造谣的行为或进行侮辱/贬损的评论，人身攻击及政治攻击
* 公开或私下的骚扰
* 未经许可地发布他人的个人资料，例如住址或是电子地址
* 其他可以被合理地认定为不恰当或者违反职业操守的行为
<a name="scope"></a>
## 使用范围
当一个人代表该项目或是其社区时，本行为标准适用于其项目社区和公共社区。
根据某人在本社区范围以外发生的违规情况，项目维护者可以认为其不受欢迎，并采取适当措施来保证所有成员的安全性和舒适性。
<a name="enforcement"></a>
## 强制执行
如果您看到违反行为准则的行为，请按以下步骤操作：
1. 让这个人知道他所做的并不合适，并要求他停止或编辑他们的提交信息。该人应立即停止行为并纠正问题。
2. 如果该人没有纠正其行为，或者您不方便与其沟通，请[联系项目维护者](#contacting-maintainers)。上报时，请尽可能多的提供详细信息，链接，截图，上下文或可用于更好地理解和解决情况的其他信息。
3. 收到上报信息后，项目维护者会查看问题，并采取进一步的措施。
一旦项目维护者参与其中，他们将遵循以下一系列步骤，并尽力保护项目成员的利益。任何维护团队认为有必要且适合的所有投诉都将进行审查及调查，并做出相对应的回应。项目小组有对事件回报者有保密的义务。具体执行的方针近一步细节可能会单独公布。
以下是项目维护者根据需要采取的进一步执法步骤：
1. 再次要求停止违规行为。
2. 如果违规者还是没有回应，将会受到正式的警告，并收到项目维护者的移除或修改消息。同时，相关的问题或合并请求将会被锁定。
3. 如果警告后违规行为继续出现，违规者将会被禁言 24 小时。
4. 如果禁言后违规行为继续出现，违规者将会被处罚长期（6-12个月）禁言。
除此之外，项目维护者可以根据需要删除任何违规的消息，图片，贡献等。如果违规行为被认为是对社区成员的严重或直接威胁，包括任何置社区成员于风险的威胁、身体或言语攻击，项目维护者有充分权利自行决定跳过上述任何步骤。
没有切实地遵守或是执行本行为标准的项目维护人员，可能会因项目领导人或是其他成员的决定，暂时或是永久地取消其参与资格。
<a name="contacting-maintainers"></a>
## 联系项目维护者
您可以通过以下任何方法与维护人员联系
* 电子邮件:
* [support@theme-next.org](mailto:support@theme-next.org)
* 即时通信:
* [Gitter](https://gitter.im/theme-next)
* [Riot](https://riot.im/app/#/room/#NexT:matrix.org)
* [Telegram](https://t.me/joinchat/GUNHXA-vZkgSMuimL1VmMw)
<a name="attribution"></a>
## 来源
本行为标准改编自[Contributor Covenant](https://www.contributor-covenant.org/) 和 [WeAllJS Code of Conduct](https://wealljs.org/code-of-conduct)。

226
themes/next/docs/zh-CN/CONTRIBUTING.md Normal file
View File

@ -0,0 +1,226 @@
<div align="right">语言：<a title="英语" href="../../.github/CONTRIBUTING.md">:us:</a>
:cn:
<a title="俄语" href="../ru/CONTRIBUTING.md">:ru:</a></div>
# <div align="center"><a title="Go to homepage" href="https://theme-next.org"><img align="center" width="56" height="56" src="https://raw.githubusercontent.com/theme-next/hexo-theme-next/master/source/images/logo.svg?sanitize=true"></a> e x T</div>
首先，非常感谢大家抽出宝贵时间来让我们的 NexT 主题越变越好。在这里，我们介绍一下 [NexT 主题及其子模块](https://github.com/theme-next) 的开源贡献指南。不过，我们希望大家不要局限于此，更欢迎大家随时进行补充。
## 目录
[如何为 NexT 做贡献](#how-can-i-contribute)
* [你需要了解的](#before-submitting-an-issue)
* [反馈 Bug](#reporting-bugs)
* [提交漏洞](#reporting-security-bugs)
* [提交功能需求](#suggesting-enhancements)
* [提交合并请求](#submitting-a-pull-request)
* [发布版本](#creating-releases)
[规范](#guides)
* [行为规范](#coding-rules)
* [编码规范](#coding-standards)
* [标签规范](#labels-rules)
* [提交信息规范](#commit-messages-rules)
<a name="how-can-i-contribute"></a>
## 如何为 NexT 做贡献
目前 NexT 主题已经从 [iissnan](https://github.com/iissnan/hexo-theme-next) 的个人仓库移动到了 [Theme-Next](https://github.com/theme-next) 组织仓库中，并升级到 V6 版本。在 V6+ 版本中，`next/source/lib` 目录下的第三方依赖库将独立放置在 [Theme-Next](https://github.com/theme-next) 组织仓库中。在大多数情况下，NexT V5 版本仍然能够正常运行，但是如果你想获得更多的功能和帮助，还是建议您 [升级到 NexT V6+ 版本](https://github.com/theme-next/hexo-theme-next/blob/master/docs/UPDATE-FROM-5.1.X.md)，并移步 [Theme-Next](https://github.com/theme-next/hexo-theme-next) 仓库。
<a name="before-submitting-an-issue"></a>
### 你需要了解的
如果你在使用过程中遇到了问题，你可以查阅 FAQs（建设中） 或者 [NexT 帮助文档](https://theme-next.org/docs/)（建设中）。另外，你也可以通过 [这里](https://github.com/theme-next/hexo-theme-next/search?q=&type=Issues&utf8=%E2%9C%93) 进行大致检索，有些问题已经得到解答，你可以自行解决。对于没有解决的 Issue，你也可以继续提问。
如果你在使用过程中发现了 Bug，请再次确认 Bug 在 [最新发布版本](https://github.com/theme-next/hexo-theme-next/releases/latest) 中是否重现。如果 Bug 重现，欢迎你到我们的 [主题仓库](https://github.com/theme-next/hexo-theme-next) 中 [反馈 Bug ](#reporting-bugs) 或者 [提交功能需求](#suggesting-enhancements)，也更期待您 [提交合并请求](#submitting-a-pull-request)。
<a name="reporting-bugs"></a>
### 反馈 Bug
反馈 Bug 前，请再次确认您已经查看了 [你需要了解的](#before-submitting-an-issue) 内容，避免提交重复的 Issue。确定相关仓库后，创建 Issue 并按照 [模板](../../.github/ISSUE_TEMPLATE.md) 尽可能的详细填写相关信息。
请认真遵守如下指南，这样我们才能更好地理解问题，重现问题和解决问题。
* 在标题中清晰准确地描述你的问题。
* 参照如下问题尽可能多的提供信息：
* Bug 是否能够重现？是一直出现还是偶尔出现？
* Bug 是从什么时候开始发生的？
* 如果 Bug 突然发生，使用 [旧版本主题](https://github.com/theme-next/hexo-theme-next/releases) 是否能够重现 Bug？又是从哪个版本开始出现 Bug？
* 你所使用 Node，Hexo 以及 Next 的版本号多少？你可以运行 `node -v` 和 `hexo version` 获取版本号，或者查看文件 `package.json` 的内容。
* 你使用了哪些插件包？查看文件 `package.json` 的内容即可获取。
* 一步步详细你是如何重现 Bug 的，做了什么，使用了哪些功能等等。如果你需要展示代码段，请使用 [Markdown 代码块](https://help.github.com/articles/creating-and-highlighting-code-blocks/) 或 [Github 预览链接](https://help.github.com/articles/creating-a-permanent-link-to-a-code-snippet/) 或 [Gist 链接](https://gist.github.com/)。
* 提供 Bug 的样例，如图像文件、在线演示网址等等。
* 详细描述通过上述重现过程出现的问题。
* 详细描述你期待的结果。
<a name="reporting-security-bugs"></a>
#### 提交漏洞
如果你发现安全问题，请以负责任的方式行事，即不要在公共 Issue 中提交而是直接向我们反馈，这样我们就可以在漏洞被利用之前对其进行修复。请将相关信息发送到 security@theme-next.com（可接受 PGP 加密邮件）。
我们很乐意对任何提交漏洞的人予以特别感谢以便我们修复它。如果你想保持匿名性或使用笔名替代，请告诉我们。我们将充分尊重你的意愿。
<a name="suggesting-enhancements"></a>
### 提交功能需求
提交功能需求前，请再次确认您已经查看了 [你需要了解的](#before-submitting-an-issue) 内容，避免提交重复的 Issue。确定相关仓库后，创建 Issue 并按照 [模板](../../.github/ISSUE_TEMPLATE.md) 尽可能的详细填写相关信息。
请认真遵守如下指南，这样我们才能更好地理解和开发功能需求:pencil:：
* 在标题中清晰准确地描述你的功能需求。
* 详细描述目前所具有的功能和你所期待的功能，并解释为什么需要该功能。
* 提供功能需求的样例，如图像文件、在线演示网址等等。
<a name="submitting-a-pull-request"></a>
### 提交合并请求
提交合并请求前，请再次确认您已经查看了 [你需要了解的](#before-submitting-an-issue) 内容，避免提交重复的合并请求。确定相关仓库后，创建合并请求。更多详细操作过程可以查看 [帮助文档](https://help.github.com/articles/creating-a-pull-request/)。
1. 进入 [hexo-theme-next](https://github.com/theme-next/hexo-theme-next) 主页面，点击`Fork`。
2. 进入到已经`Fork`的个人仓库（`https://github.com/username/hexo-theme-next`），点击 **Clone or download** 并复制该仓库地址。选择本地文件夹，并打开 Git Bash ，输入如下命令并回车，即可完成仓库克隆。
```bash
$ git clone git@github.com:username/hexo-theme-next.git
```
3. 进入 `hexo-theme-next` 本地文件夹，并创建分支。
```bash
$ cd hexo-theme-next
$ git checkout -b patchname
```
4. 本地修改并测试，推送分支。
```bash
$ git add .
$ git commit -m "add commit messamge"
$ git push origin patchname
```
5. 进入 `fork` 后的仓库，切换到新提交的 `patchname` 分支，点击 `patchname` 分支右侧的 **New pull request** 。在 PR 对比页面，正确选择你需要发起合并请求的分支，然后点击 **Create pull request** ，建立一个新的合并申请并描述变动。
请认真遵守如下指南，这样我们才能更好地理解你的合并请求：
* 创建合并请求时，请遵守 [编码规范](#coding-rules) 和 [提交信息规范](#commit-messages-rules)。
* 在标题中清晰准确地描述你的合并请求，不要加入 Issue 编号。
* 按照 [模板](../../.github/PULL_REQUEST_TEMPLATE.md) 尽可能的详细填写相关信息。
* 合并请求需要在所有主题样式中测试通过，并提供所表现功能的样例，如图像文件、在线演示网址等等。
<a name="creating-releases"></a>
### 发布版本
版本发布是将项目发布给用户的一种很好的方式。
1. 进入 GitHub 项目主页，点击 **Releases** 和 **Draft a new release**。
2. 输入你需要发布的版本号。版本控制是基于 [Git tags](https://git-scm.com/book/en/Git-Basics-Tagging) 工作的，建议按照 [About Major and Minor NexT versions](https://github.com/theme-next/hexo-theme-next/issues/187) 确定版本号。
3. 确定你需要发布的分支。除非发布测试版本，通常情况下选择 `master` 分支。
4. 输入发布版本的标题和说明。
- 标题为版本号。
- 所有内容更改的类型包括了 **Breaking Changes**, **Updates**, **Features** 和 **Bug Fixes**。在描述 Breaking Changes 时，使用二级标题分别陈述，描述其他类型时，使用项目列表陈述。
- 使用被动语态，省略主语。
- 所有的变化都需要记录在版本说明中。对于没有使用 PR 的更改，需要添加相应的 commit 编号。如果使用了 PR 进行合并修改，则直接添加相应的 PR 编号即可。
5. 如果您希望随版本一起发布二进制文件（如编译的程序），请在上传二进制文件对话框中手动拖放或选择文件。
6. 如果版本不稳定，请选择 **This is a pre-release**，以通知用户它尚未完全准备好。如果您准备公布您的版本，请点击 **Publish release**。否则，请单击 **Save draft** 以稍后处理。
<a name="guides"></a>
## 规范
<a name="coding-rules"></a>
### 行为规范
为了保证本项目的顺利运作，所有参与人都需要遵守 [行为规范](CODE_OF_CONDUCT.md)。
<a name="coding-standards"></a>
### 编码规范
未完待续。
<a name="labels-rules"></a>
### 标签规范
为了方便维护人员和用户能够快速找到他们想要查看的问题，我们使用“标签”功能对 Pull requests 和 Issues 进行分类。
如果您不确定某个标签的含义，或者不知道将哪些标签应用于 PR 或 issue，千万别错过这个。
Issues 的标签：使用`类型`+`内容`+`结果`的组合
- 类型
- `Irrelevant`: 与 NexT 主题无关的 Issue
- `Duplicate`: 重复提及的 Issue
- `Bug`: 检测到需要进行确认的 Bug
- `Improvement Need`: 需要改进的 Issue
- `Feature Request`: 提出了新功能请求的 Issue
- `High Priority`: 检测到具有高优先级的 Bug 或笔误的 Issue
- `Low Priority`: 检测到具有低优先级的 Bug 或笔误的 Issue
- `Non English`: 需要多语言维护者参与的 Issue
- `Discussion`: 需要进行讨论的 Issue
- `Question`: 提出疑问的 Issue
- `Backlog`: 待解决的 Issue
- `Meta`: 表明使用条款变更的 Issue
- 内容
- `Roadmap`: 与 NexT 主题发展相关的 Issue
- `Hexo`: 与 Hexo 相关的 Issue
- `Scheme [1] - Mist`: 与 Mist 主题相关的 Issue
- `Scheme [2] - Muse`: 与 Muse 主题相关的 Issue
- `Scheme [3] - Pisces`: 与 Pisces 主题相关的 Issue
- `Scheme [4] - Gemini`: 与 Gemini 主题相关的 Issue
- `3rd Party Service`: 与第三方服务相关的 Issue
- `Docs`: 需要添加文档说明的 Issue
- `Configurations`: 与 NexT 主题设置相关的 Issue
- `CSS`: 与 NexT 主题 CSS 文件相关的 Issue
- `Custom`: 与 NexT 主题个性化相关的 Issue
- 结果
- `Wontfix`: 不能或不被修复的 Issue
- `Need More Info`: 需要更多信息的 Issue
- `Need Verify`: 需要开发人员或用户确认 Bug 或解决方法的 Issue
- `Can't Reproduce`: 无法复现的 Issue
- `Verified`: 已经被确认的 Issue
- `Help Wanted`: 需要帮助的 Issue
- `Wait for Answer`: 需要开发人员或用户回复的 Issue
- `Resolved Maybe`: 可能已经解决的 Issue
- `Solved`: 已经解决的 Issue
- `Stale`: 由于长期无人回应被封存的 Issue
Pull requests 的标签：
- `Breaking Change`: 产生重大变动的 Pull request
- `External Change`: 针对外部变动进行更新的 Pull request
- `Bug Fix`: 修复相关 Bug 的 Pull request
- `Docs`: 添加了文档说明的 Pull request
- `New Feature`: 添加了新功能的 Pull request
- `Feature`: 为现有功能提供选项或加成的 Pull request
- `Improvement`: 改进了 NexT 主题的 Pull request
- `i18n`: 更新了翻译的 Pull request
- `Performance`: 提高了 NexT 主题性能的 Pull request
- `Discussion`: 需要进行讨论的 Pull request
- `v6.x`: 与 NexT v6.x 旧版相关的用于修复和改进的 Pull request
- `v7.x`: 与 NexT v7.x 旧版相关的用于修复和改进的 Pull request
<a name="commit-messages-rules"></a>
### 提交信息规范
我们对项目的 git 提交信息格式进行统一格式约定，每条提交信息由 `type`+`subject` 组成，这将提升项目日志的可读性。
- `type` 用于表述此次提交信息的意义，首写字母大写，包括但不局限于如下类型：
* `Build`：基础构建系统或依赖库的变化
* `Ci`：CI 构建系统及其脚本变化
* `Docs`：文档内容变化
* `Feat`：新功能
* `Fix`：Bug 修复
* `Perf`：性能优化
* `Refactor`：重构（即不是新增功能，也不是修改 Bug 的代码变动）
* `Style`：格式（不影响代码运行的变动）
* `Revert`：代码回滚
* `Release`：版本发布
- `subject` 用于简要描述修改变更的内容，如 `Update code highlighting in readme.md`。
* 句尾不要使用符号。
* 使用现在时、祈使句语气。

61
themes/next/docs/zh-CN/DATA-FILES.md Normal file
View File

@ -0,0 +1,61 @@
<h1 align="center">数据文件</h1>
目前，通过 pull 或下载新的 release 版本来更新 NexT 主题的体验并不平滑。当用户使用 `git pull` 更新 NexT 主题时经常需要解决冲突问题，而在手动下载 release 版本时也经常需要手动合并配置。
现在来说，NexT 推荐用户存储部分配置在站点的 `_config.yml` 中，而另一部分在主题的 `_config.yml` 中。这一方式固然可用，但也有一些缺点：
1. 配置项被分裂为两部分；
2. 用户难以弄清何处存放配置选项。
为了解决这一问题，NexT 将利用 Hexo 的[数据文件](https://hexo.io/docs/data-files.html)特性。因为数据文件是在 Hexo 3 中被引入，所以你需要更新至 Hexo 3.0 以后的版本来使用这一特性。
如果你仍然希望使用 Hexo 2.x，你依旧可以按老的方式进行配置。NexT 仍然兼容 Hexo 2.x（但可能会出现错误）。
<h2 align="center">选择 1：Hexo 方式</h2>
使用这一方式，你的全部配置都将置于 hexo 主要配置文件中（`hexo/_config.yml`），并且不需要修改 `next/_config.yml`，或者创建什么其他的文件。但是所有的主题选项必须放置在 `theme_config` 后，并全部增加两个空格的缩进。
如果在新的 release 中出现了任何新的选项，那么你只需要从 `next/_config.yml` 中将他们复制到 `hexo/_config.yml` 中并设置它们的值为你想要的选项。
### 用法
1. 请确认不存在 `hexo/source/_data/next.yml` 文件（如果已存在，请删除）
2. 从主题的 `next/_config.yml` 文件中复制你需要的 NexT 配置项到 `hexo/_config.yml` 中，然后\
2.1. 所有这些配置项右移两个空格（在 Visual Studio Code 中：选中这些文字，<kbd>CTRL</kbd> + <kbd>]</kbd>）。\
2.2. 在这些参数最上方添加一行 `theme_config:`。
### 相关链接
* [Hexo 配置](https://hexo.io/zh-cn/docs/configuration.html)
* [Hexo Pull #757](https://github.com/hexojs/hexo/pull/757)
<h2 align="center">选择 2: NexT 方式</h2>
使用这一方式，你现在可以将你的全部配置置于同一位置（`source/_data/next.yml`），并且不需要修改 `next/_config.yml`。
但是可能无法让所有 Hexo 外部库都准确处理它们的附加选项（举个例子，`hexo-server` 模块只会从 Hexo 默认配置文件中读取选项）。
如果在新的 release 中出现了任何新的选项，那么你只需要从 `next/_config.yml` 中将他们复制到 `source/_data/next.yml` 中并设置它们的值为你想要的选项。
### 用法
1. 请确认你的 Hexo 版本为 3.0 或更高。
2. 在你站点的 `hexo/source/_data` 目录创建一个 `next.yml` 文件（如果 `_data` 目录不存在，请创建之）。
<p align="center">以上步骤之后有 <b>两种选择</b>，请<b>任选其一</b>然后<b>继续后面的步骤</b>。</p>
* **选择 1：`override: false`（默认）**：
1. 检查默认 NexT 配置中的 `override` 选项，必须设置为 `false`。\
在 `next.yml` 文件中，也要设置为 `false`，或者不定义此选项。
2. 从站点的 `_config.yml` 与主题的 `_config.yml` 中复制你需要的选项到 `hexo/source/_data/next.yml` 中。
* **选择 2：`override: true`**：
1. 在 `next.yml` 中设置 `override` 选项为 `true`。
2. 从 `next/_config.yml` 配置文件中复制**所有**的 NexT 主题选项到 `hexo/source/_data/next.yml` 中。
3. 然后，在站点的 `hexo/_config.yml`中需要定义 `theme: next` 选项（如果需要的话，`source_dir: source`）。
4. 使用标准参数来启动服务器，生成或部署（`hexo clean && hexo g -d && hexo s`）。
### 相关链接
* [NexT Issue #328](https://github.com/iissnan/hexo-theme-next/issues/328)

120
themes/next/docs/zh-CN/INSTALLATION.md Normal file
View File

@ -0,0 +1,120 @@
<h1 align="center">安装</h1>
<h2 align="center">步骤 1 &rarr; 进入 Hexo 目录</h2>
进入 **hexo 根**目录。这一目录中应当有 `node_modules`、`source`、`themes` 等若干子目录：
```sh
$ cd hexo
$ ls
_config.yml node_modules package.json public scaffolds source themes
```
<h2 align="center">步骤 2 &rarr; 获取 NexT</h2>
<p align="center">从 GitHub 下载主题。</br>
为了下载这一主题，共有 <b>3 种选项</b>可选。你需要选择其中<b>唯一一个方式</b>。</p>
### 选项 1：下载[最新 release 版本][releases-latest-url]
通常情况下请选择 **stable** 版本。推荐不熟悉的用户按此方式进行。
* 使用 [curl、tar 和 wget][curl-tar-wget-url] 安装：
```sh
$ mkdir themes/next
$ curl -s https://api.github.com/repos/theme-next/hexo-theme-next/releases/latest | grep tarball_url | cut -d '"' -f 4 | wget -i - -O- | tar -zx -C themes/next --strip-components=1
```
这种方式将**仅提供最新的 release 版本**（其中不附带 `.git` 目录）。\
因此，将来你将不可能通过 `git` 更新这一方式安装的主题。\
取而代之的，为了能不丢失你的自定义配置，你可以使用独立的配置文件（例如 [数据文件][docs-data-files-url]）并下载最新版本到旧版本的目录中（或者下载到新的主题目录中并修改 Hexo 配置中的主题名）。
### 选项 2：下载 [tag 指向的 release 版本][releases-url]
在少数情况下将有所帮助，但这并非推荐方式。\
你必须指定一个版本：使用 [tags 列表][tags-url]中的任意 tag 替换 `v6.0.0`。
* 方式 1：使用 [curl 和 tar][curl-tar-url] 安装：
```sh
$ mkdir themes/next
$ curl -L https://api.github.com/repos/theme-next/hexo-theme-next/tarball/v6.0.0 | tar -zxv -C themes/next --strip-components=1
```
和上述的 `curl、tar 和 wget` 方法相同，但只会下载**指定的 release 版本**。
* 方式 2：使用 [git][git-url] 安装：
```sh
$ git clone --branch v6.0.0 https://github.com/theme-next/hexo-theme-next themes/next
```
这一方式将为你下载**指定的 release 版本**（其中包含 `.git` 目录）。\
并且，你可以随时切换到任何已定义的版本号所对应的 tag 的版本。
### 选项 3：下载[最新 master 分支][download-latest-url]
可能**不稳定**，但包含最新的特性。推荐进阶用户和开发者按此方式进行。
* 方式 1：使用 [curl 和 tar][curl-tar-url] 安装：
```sh
$ mkdir themes/next
$ curl -L https://api.github.com/repos/theme-next/hexo-theme-next/tarball | tar -zxv -C themes/next --strip-components=1
```
和上述的 `curl、tar 和 wget` 方法相同，但只会下载**最新 master 分支版本**。\
在有些情况对开发者有所帮助。
* 方式 2：使用 [git][git-url] 安装：
```sh
$ git clone https://github.com/theme-next/hexo-theme-next themes/next
```
这一方式将为你下载**完整仓库**（其中包含 `.git` 目录）。\
你可以随时[使用 git 更新至最新版本][update-with-git-url]并切换至任何有 tag 标记的 release 版本、最新的 master 分支版本、甚至其他分支。\
在绝大多数情况下对用户和开发者友好。
获取 tags 列表：
```sh
$ cd themes/next
$ git tag -l
…
v6.0.0
v6.0.1
v6.0.2
```
例如，假设你想要切换到 `v6.0.1` 这一 [tag 指向的 release 版本][tags-url]。输入如下指令：
```sh
$ git checkout tags/v6.0.1
Note: checking out 'tags/v6.0.1'.
…
HEAD is now at da9cdd2... Release v6.0.1
```
然后，假设你想要切换回 [master 分支][commits-url]，输入如下指令即可：
```sh
$ git checkout master
```
<h2 align="center">步骤 3 &rarr; 完成配置</h2>
在 **hexo 根配置**文件 `_config.yml` 中设置你的主题：
```yml
theme: next
```
[download-latest-url]: https://github.com/theme-next/hexo-theme-next/archive/master.zip
[releases-latest-url]: https://github.com/theme-next/hexo-theme-next/releases/latest
[releases-url]: https://github.com/theme-next/hexo-theme-next/releases
[tags-url]: https://github.com/theme-next/hexo-theme-next/tags
[commits-url]: https://github.com/theme-next/hexo-theme-next/commits/master
[git-url]: http://lmgtfy.com/?q=linux+git+install
[curl-tar-url]: http://lmgtfy.com/?q=linux+curl+tar+install
[curl-tar-wget-url]: http://lmgtfy.com/?q=linux+curl+tar+wget+install
[update-with-git-url]: https://github.com/theme-next/hexo-theme-next/blob/master/docs/zh-CN/README.md#update
[docs-data-files-url]: https://github.com/theme-next/hexo-theme-next/blob/master/docs/zh-CN/DATA-FILES.md

186
themes/next/docs/zh-CN/LEANCLOUD-COUNTER-SECURITY.md Normal file
View File

@ -0,0 +1,186 @@
在配置前，请升级NexT至**v6.0.6**以上。
在配置过程中请注意**博客配置文件**和**主题配置文件**的区别。
---
# 注册Leancloud并创建应用
- 首先，前往Leancloud官网[leancloud.cn](leancloud.cn)进行注册，并登陆。
- 然后点击图示`1`处，进入控制台：
![1](https://lc-cqha0xyi.cn-n1.lcfile.com/fc0c048a1e25dc3d10aa.jpg)
- 接着，点击图示`1`处，创建应用：
![2](https://lc-cqha0xyi.cn-n1.lcfile.com/33a56b754753a5d34b01.jpg)
- 在弹出窗口`1`处输入应用名称（可随意输入，可更改，为演示方便取名为test），并选择`2`处“开发版”，然后点击`3`处创建：
![3](https://lc-cqha0xyi.cn-n1.lcfile.com/649ccfc6f12015d1eefb.jpg)
到这里应用创建完成。
# 建立Counter类并在NexT中启用插件
- 点击`1`处应用名称进入应用管理界面：
![4](https://lc-cqha0xyi.cn-n1.lcfile.com/d0889df29841661e0b9e.jpg)
- 如图，点击侧边栏`1`处创建Class：
![5](https://lc-cqha0xyi.cn-n1.lcfile.com/b0fbc81bd6c19fa09a46.jpg)
- 在弹出窗口`1`处填入`Counter`，勾选`2`处无限制，并点击`3`处创建Class：
![6](https://lc-cqha0xyi.cn-n1.lcfile.com/ae6154d6a55f02f11ebf.jpg)
- 此时类已创建完成。接下来点击图示`1`处进入设置，然后点击`2`处进入应用Key：
![8](https://lc-cqha0xyi.cn-n1.lcfile.com/9501a6372918dd9a8a92.jpg)
- 粘贴`App ID`和`App Key`到**NexT主题配置文件**`_config.yml`对应位置。此时配置文件应如下：
```yml
leancloud_visitors:
enable: true
security: true
app_id: <<your app id>>
app_key: <<your app key>>
```
- 设置Web安全域名确保域名调用安全。点击`1`处进入安全中心，然后在`2`处填写自己博客对应的域名（**注意协议、域名和端口号需严格一致**）：
![9](https://lc-cqha0xyi.cn-n1.lcfile.com/0e537cc4bec2e185201d.jpg)
到这里内容均与Doublemine的[为NexT主题添加文章阅读量统计功能](https://notes.wanghao.work/2015-10-21-%E4%B8%BANexT%E4%B8%BB%E9%A2%98%E6%B7%BB%E5%8A%A0%E6%96%87%E7%AB%A0%E9%98%85%E8%AF%BB%E9%87%8F%E7%BB%9F%E8%AE%A1%E5%8A%9F%E8%83%BD.html#%E9%85%8D%E7%BD%AELeanCloud)这篇文章相同，只不过截图为新版的Leancloud的界面。
# 部署云引擎以保证访客数量不被随意篡改
- 点击左侧`1`处云引擎，然后点击`2`处部署，再点击`3`处在线编辑：
![10](https://lc-cqha0xyi.cn-n1.lcfile.com/d7056dfeeef7c5d66318.jpg)
- 点击`1`处创建函数：
![11](https://lc-cqha0xyi.cn-n1.lcfile.com/2737841bbc2bdd572ae0.jpg)
- 在弹出窗口选择`1`处`Hook`类型，然后`2`处选择`beforeUpdate`，`3`处选择刚才建立的`Counter`类。在`4`中粘贴下方代码后，点`5`处保存。
```javascript
var query = new AV.Query("Counter");
if (request.object.updatedKeys.indexOf('time') !== -1) {
return query.get(request.object.id).then(function (obj) {
if (obj.get("time") > request.object.get("time")) {
throw new AV.Cloud.Error('Invalid update!');
}
return request.object.save();
});
}
```
如图所示：
![12](https://lc-cqha0xyi.cn-n1.lcfile.com/a8e13418ed1d9405315b.jpg)
- 点击保存后应出现类似红框处函数。此时点击`1`处部署：
![13](https://lc-cqha0xyi.cn-n1.lcfile.com/ca56bf2e5fc2a1343565.jpg)
- 在弹出窗口点击`1`处部署：
![14](https://lc-cqha0xyi.cn-n1.lcfile.com/17548c13b3b23c71d845.jpg)
- 等待出现红框处的成功部署信息后，点击`1`处关闭：
![15](https://lc-cqha0xyi.cn-n1.lcfile.com/d2f50de6cefea9fd0ed3.jpg)
至此云引擎已成功部署，任何非法的访客数量更改请求都将失败。
# 进一步设置权限
- 打开**NexT主题配置文件**`_config.yml`，将leancloud_visitors下的security设置为true（如没有则新增）：
```yml
leancloud_visitors:
enable: true
app_id: <<your app id>>
app_key: <<your app key>>
# Dependencies: https://github.com/theme-next/hexo-leancloud-counter-security
security: true
betterPerformance: false
```
**对`betterPerformance`选项的说明：**
由于Leancloud免费版的云引擎存在请求线程数和运行时间限制以及休眠机制，很多时候访客数量加载会很慢。如果设置`betterPerformance`为`true`，则网页则会在提交请求之前直接显示访客人数为查询到的人数+1，以增加用户体验。
- 打开cmd并切换至**博客根目录**，键入以下命令以安装`hexo-leancloud-counter-security`插件：
```
npm install hexo-leancloud-counter-security --save
```
- 打开**博客配置文件**`_config.yml`，新增以下配置：
```yml
leancloud_counter_security:
enable_sync: true
app_id: <<your app id>>
app_key: <<your app key>
username:
password:
```
- 在相同目录键入以下命令：
```
hexo lc-counter register <<username>> <<password>>
```
或
```
hexo lc-counter r <<username>> <<password>>
```
将`<<username>>`和`<<password>>`替换为你自己的用户名和密码（不必与leancloud的账号相同）。此用户名和密码将在hexo部署时使用。
- 打开**博客配置文件**`_config.yml`，将`<<username>>`和`<<password>>`替换为你刚刚设置的用户名和密码：
```yml
leancloud_counter_security:
enable_sync: true
app_id: <<your app id>>
app_key: <<your app key>
username: <<your username>> #如留空则将在部署时询问
password: <<your password>> #建议留空以保证安全性，如留空则将在部署时询问
```
- 在**博客配置文件**`_config.yml`的`deploy`下添加项：
```yml
deploy:
# other deployer
- type: leancloud_counter_security_sync
```
- 返回Leancloud控制台的应用内。依次点击`1` `2`，检查_User表中是否出现一条记录（图示以用户名为admin为例）：
![16](https://lc-cqha0xyi.cn-n1.lcfile.com/99faa5a0e7160e66d506.jpg)
- 点击`1`处进入Counter表，依次点击`2` `3`，打开权限设置：
![17](https://lc-cqha0xyi.cn-n1.lcfile.com/b72a9e64579f5b71749d.jpg)
- <del>点击`1`add_fields后选择`2`指定用户， 并将下两栏留空：</del>此处应与下条create设置相同（选择你所创建的用户）：
![18](https://lc-cqha0xyi.cn-n1.lcfile.com/14a8cb37062693d768ad.jpg)
- 点击`1`create后选择`2`指定用户， 在`3`处键入用户名，点击`4`处后点击`5`处添加：
![19](https://lc-cqha0xyi.cn-n1.lcfile.com/d91714cfd703ef42b94c.jpg)
完成此步操作后，界面应与图示类似：
![20](https://lc-cqha0xyi.cn-n1.lcfile.com/c05e7ec9218820baf412.jpg)
- 点击`1`delete后选择`2`指定用户， 并将下两栏留空：
![21](https://lc-cqha0xyi.cn-n1.lcfile.com/c37b6e20726cfb1d3197.jpg)
至此权限已设置完成，数据库记录只能在本地增删。
每次运行`hexo d`部署的时候，插件都会扫描本地`source/_posts`下的文章并与数据库对比，然后在数据库创建没有录入数据库的文章记录。
如果在**博客配置文件**中留空username或password，则在部署过程中程序会要求输入。
---
原文链接：https://leaferx.online/2018/02/11/lc-security/

291
themes/next/docs/zh-CN/MATH.md Normal file
View File

@ -0,0 +1,291 @@
<h1 align="center">数学公式</h1>
NexT 内部提供数学公式渲染的引擎，这样你就不需要自己手动在模板中引入 JS 或者 CSS；
只需要将 `next/_config.yml` 中 `math` 的 `enable` 选项改为 `true`，并选择对应的渲染引擎即可：
```yml
math:
enable: true
...
engine: mathjax
```
需要注意的是，仅仅将 `math` 的 `enable` 打开**并不能让你看到数学公式**，你还需要**使用对应的 Hexo 渲染器(Renderer)** 才能真正在博客页面中显示出数学公式。引擎对应使用的 Hexo 渲染器会在引擎相关的部分介绍。
<h2 align="center">提供的渲染引擎</h2>
目前，NexT 提供两种数学公式渲染引擎，分别为 [MathJax](https://www.mathjax.org/) 和 [Katex](https://khan.github.io/KaTeX/)，默认为 MathJax。
### MathJax(默认)
如果你选择使用 MathJax 进行数学公式渲染，你需要使用 [hexo-renderer-pandoc](https://github.com/wzpan/hexo-renderer-pandoc) 或者 [hexo-renderer-kramed](https://github.com/sun11/hexo-renderer-kramed) 这两个渲染器的其中一个。
首先，卸载原有的渲染器 `hexo-renderer-marked`，并安装这两种渲染器的**其中一个**：
```sh
npm un hexo-renderer-marked --save
npm i hexo-renderer-pandoc --save # 或者 hexo-renderer-kramed
```
然后在 `next/_config.yml` 中将 `math` 的 `enable` 打开，并选择 `mathjax` 作为渲染引擎。
```yml
math:
enable: true
...
engine: mathjax
#engine: katex
```
执行 Hexo 生成，部署，或者启动服务器：
```sh
hexo clean && hexo g -d
# 或者 hexo clean && hexo s
```
#### 使用 MathJax 给公式编号并引用公式
在新版本的 NexT 主题中，我们加入了公式自动编号和引用功能。下面简要介绍一下如何使用这项功能。
为了使用这项功能，一般来说，你必须把所使用的 LaTeX 公式放在 `equation` 环境里面，采用旧的方法（也就是说，仅仅把公式的每一边用两个 $ 符号包含起来）是无效的。如何引用公式？你只需要在书写公式的时候给公式一个 `\
label{}` 标记（tag），然后在正文中，可以使用 `\ref{}` 或者 `\eqref{}` 命令来引用对应的公式。使用 `\eqref{}` 是推荐的方式，因为如果你使用 `\ref{}`，公式在文中的引用编号将没有圆括号包围。下面介绍几种常见的公式编号例子。
对于简单的公式，使用下面的方式给公式一个标记，
```latex
$$\begin{equation}
e=mc^2
\end{equation}\label{eq1}$$
```
然后，在正文中，你可以轻松引用上述公式，一个简单的例子如下：
```
著名的质能方程 $\eqref{eq1}$ 由爱因斯坦提出 ...
```
对于多行公式，在 `equation` 环境中，你可以使用 `aligned` 环境把公式分成多行，
```latex
$$\begin{equation}
\begin{aligned}
a &= b + c \\
&= d + e + f + g \\
&= h + i
\end{aligned}
\end{equation}\label{eq2}$$
```
要对齐多个公式，我们需要使用 `align` 环境。align 环境中的每个公式都有自己的编号：
```
$$\begin{align}
a &= b + c \label{eq3} \\
x &= yz \label{eq4}\\
l &= m - n \label{eq5}
\end{align}$$
```
在 `align` 环境中，如果你不想给某个或某几个公式编号，那么在这些公式后面使用 [`\nonumber`](https://tex.stackexchange.com/questions/17528/show-equation-number-only-once-in-align-environment) 命令即可。例如：
```latex
$$\begin{align}
-4 + 5x &= 2+y \nonumber \\
w+2 &= -1+w \\
ab &= cb
\end{align}$$
```
有时，你可能会希望采用更加奇特的方式来标记和引用你的公式，你可以通过使用 `\tag{}` 命令来实现，例如：
```latex
$$x+1\over\sqrt{1-x^2} \tag{i}\label{eq_tag}$$
```
如果你想要了解更多信息，请访问 [MathJax 关于公式编号的官方文档](http://docs.mathjax.org/en/latest/tex.html#automatic-equation-numbering)。同时，你也可以访问[这篇博客](https://jdhao.github.io/2018/01/25/hexo-mathjax-equation-number/) 来获取更多细节信息。
### Katex
Katex 渲染引擎相对于 MathJax 来说**大大提高了速度**，而且在关掉 JavaScript 时也能渲染数学公式。
但是 Katex 所支持的东西没有 MathJax 全面，你可以从下面的相关链接中获取更多的信息。
如果你选择使用 Katex 进行数学公式渲染，你需要使用 [hexo-renderer-markdown-it-plus](https://github.com/CHENXCHEN/hexo-renderer-markdown-it-plus) 或者 [hexo-renderer-markdown-it](https://github.com/hexojs/hexo-renderer-markdown-it) 这两种渲染器的其中一个。
首先，卸载原有的渲染器 `hexo-renderer-marked`，并安装这两种渲染器的**其中一个**：
```sh
npm un hexo-renderer-marked --save
npm i hexo-renderer-markdown-it-plus --save
# 或者 hexo-renderer-markdown-it
```
然后在 `next/_config.yml` 中将 `math` 的 `enable` 打开，并选择 `katex` 作为渲染引擎。
```yml
math:
enable: true
...
#engine: mathjax
engine: katex
```
执行 Hexo 生成，部署，或者启动服务器：
```sh
hexo clean && hexo g -d
# 或者 hexo clean && hexo s
```
#### 如果你使用 hexo-renderer-markdown-it
如果你使用 `hexo-renderer-markdown-it`，你还需要为其加上 `markdown-it-katex` 作为插件：
```
npm i markdown-it-katex --save
```
然后在 `hexo/_config.yml` 中将 `markdown-it-katex` 作为插件写入 `hexo-renderer-markdown-it` 的配置中：
```yml
markdown:
render:
html: true
xhtmlOut: false
breaks: true
linkify: true
typographer: true
quotes: '“”‘’'
plugins:
- markdown-it-katex
```
#### 已知的问题
1. 首先请查阅 Katex 的 [Common Issue](https://github.com/Khan/KaTeX#common-issues)
2. 块级公式(例如 `$$...$$`)必须位于空行。\
即在开头的 `$$` 前和在结尾的 `$$` 后不能有除了空白字符以外的其他字符。([#32comment](https://github.com/theme-next/hexo-theme-next/pull/32#issuecomment-357489509))
3. 不支持 Unicode。([#32comment](https://github.com/theme-next/hexo-theme-next/pull/32#issuecomment-357489509))
4. 行内公式(例如 `$...$`)在开头的 `$` 后面和结尾的 `$` 前面**不能含有空格**。([#32comment](https://github.com/theme-next/hexo-theme-next/pull/32#issuecomment-357489509))
5. 如果你在文章的各级标题中(例如 `## 标题`)使用公式。\
那么文章目录中的这个标题会出现 3 次未渲染的公式代码([#32comment](https://github.com/theme-next/hexo-theme-next/pull/32#issuecomment-359018694))
6. 如果你在文章 Title 中使用公式，那么公式将不会被渲染。([#32comment](https://github.com/theme-next/hexo-theme-next/pull/32#issuecomment-359142879))
我们目前使用的 Katex 版本为 0.7.1，这里面可能有某些问题是因为 Katex 版本老旧导致的；
但是，就像上面所说的，数学公式的渲染必须依靠渲染器来支持，目前的 Katex 相关的渲染器仅支持到 Katex 0.7.1；
我们会持续关注相关渲染器的更新，如果有渲染器支持更高版本的 Katex，我们会及时更新我们的 Katex 版本。
### 相关链接
* [Katex 与 MathJax 渲染速度对比](https://www.intmath.com/cg5/katex-mathjax-comparison.php)
* [Katex 支持的功能列表](https://khan.github.io/KaTeX/function-support.html)
<h2 align="center">相关配置说明</h2>
注意，在修改配置选项时，**不要更改配置的缩进**；
目前，NexT 的所有配置都采用**2 空格的缩进**；
如果配置的内容接在冒号后面，那么内容和冒号之间必须有一个空格(例如`enable: true`)
```yml
# Math Equations Render Support
math:
enable: false
# Default(true) will load mathjax/katex script on demand
# That is it only render those page who has 'mathjax: true' in Front-matter.
# If you set it to false, it will load mathjax/katex srcipt EVERY PAGE.
per_page: true
engine: mathjax
#engine: katex
# hexo-renderer-pandoc (or hexo-renderer-kramed) needed to full MathJax support.
mathjax:
# Use 2.7.1 as default, jsdelivr as default CDN, works everywhere even in China
cdn: //cdn.jsdelivr.net/npm/mathjax@2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML
# For direct link to MathJax.js with CloudFlare CDN (cdnjs.cloudflare.com).
#cdn: //cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML
# hexo-renderer-markdown-it-plus (or hexo-renderer-markdown-it with markdown-it-katex plugin)
# needed to full Katex support.
katex:
# Use 0.7.1 as default, jsdelivr as default CDN, works everywhere even in China
cdn: //cdn.jsdelivr.net/npm/katex@0.7.1/dist/katex.min.css
# CDNJS, provided by cloudflare, maybe the best CDN, but not works in China
#cdn: //cdnjs.cloudflare.com/ajax/libs/KaTeX/0.7.1/katex.min.css
```
### enable
`true` 或者 `false`，默认为 `false`。
`true` 是打开数学公式渲染，`false` 则是关闭。
### per_page
`true` 或者 `false`，默认为 `true`。
这个选项是控制是否在每篇文章都渲染数学公式；
默认(`true`) 的行为是**只对 Front-matter 中含有 `mathjax: true` 的文章进行数学公式渲染**。
如果 Front-matter 中不含有 `mathjax: true`，或者 `mathjax: false`，那么 NexT 将不会对这些文章进行数学公式渲染。
例如：
```md
<!-- 这篇文章会渲染数学公式 -->
---
title: 'Will Render Math'
mathjax: true
---
....
```
```md
<!-- 这篇文章不会渲染数学公式 -->
---
title: 'Not Render Math'
mathjax: false
---
....
```
```md
<!-- 这篇文章也不会渲染数学公式 -->
---
title: 'Not Render Math Either'
---
....
```
当你将它设置为 `false` 时，它就会在每个页面都加载 MathJax 或者 Katex 来进行数学公式渲染。
### cdn
MathJax 和 Katex 都提供了 `cdn` 的配置，如果你不知道什么是 `cdn` ，**请不要修改这个配置**。
首先，MathJax 和 Katex 都使用了 [jsDelivr](https://www.jsdelivr.com/) 作为默认 CDN；
之所以选择 jsDelivr 是因为它在全球各地都有比较不错的速度，而且具有中国官方颁布的 ICP 证书，在中国也能比较好地访问。
同时，我们也提供了其他的 CDN 备选方案，包括著名的 [CDNJS](https://cdnjs.com/)。
对于 MathJax 来说，我们目前采用的版本为 2.7.1。
对于 Katex，由于上面提到的版本问题，我们目前采用的版本为 0.7.1。
如果你想尝试我们提供的备选方案以外的 CDN，请注意使用对应的版本。
特别的，对于中国的博客主，或者您的博客访问大部分来源于中国，由于 CDNJS 在部分中国地区被墙，请不要使用 CDNJS 作为 CDN。

156
themes/next/docs/zh-CN/README.md Normal file
View File

@ -0,0 +1,156 @@
<div align="right">语言: <a title="英语" href="../../README.md">:us:</a>
:cn:
<a title="俄语" href="../../docs/ru/README.md">:ru:</a></div>
# <div align="center"><a title="NexT website repository" href="https://github.com/theme-next/theme-next.org"><img align="center" width="56" height="56" src="https://raw.githubusercontent.com/theme-next/hexo-theme-next/master/source/images/logo.svg?sanitize=true"></a> e x T</div>
<p align="center">«NexT» 是一款风格优雅的高质量 <a href="http://hexo.io">Hexo</a> 主题，自点点滴滴中用爱雕琢而成。</p>
<p align="center">
<a href="https://bestpractices.coreinfrastructure.org/projects/2625"><img src="https://bestpractices.coreinfrastructure.org/projects/2625/badge" title="Core Infrastructure Initiative Best Practices"></a>
<a href="https://www.codacy.com/app/theme-next/hexo-theme-next?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=theme-next/hexo-theme-next&amp;utm_campaign=Badge_Grade"><img src="https://api.codacy.com/project/badge/Grade/72f7fe7609c2438a92069f448e5a341a" title="Project Grade"></a>
<a href="https://travis-ci.org/theme-next/hexo-theme-next?branch=master"><img src="https://travis-ci.org/theme-next/hexo-theme-next.svg?branch=master" title="Travis CI [Linux]"></a>
<a href="https://crwd.in/theme-next"><img src="https://d322cqt584bo4o.cloudfront.net/theme-next/localized.svg" title="请花几秒钟来添加或修正翻译！"></a>
<a href="https://github.com/theme-next/hexo-theme-next/releases"><img src="https://badge.fury.io/gh/theme-next%2Fhexo-theme-next.svg"></a>
<a href="http://hexo.io"><img src="https://img.shields.io/badge/hexo-%3E%3D%203.5.0-blue.svg"></a>
<a href="https://github.com/theme-next/hexo-theme-next/blob/master/LICENSE.md"><img src="https://img.shields.io/badge/license-%20AGPL-blue.svg"></a>
</p>
## 即时预览
* :heart_decoration: Muse 主题: [LEAFERx](https://leaferx.online) | [Alex LEE](http://saili.science) | [Miaia](https://11.tt)
* :six_pointed_star: Mist 主题: [uchuhimo](http://uchuhimo.me) | [xirong](http://www.ixirong.com)
* :pisces: Pisces 主题: [Vi](http://notes.iissnan.com) | [Acris](https://acris.me) | [Jiaxi He](http://jiaxi.io)
* :gemini: Gemini 主题: [Ivan.Nginx](https://almostover.ru) | [Raincal](https://raincal.com) | [Dandy](https://dandyxu.me)
更多 «NexT» 的例子参见[这里](https://github.com/iissnan/hexo-theme-next/issues/119)。
## 安装
最简单的安装方式是直接克隆整个仓库：
```sh
$ cd hexo
$ git clone https://github.com/theme-next/hexo-theme-next themes/next
```
此外，如果你想要使用其他方式，你也可以参见[详细安装步骤][docs-installation-url]。
## 插件
在 NexT 配置中你现在可以找到已经被移至外部仓库的依赖项。你可以在[组织主页](https://github.com/theme-next)中找到它们。
例如，假设你想要在你的站点中使用 `fancybox` 插件，请进入 NexT 配置文件，你会看到如下内容：
```yml
# Fancybox
# Dependencies: https://github.com/theme-next/theme-next-fancybox
fancybox: false
```
将 `fancybox` 配置项打开，进入它上面的 «Dependencies» 链接以查看它的安装步骤。
### 例外
如果你使用的插件脚本依赖 CDN，那么需要替换你的 CDN 链接：
例如，假如你使用了 `fancybox` 插件并且配置了 CDN 加载链接，进入 Next 配置文件，你会看到如下内容：
```yml
vendors:
# ...
# Some contents...
# ...
fancybox: # Set or update fancybox cdn url.
fancybox_css: # Set or update fancybox cdn url.
```
通过替换 CDN 链接来替换 [插件列表](https://github.com/theme-next) 项目来升级。
## 更新
你可以通过如下命令更新到最新的 master 分支：
```sh
$ cd themes/next
$ git pull
```
如果你在此过程中收到了任何错误报告 (例如 **«Commit your changes or stash them before you can merge»**)，我们推荐你使用 [Hexo 数据文件][docs-data-files-url]特性。\
然而你也可以通过提交（`Commit`）、贮藏（`Stash`）或忽视（`Discard`）本地更改以绕过这种更新错误。具体方法请参考[这里](https://stackoverflow.com/a/15745424/5861495)。
**如果你想要从 v5.1.x 更新到 v6.0.x，阅读[这篇文档][docs-update-5-1-x-url]。**
## 已知问题
对于仍然遇到 **«[Error: Cannot find module 'hexo-util'](https://github.com/iissnan/hexo-theme-next/issues/1490)»** 这一错误的用户，请检查你的 NPM 版本。
* `> 3`：仍然出现错误吗？请删除 `node_modules` 目录并通过 `npm install` 重新安装。
* `< 3`：请通过 `npm install --save-dev hexo-util` 将 `hexo-util` 依赖手动添加至你的站点依赖包中。
## 贡献你的代码
我们欢迎你贡献出你的一份力量，你可以随时提交 issue 或 fork 本仓库。静候你的 pull request。
## 反馈
* 在 [Stack Overflow][stack-url] 上提问。
* 在 [GitHub Issues][issues-bug-url] 报告Bug。
* 在 [GitHub][issues-feat-url] 请求新的功能。
* 为 [popular feature requests][feat-req-vote-url] 投票。
* 加入我们的 [Gitter][gitter-url] / [Riot][riot-url] / [Telegram][t-chat-url] 聊天。
* 关注我们的 [Telegram Channel][t-news-url] 以获取最新消息。
## 第三方应用程序
* :triangular_flag_on_post: <a title="Hexo Markdown 编辑器" href="https://github.com/zhuzhuyule/HexoEditor" target="_blank">HexoEditor</a>
## 鸣谢
<p align="center">
«NexT» 特别感谢这些支持我们核心基础设施的优质服务：
</p>
<p align="center"><a href="https://github.com"><img align="center" width="100" src="https://github.githubassets.com/images/modules/logos_page/GitHub-Logo.png"></a>
&nbsp;<a href="https://www.netlify.com"><img align="center" width="150" src="https://cdn.netlify.com/15ecf59b59c9d04b88097c6b5d2c7e8a7d1302d0/1b6d6/img/press/logos/full-logo-light.svg"></a></p>
<p align="center">
<sub>GitHub 容许我们托管 Git 仓库，Netlify 容许我们分发文档。</sub>
</p>
<p align="center"><a href="https://crowdin.com"><img align="center" width="180" src="https://support.crowdin.com/assets/logos/crowdin-logo1-small.png"></a></p>
<p align="center">
<sub>Crowdin 容许我们方便地翻译文档。</sub>
</p>
<p align="center"><a href="https://codacy.com"><img align="center" width="155" src="https://user-images.githubusercontent.com/16944225/55026017-623f8f00-5002-11e9-88bf-0d6a5884c6c2.png"></a>
&nbsp;<a href="https://www.browserstack.com"><img align="center" width="140" src="https://www.browserstack.com/images/mail/browserstack-logo-footer.png"></a></p>
<p align="center">
<sub>Codacy 容许我们运行测试套件，BrowserStack 容许我们在真实的浏览器中进行测试。</sub>
</p>
[browser-image]: https://img.shields.io/badge/browser-%20chrome%20%7C%20firefox%20%7C%20opera%20%7C%20safari%20%7C%20ie%20%3E%3D%209-lightgrey.svg
[browser-url]: https://www.browserstack.com
[stack-url]: https://stackoverflow.com/questions/tagged/theme-next
[issues-bug-url]: https://github.com/theme-next/hexo-theme-next/issues/new?assignees=&labels=Bug&template=bug-report.md
[issues-feat-url]: https://github.com/theme-next/hexo-theme-next/issues/new?assignees=&labels=Feature+Request&template=feature-request.md
[feat-req-vote-url]: https://github.com/theme-next/hexo-theme-next/issues?q=is%3Aopen+is%3Aissue+label%3A%22Feature+Request%22+sort%3Areactions-%2B1-desc
[gitter-url]: https://gitter.im/theme-next
[riot-url]: https://riot.im/app/#/room/#theme-next:matrix.org
[t-chat-url]: https://t.me/theme_next_chinese
[t-news-url]: https://t.me/theme_next_news
<!--[rel-image]: https://img.shields.io/github/release/theme-next/hexo-theme-next.svg-->
<!--[rel-image]: https://badge.fury.io/gh/theme-next%2Fhexo-theme-next.svg-->
<!--[mnt-image]: https://img.shields.io/maintenance/yes/2018.svg-->
[download-latest-url]: https://github.com/theme-next/hexo-theme-next/archive/master.zip
[releases-latest-url]: https://github.com/theme-next/hexo-theme-next/releases/latest
<!--[releases-url]: https://github.com/theme-next/hexo-theme-next/releases-->
[tags-url]: https://github.com/theme-next/hexo-theme-next/tags
[commits-url]: https://github.com/theme-next/hexo-theme-next/commits/master
[docs-installation-url]: https://github.com/theme-next/hexo-theme-next/blob/master/docs/zh-CN/INSTALLATION.md
[docs-data-files-url]: https://github.com/theme-next/hexo-theme-next/blob/master/docs/zh-CN/DATA-FILES.md
[docs-update-5-1-x-url]: https://github.com/theme-next/hexo-theme-next/blob/master/docs/zh-CN/UPDATE-FROM-5.1.X.md

35
themes/next/docs/zh-CN/UPDATE-FROM-5.1.X.md Normal file
View File

@ -0,0 +1,35 @@
<h1 align="center">从 NexT v5.1.x 更新</h1>
在 5.1.x 版本和 6.0.x 版本之间没有很大的革命性改进。主版本号变更至 6 主要是因为：
1. 主仓库已从 [iissnan 名下](https://github.com/iissnan/hexo-theme-next) 迁移至 [theme-next](https://github.com/theme-next) 组织。
2. `next/source/lib` 目录下的绝大多数库被移出到了 [NexT 组织的外部仓库](https://github.com/theme-next)中。
3. 第三方插件 [`hexo-wordcount`](https://github.com/willin/hexo-wordcount) 被 [`hexo-symbols-count-time`](https://github.com/theme-next/hexo-symbols-count-time) 所取代，因为 `hexo-symbols-count-time` 没有任何外部 nodejs 依赖、也没有会导致生成站点时的性能问题 [language filter](https://github.com/willin/hexo-wordcount/issues/7)。
推荐通过如下步骤从 v5 升级到 v6：
1. 并不修改原有的 `next` 目录，而只是复制部分 NexT 文件：
1. `config.yml` 或 `next.yml`（如果你使用了[数据文件](DATA-FILES.md)）。
2. 自定义的 CSS 配置，它们应在 `next/source/css/_custom/*` 和 `next/source/css/_variables/*` 中。
3. 自定义的排布配置，它们应在 `next/layout/_custom/*` 中。
4. 任何其它可能的附加自定义内容；为了定位它们，你可以通过某些工具在仓库间比较。
2. 克隆新的 v6.x 仓库到任一异于 `next` 的目录（如 `next-reloaded`）：
```sh
$ git clone https://github.com/theme-next/hexo-theme-next themes/next-reloaded
```
如此，你可以在不修改原有的 NexT v5.1.x 目录的同时使用 `next-reloaded` 目录中的新版本主题。
3. 在 Hexo 的主配置文件中设置主题：
```yml
...
theme: next-reloaded
...
```
如此，你的 `next-reloaded` 主题将在生成站点时被加载。如果你遇到了任何错误、或只是不喜欢这一新版本，你可以随时切换回旧的 v5.1.x 版本。
4. 更新语言配置
从 v6.0.3版本起，`zh-Hans`改名为`zh-CN`：https://github.com/theme-next/hexo-theme-next/releases/tag/v6.0.3
升级到v6.0.3及以后版本的用户，需要显式修改`_config.xml`里的language配置，否则语言显示不正确。
关于第三方库的启用，参见[这里](https://github.com/theme-next/hexo-theme-next/blob/master/docs/zh-CN/INSTALLATION.md#插件)。