diff --git a/source/zh-cn/api/box.md b/source/zh-cn/api/box.md index c9dbe4b9e5..14576dda81 100644 --- a/source/zh-cn/api/box.md +++ b/source/zh-cn/api/box.md @@ -2,13 +2,15 @@ title: Box --- -「Box」是 Hexo 用来处理特定文件夹中的文件的容器，在 Hexo 中有两个 Box，分别是 `hexo.source` 和 `hexo.theme`，前者用于处理 `source` 文件夹，而后者用于处理主题文件夹。 +Box is a container used for processing files in a specified folder. 「Box」是 Hexo 用来处理特定文件夹中的文件的容器，在 Hexo 中有两个 Box，分别是 `hexo.source` 和 `hexo.theme`，前者用于处理 `source` 文件夹，而后者用于处理主题文件夹。 The former is used to process the `source` folder and the latter to process the `theme` folder. ## 加载文件 -Box 提供了两种方法来加载文件：`process`, `watch`，前者用于加载文件夹内的所有文件；而后者除了执行 `process` 以外，还会继续监视文件变动。 +Box 提供了两种方法来加载文件：`process`, `watch`，前者用于加载文件夹内的所有文件；而后者除了执行 `process` 以外，还会继续监视文件变动。 `process` loads all files in the folder. `watch` does the same, but also starts watching for file changes. ```js +box.process().then(function () { + // ... box.process().then(function () { // ... }); @@ -16,22 +18,23 @@ box.process().then(function () { box.watch().then(function () { // 之后可调用 box.unwatch()，停止监视文件 }); +}); ``` ## 比对路径 -Box 提供了多种比对路径的模式，您可以以使用正则表达式（regular expression）、函数、或是 Express 风格的模式字符串，例如： +Box provides many ways for path matching. Box 提供了多种比对路径的模式，您可以以使用正则表达式（regular expression）、函数、或是 Express 风格的模式字符串，例如： For example: ```plain posts/:id => posts/89 posts/*path => posts/2015/title ``` -您可以以参考 [util.Pattern] 以获得更多信息。 +您可以以参考 [util.Pattern][] 以获得更多信息。 ## 处理器（Processor） -处理器（Processor）是 Box 中非常重要的元素，它用于处理文件，您可以使用上述的路径对比来限制该处理器所要处理的文件类型。使用 `addProcessor` 来添加处理器。 +处理器（Processor）是 Box 中非常重要的元素，它用于处理文件，您可以使用上述的路径对比来限制该处理器所要处理的文件类型。 You can use path matching as described above to restrict what exactly the processor should process. 使用 `addProcessor` 来添加处理器。 ```js box.addProcessor("posts/:id", function (file) { @@ -39,24 +42,24 @@ box.addProcessor("posts/:id", function (file) { }); ``` -Box 在处理时会把目前处理的文件内容（`file`）传给处理器，您可以通过此参数获得该文件的数据。 +Box passes the content of matched files to processors. This information can then be read straight from the `file` argument in the callback: -| 属性 | 描述 | -| -------- | --------------------------------------------------- | +| 属性 | 描述 | +| -------- | --------------------------------------------- | | `source` | 文件完整路径 | -| `path` | 文件相对于 Box 的路径 | -| `type` | 文件类型。有 `create`, `update`, `skip`, `delete`。 | -| `params` | 从路径对比中取得的信息 | +| `path` | 文件相对于 Box 的路径 | +| `type` | 文件类型。 有 `create`, `update`, `skip`, `delete`。 | +| `params` | 从路径对比中取得的信息 | Box 还提供了一些方法，让您无须手动处理文件 I/O。 -| 方法 | 描述 | -| ------------ | ---------------- | -| `read` | 读取文件 | -| `readSync` | 同步读取文件 | -| `stat` | 读取文件状态 | +| 方法 | 描述 | +| ------------ | -------- | +| `read` | 读取文件 | +| `readSync` | 同步读取文件 | +| `stat` | 读取文件状态 | | `statSync` | 同步读取文件状态 | -| `render` | 渲染文件 | -| `renderSync` | 同步渲染文件 | +| `render` | 渲染文件 | +| `renderSync` | 同步渲染文件 | [util.Pattern]: https://github.com/hexojs/hexo-util#patternrule diff --git a/source/zh-cn/api/console.md b/source/zh-cn/api/console.md index 31a96709f0..f12ff274a3 100644 --- a/source/zh-cn/api/console.md +++ b/source/zh-cn/api/console.md @@ -2,7 +2,7 @@ title: 控制台（Console） --- -控制台是 Hexo 与开发者之间沟通的桥梁。它注册并描述了可用的控制台命令。 +控制台是 Hexo 与开发者之间沟通的桥梁。 它注册并描述了可用的控制台命令。 ## 概要 @@ -10,21 +10,22 @@ title: 控制台（Console） hexo.extend.console.register(name, desc, options, function (args) { // ... }); +}); ``` -| 参数 | 描述 | -| --------- | ---- | +| Argument | 描述 | +| --------- | -- | | `name` | 名称 | | `desc` | 描述 | | `options` | 选项 | -在函数中会传入 `args` 参数，此参数是使用者在终端中所传入的参数，是一个经 [Minimist] 解析的对象。 +An argument `args` will be passed into the function. This is the argument that users type into the terminal. It's parsed by [Minimist][]. ## 选项 ### 用法 -控制台的操作方法，例如： +The usage of a console command. For example: ```js { @@ -33,9 +34,9 @@ hexo.extend.console.register(name, desc, options, function (args) { // hexo new [layout] ``` -### 参数 +### arguments -控制台各个参数的说明，例如： +控制台各个参数的说明，例如： For example: ```js { @@ -46,9 +47,9 @@ hexo.extend.console.register(name, desc, options, function (args) { } ``` -### 选项 +### options -控制台的各个选项的说明，例如： +控制台的各个选项的说明，例如： For example: ```js { @@ -56,7 +57,7 @@ hexo.extend.console.register(name, desc, options, function (args) { } ``` -### 描述 +### desc 关于控制台命令的更详细的信息。 diff --git a/source/zh-cn/api/deployer.md b/source/zh-cn/api/deployer.md index b7503280a2..e14d6c64f0 100644 --- a/source/zh-cn/api/deployer.md +++ b/source/zh-cn/api/deployer.md @@ -10,6 +10,7 @@ title: 部署器（Deployer） hexo.extend.deployer.register(name, function (args) { // ... }); +}); ``` -在函数中会传入 `args` 参数，该参数包含了 `_config.yml` 中的 `deploy` 参数值，以及开发者在终端中所传入的参数。 +在函数中会传入 `args` 参数，该参数包含了 `_config.yml` 中的 `deploy` 参数值，以及开发者在终端中所传入的参数。 It contains the `deploy` value set in `_config.yml`, as well as the exact input users typed into their terminal. diff --git a/source/zh-cn/api/events.md b/source/zh-cn/api/events.md index babfc44fe6..b48044851a 100644 --- a/source/zh-cn/api/events.md +++ b/source/zh-cn/api/events.md @@ -2,15 +2,15 @@ title: 事件 --- -Hexo 继承了 [EventEmitter]，您可以用 `on` 方法监听 Hexo 所发布的事件，也可以使用 `emit` 方法对 Hexo 发布事件，更详细的说明请参阅 Node.js 的 API。 +Hexo 继承了 [EventEmitter][]，您可以用 `on` 方法监听 Hexo 所发布的事件，也可以使用 `emit` 方法对 Hexo 发布事件，更详细的说明请参阅 Node.js 的 API。 Use the `on` method to listen for events emitted by Hexo, and use the `emit` method to emit events. For more information, refer to the Node.js API documentation. ### deployBefore -在部署完成前发布。 +Emitted before deployment begins. ### deployAfter -在部署成功后发布。 +Emitted after deployment finishes. ### exit @@ -18,15 +18,15 @@ Hexo 继承了 [EventEmitter]，您可以用 `on` 方法监听 Hexo 所发布的 ### generateBefore -在静态文件生成前发布。 +Emitted before generation begins. ### generateAfter -在静态文件生成后发布。 +Emitted after generation finishes. ### new -在文章文件建立后发布。该事件返回文章参数。 +在文章文件建立后发布。 该事件返回文章参数。 ```js hexo.on("new", function (post) { @@ -34,18 +34,18 @@ hexo.on("new", function (post) { }); ``` -| 数据 | 描述 | -| -------------- | ------------------ | +| 数据 | 描述 | +| -------------- | --------- | | `post.path` | 文章文件的完整路径 | -| `post.content` | 文章文件的内容 | +| `post.content` | 文章文件的内容 | ### processBefore -在处理原始文件前发布。此事件会返回一个路径，代表 盒（Box）的根目录。 +在处理原始文件前发布。 此事件会返回一个路径，代表 盒（Box）的根目录。 ### processAfter -在原始文件处理后发布。此事件会返回一个路径，代表 盒（Box）的根目录。 +在原始文件处理后发布。 此事件会返回一个路径，代表 盒（Box）的根目录。 ### ready diff --git a/source/zh-cn/api/filter.md b/source/zh-cn/api/filter.md index 81585bd909..27d8c89556 100644 --- a/source/zh-cn/api/filter.md +++ b/source/zh-cn/api/filter.md @@ -2,7 +2,7 @@ title: 过滤器（Filter） --- -过滤器用于修改特定文件，Hexo 将这些文件依序传给过滤器，而过滤器可以针对文件进行修改，这个概念借鉴自 [WordPress](http://codex.wordpress.org/Plugin_API#Filters)。 +A filter is used to modify some specified data. Hexo passes data to filters in sequence and the filters then modify the data one after the other. This concept was borrowed from [WordPress](http://codex.wordpress.org/Plugin_API#Filters). ## 概要 @@ -16,10 +16,16 @@ hexo.extend.filter.register(type, function() { const { config: themeCfg } = this.theme; if (themeCfg.fancybox) // do something... +}, priority); + + // Theme configuration + const { config: themeCfg } = this.theme; + if (themeCfg.fancybox) // do something... + }, priority); ``` -您可以指定过滤器的优先级 `priority`，`priority` 值越低，过滤器会越早执行，默认的 `priority` 是 10。我们建议提供配置选项如 `hexo.config.your_plugin.priority`、让用户自行决定过滤器的优先级。 +You can define the `priority`. Lower `priority` means that it will be executed first. 您可以指定过滤器的优先级 `priority`，`priority` 值越低，过滤器会越早执行，默认的 `priority` 是 10。 我们建议提供配置选项如 `hexo.config.your_plugin.priority`、让用户自行决定过滤器的优先级。 ## 执行过滤器 @@ -28,12 +34,12 @@ hexo.extend.filter.exec(type, data, options); hexo.extend.filter.execSync(type, data, options); ``` -| 选项 | 描述 | -| --------- | ------------------ | -| `context` | Context | -| `args` | 参数。必须为数组。 | +| 选项 | 描述 | +| --------- | ---------- | +| `context` | Context | +| `args` | 参数。 必须为数组。 | -`data` 会作为第一个参数传入每个过滤器，而您可以在过滤器中通过返回值改变下一个过滤器中的 `data`，如果什么都没有返回的话则会保持原本的 `data`。您还可以使用 `args` 指定过滤器的其他参数。举例来说： +`data` 会作为第一个参数传入每个过滤器，而您可以在过滤器中通过返回值改变下一个过滤器中的 `data`，如果什么都没有返回的话则会保持原本的 `data`。 The `data` passed into the next filter can be modified by returning a new value. If nothing is returned, the data remains unmodified. 您还可以使用 `args` 指定过滤器的其他参数。 举例来说： ```js hexo.extend.filter.register("test", function (data, arg1, arg2) { @@ -94,7 +100,7 @@ hexo.extend.filter.unregister("example", require("path/to/filter")); ### before_post_render -在文章开始渲染前执行。您可以参考 [文章渲染](posts.html#渲染) 以了解执行顺序。 +在文章开始渲染前执行。 您可以参考 [文章渲染](posts.html#渲染) 以了解执行顺序。 举例来说，把标题转为小写： @@ -107,7 +113,7 @@ hexo.extend.filter.register("before_post_render", function (data) { ### after_post_render -在文章渲染完成后执行。您可以参考 [文章渲染](posts.html#渲染) 以了解执行顺序。 +在文章渲染完成后执行。 您可以参考 [文章渲染](posts.html#渲染) 以了解执行顺序。 举例来说，把 `@username` 取代为 Twitter 的开发者链接。 @@ -139,16 +145,18 @@ hexo.extend.filter.register("before_exit", function () { hexo.extend.filter.register("before_generate", function () { // ... }); +}); ``` ### after_generate -在生成器解析后执行。 +Executed after generation finishes. ```js hexo.extend.filter.register("after_generate", function () { // ... }); +}); ``` ### template_locals @@ -172,6 +180,7 @@ hexo.extend.filter.register("template_locals", function (locals) { hexo.extend.filter.register("after_init", function () { // ... }); +}); ``` ### new_post_path @@ -182,25 +191,37 @@ hexo.extend.filter.register("after_init", function () { hexo.extend.filter.register("new_post_path", function (data, replace) { // ... }); +}); ``` ### post_permalink -用来决定文章的永久链接。 +Used to determine the permalink of posts. ```js hexo.extend.filter.register("post_permalink", function (data) { // ... }); +}); ``` ### after_render -在渲染后执行，您可以参考 [渲染](rendering.html#after-render-过滤器) 以了解更多信息。 +Executed after rendering finishes. 在渲染后执行，您可以参考 [渲染](rendering.html#after-render-过滤器) 以了解更多信息。 + +### after_clean + +Executed after generated files and cache are removed with `hexo clean` command. + +```js +hexo.extend.filter.register("before_exit", function () { + // ... +}); +``` ### server_middleware -向服务器添加中间件（Middleware）。`app` 是一个 [Connect] 实例。 +向服务器添加中间件（Middleware）。 `app` 是一个 [Connect][] 实例。 举例来说，在响应头中新增 `X-Powered-By: Hexo`。 diff --git a/source/zh-cn/api/generator.md b/source/zh-cn/api/generator.md index bf43ba9d4f..ccfed5c2cb 100644 --- a/source/zh-cn/api/generator.md +++ b/source/zh-cn/api/generator.md @@ -8,9 +8,10 @@ title: 生成器（Generator） ```js hexo.extend.generator.register(name, function (locals) {}); +}); ``` -`locals` 参数会被传递到此函数，其中包含 [网站变量](../docs/variables.html#网站变量)，请尽量利用此参数取得网站数据，避免直接访问数据库。 +`locals` 参数会被传递到此函数，其中包含 [网站变量](../docs/variables.html#网站变量)，请尽量利用此参数取得网站数据，避免直接访问数据库。 You should use this argument to get the website data, thereby avoiding having to access the database directly. ## 更新路由 @@ -30,21 +31,21 @@ hexo.extend.generator.register("test", function (locals) { }); ``` -| 属性 | 描述 | -| -------- | ----------------------------------------------------------------------------------- | -| `path` | 路径。不可包含开头的 `/`。 | -| `data` | 数据 | -| `layout` | 布局。指定用于渲染的模板，可为字符串或数组，如果省略此属性的话则会直接输出 `data`。 | +| 属性 | 描述 | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `path` | 路径。 不可包含开头的 `/`。 | +| `data` | 数据 | +| `layout` | 布局。 Specify the layouts for rendering. The value can be a string or an array. If it's ignored then the route will return `data` directly. | -在原始文件更新时，Hexo 会执行所有生成器并重建路由，**请直接回传数据，不要直接操作路由**。 +在原始文件更新时，Hexo 会执行所有生成器并重建路由，**请直接回传数据，不要直接操作路由**。 **Please return the data and do not access the router directly.** ## 示例 ### 归档页面 -在 `archives/index.html` 建立一归档页面，把所有文章当作数据传入模板内，这个数据也就等同于模板中的 `page` 变量。 +Create an archive page at `archives/index.html`. We pass all posts as data to the templates. 在 `archives/index.html` 建立一归档页面，把所有文章当作数据传入模板内，这个数据也就等同于模板中的 `page` 变量。 -然后，设置 `layout` 属性好让 Hexo 使用主题模板来渲染，在此例中同时设定了两个布局，当 `archive` 布局不存在时，会继续尝试 `index` 布局。 +Next, set the `layout` attribute to render with the theme templates. We're setting two layouts in this example: if the `archive` layout doesn't exist, the `index` layout will be used instead. ```js hexo.extend.generator.register("archive", function (locals) { @@ -58,7 +59,7 @@ hexo.extend.generator.register("archive", function (locals) { ### 有分页的归档页面 -您可以通过 [hexo-pagination] 这个方便的官方工具来轻松建立分页归档。 +您可以通过 [hexo-pagination][] 这个方便的官方工具来轻松建立分页归档。 ```js var pagination = require("hexo-pagination"); diff --git a/source/zh-cn/api/helper.md b/source/zh-cn/api/helper.md index 6c287ee0de..98ea2ecd55 100644 --- a/source/zh-cn/api/helper.md +++ b/source/zh-cn/api/helper.md @@ -2,7 +2,7 @@ title: 辅助函数（Helper） --- -辅助函数帮助您在模板中快速插入内容，建议您把复杂的代码放在辅助函数而非模板中。 +辅助函数帮助您在模板中快速插入内容，建议您把复杂的代码放在辅助函数而非模板中。 We recommend using helpers instead of templates when you're dealing with more complicated code. 辅助函数不能从 `source` 的文件中访问。 @@ -12,6 +12,7 @@ title: 辅助函数（Helper） hexo.extend.helper.register(name, function () { // ... }); +}); ``` ## 示例 @@ -35,7 +36,7 @@ hexo.extend.helper.register("js", function (path) { ### 如何在我的自定义 helper 中使用另外一个已经注册的 helper？ -所有的辅助函数都在同一个上下文中执行。例如，在一个自定义的辅助函数中使用 [`url_for()`](/zh-cn/docs/helpers#url-for)： +所有的辅助函数都在同一个上下文中执行。 例如，在一个自定义的辅助函数中使用 [`url_for()`](/zh-cn/docs/helpers#url-for)： ```js hexo.extend.helper.register("lorem", function (path) { diff --git a/source/zh-cn/api/index.md b/source/zh-cn/api/index.md index e0bbf77f17..30c489dd47 100644 --- a/source/zh-cn/api/index.md +++ b/source/zh-cn/api/index.md @@ -2,13 +2,13 @@ title: API --- -本文件提供您更丰富的 API 信息，使您更容易修改 Hexo 源代码或编写插件。如果您只是想查询 Hexo 的基本使用方法，请参阅 [文档](../docs/)。 +本文件提供您更丰富的 API 信息，使您更容易修改 Hexo 源代码或编写插件。 如果您只是想查询 Hexo 的基本使用方法，请参阅 [文档](../docs/)。 在开始之前，请注意本文件仅适用于 Hexo 3 及以上版本。 ## 初始化 -首先，我们必须建立一个 Hexo 实例（instance），第一个参数是网站的根目录，也就是 `base_dir`，而第二个参数则是初始化的选项。接着执行 `init` 方法后，Hexo 会加载插件及配置文件。 +First, we have to create a Hexo instance. 首先，我们必须建立一个 Hexo 实例（instance），第一个参数是网站的根目录，也就是 `base_dir`，而第二个参数则是初始化的选项。 接着执行 `init` 方法后，Hexo 会加载插件及配置文件。 ```js var Hexo = require("hexo"); @@ -17,23 +17,26 @@ var hexo = new Hexo(process.cwd(), {}); hexo.init().then(function () { // ... }); +}); ``` -| 参数 | 描述 | 默认值 | -| ------------------ | -------------------------------------------------------------------------------- | ------------------------------------ | -| `debug` | 开启调试模式。在终端中显示调试信息，并在根目录中存储 `debug.log` 日志文件。 | `false` | -| `safe` | 开启安全模式。不加载任何插件。 | `false` | -| `silent` | 开启安静模式。不在终端中显示任何信息。 | `false` | -| `config` | 指定配置文件的路径。 | `_config.yml` | -| `draft` / `drafts` | 是否将草稿加入到文章列表中。<br>例如在 `hexo.locals.get('posts')` 中获取草稿内容 | \_config.yml 中 `render_drafts` 的值 | +| Option | 描述 | 默认值 | +| ------------------ | --------------------------------------------------------------- | ----------------------------------- | +| `debug` | 开启调试模式。 在终端中显示调试信息，并在根目录中存储 `debug.log` 日志文件。 | `false` | +| `safe` | 开启安全模式。 不加载任何插件。 | `false` | +| `silent` | 开启安静模式。 不在终端中显示任何信息。 | `false` | +| `config` | 指定配置文件的路径。 | `_config.yml` | +| `draft` / `drafts` | 是否将草稿加入到文章列表中。 <br>例如在 `hexo.locals.get('posts')` 中获取草稿内容 | \_config.yml 中 `render_drafts` 的值 | ## 加载文件 -Hexo 提供了两种方法来加载文件：`load`, `watch`，前者用于加载 `source` 文件夹内的所有文件及主题资源；而后者除了执行 `load` 以外，还会继续监视文件变动。 +Hexo 提供了两种方法来加载文件：`load`, `watch`，前者用于加载 `source` 文件夹内的所有文件及主题资源；而后者除了执行 `load` 以外，还会继续监视文件变动。 `load` is used for loading all files in the `source` folder as well as the theme data. `watch` does the same things `load` does, but will also start watching for file changes continuously. -这两个方法实际上所做的，就是加载文件列表，并把文件传给相对应的处理器（Processor），当文件全部处理完毕后，就会执行生成器（Generator）来建立路由。 +Both methods will load the list of files and pass them to the corresponding processors. After all files have been processed, they will call upon the generators to create the routes. ```js +hexo.load().then(function () { + // ... hexo.load().then(function () { // ... }); @@ -41,21 +44,29 @@ hexo.load().then(function () { hexo.watch().then(function () { // 之后可以调用 hexo.unwatch()，停止监视文件 }); +}); ``` ## 执行指令 -您可以通过 `call` 方法来调用控制台（Console），第一个参数是控制台的名称，而第二个参数是选项——根据不同控制台有所不同。 +Any console command can be called explicitly using the `call` method on the Hexo instance. Such a call takes two arguments: the name of the console command, and an options argument. Different options are available for the different console commands. ```js hexo.call("generate", {}).then(function () { // ... }); +}); +``` + +```js +hexo.call("list", { _: ["post"] }).then(function () { + // ... +}); ``` ## 退出 -无论控制台命令完成与否，都应调用 `exit` 方法。这样 Hexo 就能优雅地退出，并完成保存数据库等重要工作。 +无论控制台命令完成与否，都应调用 `exit` 方法。 这样 Hexo 就能优雅地退出，并完成保存数据库等重要工作。 ```js hexo diff --git a/source/zh-cn/api/injector.md b/source/zh-cn/api/injector.md index d07af697ac..6296cdfa53 100644 --- a/source/zh-cn/api/injector.md +++ b/source/zh-cn/api/injector.md @@ -2,7 +2,7 @@ title: 注入器（Injector） --- -注入器被用于将静态代码片段注入生成的 HTML 的 `<head>` 和/或 `<body>` 中。Hexo 将在 `after_render:html` 过滤器 **之前** 完成注入。 +注入器被用于将静态代码片段注入生成的 HTML 的 `<head>` 和/或 `<body>` 中。 Hexo 将在 `after_render:html` 过滤器 **之前** 完成注入。 ## 概要 @@ -12,7 +12,9 @@ hexo.extend.injector.register(entry, value, to); ### entry `<string>` -代码片段注入的位置，接受以下值： +Where the code will be injected inside the HTML. + +Support those values: - `head_begin`: 注入在 `<head>` 之后（默认） - `head_end`: 注入在 `</head>` 之前 @@ -27,7 +29,7 @@ hexo.extend.injector.register(entry, value, to); ### to `<string>` -需要注入代码片段的页面类型，接受以下值： +Which page will code snippets being injected. - `default`: 注入到每个页面（默认值） - `home`: 只注入到主页（`is_home()` 为 `true` 的页面） @@ -69,7 +71,7 @@ hexo.extend.injector.register("body_end", () => { }); ``` -上述代码将会把 `APlayer.min.css`（`<link>` 标签）和 `APlayer.min.js` （`<script>` 标签）注入到所有 layout 为 `music` 的页面的 `</head>` 和 `</body>` 之前，以及将 `jquery.js`（`<script>` 标签）注入到每一个生成的页面的 `</body>` 之前。 +上述代码将会把 `APlayer.min.css`（`<link>` 标签）和 `APlayer.min.js` （`<script>` 标签）注入到所有 layout 为 `music` 的页面的 `</head>` 和 `</body>` 之前，以及将 `jquery.js`（`<script>` 标签）注入到每一个生成的页面的 `</body>` 之前。 Also, `jquery.js` (`<script>` tag) will be injected to `</body>` of every page generated. ## 访问用户配置 diff --git a/source/zh-cn/api/locals.md b/source/zh-cn/api/locals.md index d759e5d118..60ee9a2261 100644 --- a/source/zh-cn/api/locals.md +++ b/source/zh-cn/api/locals.md @@ -6,8 +6,8 @@ title: 局部变量 ## 默认变量 -| 变量 | 描述 | -| ------------ | -------- | +| 变量 | 描述 | +| ------------ | ---- | | `posts` | 所有文章 | | `pages` | 所有分页 | | `categories` | 所有分类 | @@ -25,6 +25,7 @@ hexo.locals.get("posts"); hexo.locals.set('posts', function(){ return ... }); +}); ``` ## 移除变量 diff --git a/source/zh-cn/api/migrator.md b/source/zh-cn/api/migrator.md index cd71da4fe7..1f1f8c47df 100644 --- a/source/zh-cn/api/migrator.md +++ b/source/zh-cn/api/migrator.md @@ -1,5 +1,5 @@ --- -title: 迁移器（Migrator） +title: Migrator --- 迁移器帮助开发者从其他系统迁移到 Hexo。 @@ -10,6 +10,7 @@ title: 迁移器（Migrator） hexo.extend.migrator.register(name, function (args) { // ... }); +}); ``` -在函数中需要传入 `args` 参数，该参数包含了开发者在终端中所传入的参数。 +在函数中需要传入 `args` 参数，该参数包含了开发者在终端中所传入的参数。 This argument will contain the user's input into the terminal. diff --git a/source/zh-cn/api/posts.md b/source/zh-cn/api/posts.md index a40ae10380..17a0e38186 100644 --- a/source/zh-cn/api/posts.md +++ b/source/zh-cn/api/posts.md @@ -2,26 +2,26 @@ title: 文章 --- -## 新建文章 +## Create a Post ```js hexo.post.create(data, replace); ``` -| 参数 | 描述 | -| --------- | ------------ | -| `data` | 数据 | +| Argument | 描述 | +| --------- | ------ | +| `data` | 数据 | | `replace` | 替换现有文件 | -您可以在 `data` 中指定文章的属性，除了以下属性之外，其他属性也会被加到 front-matter 中。 +The attributes of a post can be defined in `data`. The table below is not exhaustive. Additional attributes may be appended to the front-matter. -| 属性 | 描述 | -| -------- | --------------------------------------------------- | -| `title` | 标题 | -| `slug` | 网址 | -| `layout` | 布局。默认为 `default_layout` 参数。 | -| `path` | 路径。默认会根据 `new_post_path` 参数创建文章路径。 | -| `date` | 日期。默认为当前时间。 | +| Data | 描述 | +| -------- | ----------------------------------- | +| `title` | 标题 | +| `slug` | 网址 | +| `layout` | 布局。 默认为 `default_layout` 参数。 | +| `path` | 路径。 默认会根据 `new_post_path` 参数创建文章路径。 | +| `date` | 日期。 默认为当前时间。 | ## 发布草稿 @@ -29,17 +29,17 @@ hexo.post.create(data, replace); hexo.post.publish(data, replace); ``` -| 参数 | 描述 | -| --------- | ------------ | -| `data` | 数据 | +| Argument | 描述 | +| --------- | ------ | +| `data` | 数据 | | `replace` | 替换现有文件 | -您可以在 `data` 中指定文章的属性，除了以下的属性之外，其他属性也会被加到 front-matter 中。 +The attributes of a post can be defined in `data`. The table below is not exhaustive. Additional attributes may be appended to the front-matter. -| 属性 | 描述 | -| -------- | ------------------------------------ | +| Data | 描述 | +| -------- | ---------------------------- | | `slug` | 文件名称（必须） | -| `layout` | 布局。默认为 `default_layout` 参数。 | +| `layout` | 布局。 默认为 `default_layout` 参数。 | ## 渲染 @@ -47,16 +47,16 @@ hexo.post.publish(data, replace); hexo.post.render(source, data); ``` -| 参数 | 描述 | -| -------- | ------------------------ | +| Argument | 描述 | +| -------- | ------------ | | `source` | 文件的完整路径（可忽略） | -| `data` | 数据 | +| `data` | 数据 | -数据中必须包含 `content` 属性，如果没有的话，Hexo 会尝试读取原始文件。此函数的执行顺序为： +The data must contain the `content` attribute. If not, Hexo will try to read the original file. 此函数的执行顺序为： - 执行 `before_post_render` 过滤器 - 使用 Markdown 或其他渲染器渲染（根据扩展名而定） -- 使用 [Nunjucks] 渲染 +- 使用 [Nunjucks][] 渲染 - 执行 `after_post_render` 过滤器 [Nunjucks]: https://mozilla.github.io/nunjucks/ diff --git a/source/zh-cn/api/processor.md b/source/zh-cn/api/processor.md index ca368e7e43..de5a26ffc5 100644 --- a/source/zh-cn/api/processor.md +++ b/source/zh-cn/api/processor.md @@ -8,6 +8,7 @@ title: 处理器（Processor） ```js hexo.extend.processor.register(rule, function (file) {}); +}); ``` 完整说明请参考 [Box](box.html)。 diff --git a/source/zh-cn/api/renderer.md b/source/zh-cn/api/renderer.md index ee824fd7bd..91acae0f83 100644 --- a/source/zh-cn/api/renderer.md +++ b/source/zh-cn/api/renderer.md @@ -1,8 +1,8 @@ --- -title: 渲染引擎（Renderer） +title: Renderer --- -渲染引擎用于渲染内容。 +A renderer is used to render content. ## 概要 @@ -14,22 +14,25 @@ hexo.extend.renderer.register( // ... }, sync, +); + }, + sync, ); ``` -| 参数 | 描述 | -| -------- | ------------------------------------ | +| Argument | 描述 | +| -------- | -------------------- | | `name` | 输入的扩展名（小写，不含开头的 `.`） | | `output` | 输出的扩展名（小写，不含开头的 `.`） | -| `sync` | 同步模式 | +| `sync` | 同步模式 | 渲染函数中会传入三个参数： -| 参数 | 描述 | -| ---------- | -------------------------------------------------------------------- | -| `data` | 包含两个属性：文件路径 `path` 和文件内容 `text`。`path` 不一定存在。 | -| `option` | 选项 | -| `callback` | 包含两个参数 `err`, `value` 的回调函数 | +| Argument | 描述 | +| ---------- | ---------------------------------------------- | +| `data` | 包含两个属性：文件路径 `path` 和文件内容 `text`。 `path` 不一定存在。 | +| `option` | 选项 | +| `callback` | 包含两个参数 `err`, `value` 的回调函数 | ## 示例 diff --git a/source/zh-cn/api/rendering.md b/source/zh-cn/api/rendering.md index 431d12676c..0e12115889 100644 --- a/source/zh-cn/api/rendering.md +++ b/source/zh-cn/api/rendering.md @@ -2,7 +2,7 @@ title: 渲染 --- -在 Hexo 中，有两个方法可用于渲染文件或字符串，分别是异步的 `hexo.render.render` 和同步的 `hexo.render.renderSync`，这两个方法的使用方式十分类似，因此下文仅以异步的 `hexo.render.render` 为例。 +在 Hexo 中，有两个方法可用于渲染文件或字符串，分别是异步的 `hexo.render.render` 和同步的 `hexo.render.renderSync`，这两个方法的使用方式十分类似，因此下文仅以异步的 `hexo.render.render` 为例。 Unsurprisingly, the two methods are very similar so only the asynchronous `hexo.render.render` will be further discussed in the below paragraphs. ## 渲染字符串 @@ -12,31 +12,34 @@ title: 渲染 hexo.render.render({ text: "example", engine: "swig" }).then(function (result) { // ... }); +}); ``` ## 渲染文件 -在渲染文件时，您无须指定 `engine`，Hexo 会自动根据扩展名猜测所要使用的渲染引擎，当然您也可以使用 `engine` 指定。 +在渲染文件时，您无须指定 `engine`，Hexo 会自动根据扩展名猜测所要使用的渲染引擎，当然您也可以使用 `engine` 指定。 Of course, you are also allowed to explicitly define the `engine`. ```js hexo.render.render({ path: "path/to/file.swig" }).then(function (result) { // ... }); +}); ``` ## 渲染选项 -在渲染时，您可以向第二个参数中传入参数。 +You can pass in an options object as the second argument. ```js hexo.render.render({ text: "" }, { foo: "foo" }).then(function (result) { // ... }); +}); ``` ## after_render 过滤器 -在渲染完成后，Hexo 会自动执行相对应的 `after_render` 过滤器，举例来说，我们可以通过这个功能实现 JavaScript 的压缩。 +在渲染完成后，Hexo 会自动执行相对应的 `after_render` 过滤器，举例来说，我们可以通过这个功能实现 JavaScript 的压缩。 For example, we can use this feature to implement a JavaScript minifier. ```js var UglifyJS = require("uglify-js"); @@ -49,7 +52,7 @@ hexo.extend.filter.register("after_render:js", function (str, data) { ## 检查文件是否可被渲染 -您可以通过 `isRenderable` 或 `isRenderableSync` 两个方法检查文件路径是否可以被渲染，只有在相对应的渲染器（renderer）已注册的情况下才会返回 true。 +您可以通过 `isRenderable` 或 `isRenderableSync` 两个方法检查文件路径是否可以被渲染，只有在相对应的渲染器（renderer）已注册的情况下才会返回 true。 Only when a corresponding renderer has been registered will this method return true. ```js hexo.render.isRenderable("layout.swig"); // true @@ -58,7 +61,7 @@ hexo.render.isRenderable("image.png"); // false ## 获取文件的输出扩展名 -您可以通过 `getOutput` 方法取得文件路径输出后的扩展名，如果文件无法渲染，则会返回空字符串。 +Use the `getOutput` method to get the extension of the rendered output. If a file is not renderable, the method will return an empty string. ```js hexo.render.getOutput("layout.swig"); // html diff --git a/source/zh-cn/api/router.md b/source/zh-cn/api/router.md index 00e3efdaeb..d33f1cd1ed 100644 --- a/source/zh-cn/api/router.md +++ b/source/zh-cn/api/router.md @@ -6,7 +6,7 @@ title: 路由 ## 获取路径 -`get` 方法会传回一个 [Stream]，例如把该路径的数据存储到某个指定位置。 +`get` 方法会传回一个 [Stream][]，例如把该路径的数据存储到某个指定位置。 For example, to save the path data to a specified destination: ```js var data = hexo.route.get("index.html"); @@ -17,7 +17,7 @@ data.pipe(dest); ## 设置路径 -您可以在 `set` 方法中使用字符串、[Buffer] 或函数，如下： +您可以在 `set` 方法中使用字符串、[Buffer][] 或函数，如下： ```js // String @@ -39,7 +39,7 @@ hexo.route.set("index.html", function (callback) { }); ``` -您还可以设置该路径是否更新，这样在生成文件时便能忽略未更动的文件，加快生成时间。 +You can also set a boolean for whether a path has been modified or not. This can speed up file generation as it allows for ignoring the unmodified files. ```js hexo.route.set("index.html", { @@ -56,7 +56,7 @@ hexo.route.set("index.html", { hexo.route.remove("index.html"); ``` -## 获得路由表 +## Get the List of Routes ```js hexo.route.list(); diff --git a/source/zh-cn/api/scaffolds.md b/source/zh-cn/api/scaffolds.md index 8ae40a5ccc..d49bcb5da0 100644 --- a/source/zh-cn/api/scaffolds.md +++ b/source/zh-cn/api/scaffolds.md @@ -1,5 +1,5 @@ --- -title: 脚手架（Scaffold） +title: Scaffolds --- ## 获得脚手架 diff --git a/source/zh-cn/api/tag.md b/source/zh-cn/api/tag.md index 2633223838..45067e6495 100644 --- a/source/zh-cn/api/tag.md +++ b/source/zh-cn/api/tag.md @@ -8,11 +8,14 @@ title: 标签插件（Tag） ```js hexo.extend.tag.register(name, function (args, content) {}, options); + }, + options, +); ``` -标签函数会传入两个参数：`args` 和 `content`，前者代表开发者在使用标签插件时传入的参数，而后者则是标签插件所覆盖的内容。 +标签函数会传入两个参数：`args` 和 `content`，前者代表开发者在使用标签插件时传入的参数，而后者则是标签插件所覆盖的内容。 `args` contains the arguments passed into the tag plugin and `content` is the wrapped content from the tag plugin. -从 Hexo 3 开始，因为新增了异步渲染功能，而改用 [Nunjucks] 作为渲染引擎，其行为可能会与过去使用的 [Swig] 有些许差异。 +从 Hexo 3 开始，因为新增了异步渲染功能，而改用 [Nunjucks][] 作为渲染引擎，其行为可能会与过去使用的 [Swig][] 有些许差异。 The behavior may be somewhat different from that in [Swig][]. ## 移除标签插件 @@ -40,11 +43,11 @@ hexo.extend.tag.register("youtube", tagFn); ### ends -使用结束标签，此选项默认为 `false`。 +Use end tags. 使用结束标签，此选项默认为 `false`。 ### async -开启异步模式，此选项默认为 `false`。 +Enable async mode. This option is `false` by default. ## 示例 @@ -84,7 +87,7 @@ hexo.extend.tag.register( ); ``` -### 异步渲染 +### Async Rendering 插入文件。 @@ -133,6 +136,16 @@ hexo.extend.tag.register('foo', function (args) { return 'foo'; }); + + // Front-matter + const { title } = this; // article's (post/page) title + + // Article's content + const { _content } = this; // original content + const { content } = this; // HTML-rendered content + + return 'foo'; +}); ``` 2. @@ -157,6 +170,12 @@ module.exports = hexo => { return 'foo'; }; }; + + const { title, _content, content } = this; + + return 'foo'; + }; +}; ``` [Nunjucks]: https://mozilla.github.io/nunjucks/ diff --git a/source/zh-cn/api/themes.md b/source/zh-cn/api/themes.md index 1c0b1c7cad..f40b89a2ac 100644 --- a/source/zh-cn/api/themes.md +++ b/source/zh-cn/api/themes.md @@ -4,27 +4,27 @@ title: 主题 `hexo.theme` 除了继承 [Box](box.html) 外，还具有存储模板的功能。 -## 获取模板 +## Get a View ```js hexo.theme.getView(path); ``` -## 设置模板 +## Set a View ```js hexo.theme.setView(path, data); ``` -## 移除模板 +## Remove a View ```js hexo.theme.removeView(path); ``` -## 模板 +## View -模板本身有两个方法可供使用：`render` 和 `renderSync`。两者功能一样，只是前者为异步函数，而后者为同步函数，因此仅以 `render` 演示调用方法。 +模板本身有两个方法可供使用：`render` 和 `renderSync`。 These two methods are identical, but the former is asynchronous and the latter is synchronous. So for the sake of simplicity, we will only discuss `render` here. ```js var view = hexo.theme.getView("layout.swig"); @@ -32,6 +32,7 @@ var view = hexo.theme.getView("layout.swig"); view.render({ foo: 1, bar: 2 }).then(function (result) { // ... }); +}); ``` -您可以以向 `render` 方法传入对象作为参数，`render` 方法会先使用对应的渲染引擎进行解析，并加载 [辅助函数](helper.html)。渲染完成后，会检测布局（layout）是否存在，当 `layout` 设为 `false` 或不存在时，就会直接返回渲染结果。 +您可以以向 `render` 方法传入对象作为参数，`render` 方法会先使用对应的渲染引擎进行解析，并加载 [辅助函数](helper.html)。 When rendering is complete, it will try to find whether a layout exists. If `layout` is `false` or if it doesn't exist, the result will be returned directly. diff --git a/source/zh-cn/docs/asset-folders.md b/source/zh-cn/docs/asset-folders.md index 7855988b1f..81c1638824 100644 --- a/source/zh-cn/docs/asset-folders.md +++ b/source/zh-cn/docs/asset-folders.md @@ -4,21 +4,23 @@ title: 资源文件夹 ## 全局资源文件夹 -资源（Asset）代表 `source` 文件夹中除了文章以外的所有文件，例如图片、CSS、JS 文件等。比方说，如果你的Hexo项目中只有少量图片，那最简单的方法就是将它们放在 `source/images` 文件夹中。然后通过类似于 `![](/images/image.jpg)` 的方法访问它们。 +资源（Asset）代表 `source` 文件夹中除了文章以外的所有文件，例如图片、CSS、JS 文件等。 比方说，如果你的Hexo项目中只有少量图片，那最简单的方法就是将它们放在 `source/images` 文件夹中。 然后通过类似于 `![](/images/image.jpg)` 的方法访问它们。 ## 文章资源文件夹 -对于那些想要更有规律地提供图片和其他资源以及想要将他们的资源分布在各个文章上的人来说，Hexo也提供了更组织化的方式来管理资源。这个稍微有些复杂但是管理资源非常方便的功能可以通过将 `config.yml` 文件中的 `post_asset_folder` 选项设为 `true` 来打开。 +{% youtube feIDVQ2tz0o %} + +对于那些想要更有规律地提供图片和其他资源以及想要将他们的资源分布在各个文章上的人来说，Hexo也提供了更组织化的方式来管理资源。 这个稍微有些复杂但是管理资源非常方便的功能可以通过将 `config.yml` 文件中的 `post_asset_folder` 选项设为 `true` 来打开。 ```yaml _config.yml post_asset_folder: true ``` -当资源文件管理功能打开后，Hexo将会在你每一次通过 `hexo new [layout] <title>` 命令创建新文章时自动创建一个文件夹。这个资源文件夹将会有与这个文章文件一样的名字。将所有与你的文章有关的资源放在这个关联文件夹中之后，你可以通过相对路径来引用它们，这样你就得到了一个更简单而且方便得多的工作流。 +当资源文件管理功能打开后，Hexo将会在你每一次通过 `hexo new [layout] <title>` 命令创建新文章时自动创建一个文件夹。 这个资源文件夹将会有与这个文章文件一样的名字。 将所有与你的文章有关的资源放在这个关联文件夹中之后，你可以通过相对路径来引用它们，这样你就得到了一个更简单而且方便得多的工作流。 ## 相对路径引用的标签插件 -通过常规的 markdown 语法和相对路径来引用图片和其它资源可能会导致它们在存档页或者主页上显示不正确。在Hexo 2时代，社区创建了很多插件来解决这个问题。但是，随着Hexo 3 的发布，许多新的[标签插件](/zh-cn/docs/tag-plugins#引用资源)被加入到了核心代码中。这使得你可以更简单地在文章中引用你的资源。 +通过常规的 markdown 语法和相对路径来引用图片和其它资源可能会导致它们在存档页或者主页上显示不正确。 在Hexo 2时代，社区创建了很多插件来解决这个问题。 但是，随着Hexo 3 的发布，许多新的[标签插件](/zh-cn/docs/tag-plugins#引用资源)被加入到了核心代码中。 这使得你可以更简单地在文章中引用你的资源。 ``` {% asset_path slug %} @@ -26,7 +28,7 @@ post_asset_folder: true {% asset_link slug [title] %} ``` -比如说：当你打开文章资源文件夹功能后，你把一个 `example.jpg` 图片放在了你的资源文件夹中，如果通过使用相对路径的常规 markdown 语法 `![](example.jpg)` ，它将 _不会_ 出现在首页上。（但是它会在文章中按你期待的方式工作） +比如说：当你打开文章资源文件夹功能后，你把一个 `example.jpg` 图片放在了你的资源文件夹中，如果通过使用相对路径的常规 markdown 语法 `![](example.jpg)` ，它将 _不会_ 出现在首页上。 正确的引用图片方式是使用下列的标签插件而不是 markdown ： @@ -49,5 +51,4 @@ marked: postAsset: true ``` -启用后，资源图片将会被自动解析为其对应文章的路径。 -例如： `image.jpg` 位置为 `/2020/01/02/foo/image.jpg` ，这表示它是 `/2020/01/02/foo/` 文章的一张资源图片， `![](image.jpg)` 将会被解析为 `<img src="/2020/01/02/foo/image.jpg">` 。 +启用后，资源图片将会被自动解析为其对应文章的路径。 例如： `image.jpg` 位置为 `/2020/01/02/foo/image.jpg` ，这表示它是 `/2020/01/02/foo/` 文章的一张资源图片， `![](image.jpg)` 将会被解析为 `<img src="/2020/01/02/foo/image.jpg">` 。 diff --git a/source/zh-cn/docs/commands.md b/source/zh-cn/docs/commands.md index fb6edb86ee..5267c717a8 100644 --- a/source/zh-cn/docs/commands.md +++ b/source/zh-cn/docs/commands.md @@ -2,20 +2,18 @@ title: 指令 --- -{% youtube mgdXi5npArQ %} - ## init ```bash $ hexo init [folder] ``` -新建一个网站。如果没有设置 `folder` ，Hexo 默认在目前的文件夹建立网站。 +新建一个网站。 如果没有设置 `folder` ，Hexo 默认在目前的文件夹建立网站。 本命令相当于执行了以下几步： 1. Git clone [hexo-starter](https://github.com/hexojs/hexo-starter) 和 [hexo-theme-landscape](https://github.com/hexojs/hexo-theme-landscape) 主题到当前目录或指定目录。 -2. 使用 [Yarn 1](https://classic.yarnpkg.com/lang/en/)、[pnpm](https://pnpm.io/zh/) 或 [npm](https://docs.npmjs.com/cli/install) 包管理器下载依赖（如有已安装多个，则列在前面的优先）。npm 默认随 [Node.js](/zh-cn/docs/index.html#安装-Node-js) 安装。 +2. 使用 [Yarn 1](https://classic.yarnpkg.com/lang/en/)、[pnpm](https://pnpm.io/zh/) 或 [npm](https://docs.npmjs.com/cli/install) 包管理器下载依赖（如有已安装多个，则列在前面的优先）。 npm 默认随 [Node.js](/zh-cn/docs/index.html#安装-Node-js) 安装。 ## new @@ -23,19 +21,15 @@ $ hexo init [folder] $ hexo new [layout] <title> ``` -新建一篇文章。如果没有设置 `layout` 的话，默认使用 [\_config.yml](configuration.html) 中的 `default_layout` 参数代替。如果标题包含空格的话，请使用引号括起来。 - -```bash -$ hexo new "post title with whitespace" -``` +新建一篇文章。 如果没有设置 `layout` 的话，默认使用 [\_config.yml](configuration.html) 中的 `default_layout` 参数代替。 Use the layout `draft` to create a draft. 如果标题包含空格的话，请使用引号括起来。 -| 参数 | 描述 | -| ----------------- | --------------------------------------------- | -| `-p`, `--path` | 自定义新文章的路径 | -| `-r`, `--replace` | 如果存在同名文章，将其替换 | -| `-s`, `--slug` | 文章的 Slug，作为新文章的文件名和发布后的 URL | +| Option | 描述 | +| ----------------- | ----------------------------------------- | +| `-p`, `--path` | Post path. 自定义新文章的路径 | +| `-r`, `--replace` | Replace the current post if existed. | +| `-s`, `--slug` | Post slug. Customize the URL of the post. | -默认情况下，Hexo 会使用文章的标题来决定文章文件的路径。对于独立页面来说，Hexo 会创建一个以标题为名字的目录，并在目录中放置一个 `index.md` 文件。你可以使用 `--path` 参数来覆盖上述行为、自行决定文件的目录： +默认情况下，Hexo 会使用文章的标题来决定文章文件的路径。 对于独立页面来说，Hexo 会创建一个以标题为名字的目录，并在目录中放置一个 `index.md` 文件。 你可以使用 `--path` 参数来覆盖上述行为、自行决定文件的目录： ```bash hexo new page --path about/me "About me" @@ -43,13 +37,13 @@ hexo new page --path about/me "About me" 以上命令会创建一个 `source/about/me.md` 文件，同时 Front Matter 中的 title 为 `"About me"` -注意！title 是必须指定的！如果你这么做并不能达到你的目的： +注意！ title 是必须指定的！ For example, this will not result in the behaviour you might expect: ```bash hexo new page --path about/me ``` -此时 Hexo 会创建 `source/_posts/about/me.md`，同时 `me.md` 的 Front Matter 中的 title 为 `"page"`。这是因为在上述命令中，hexo-cli 将 `page` 视为指定文章的标题、并采用默认的 `layout`。 +此时 Hexo 会创建 `source/_posts/about/me.md`，同时 `me.md` 的 Front Matter 中的 title 为 `"page"`。 这是因为在上述命令中，hexo-cli 将 `page` 视为指定文章的标题、并采用默认的 `layout`。 ## generate @@ -59,19 +53,13 @@ $ hexo generate 生成静态文件。 -| 选项 | 描述 | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-d`, `--deploy` | 文件生成后立即部署网站 | -| `-w`, `--watch` | 监视文件变动 | -| `-b`, `--bail` | 生成过程中如果发生任何未处理的异常则抛出异常 | -| `-f`, `--force` | 强制重新生成文件<br>Hexo 引入了差分机制，如果 `public` 目录存在，那么 `hexo g` 只会重新生成改动的文件。<br>使用该参数的效果接近 `hexo clean && hexo generate` | -| `-c`, `--concurrency` | 最大同时生成文件的数量，默认无限制 | - -该命令可以简写为 - -```bash -$ hexo g -``` +| 选项 | 描述 | +| --------------------- | ------------------------------------- | +| `-d`, `--deploy` | Deploy after generation finishes | +| `-w`, `--watch` | 监视文件变动 | +| `-b`, `--bail` | 生成过程中如果发生任何未处理的异常则抛出异常 | +| `-f`, `--force` | Force regenerate | +| `-c`, `--concurrency` | 最大同时生成文件的数量，默认无限制 Default is infinity | ## publish @@ -87,13 +75,13 @@ $ hexo publish [layout] <filename> $ hexo server ``` -启动服务器。默认情况下，访问网址为： `http://localhost:4000/`。 +启动服务器。 默认情况下，访问网址为： `http://localhost:4000/`。 -| 选项 | 描述 | -| ---------------- | ------------------------------ | -| `-p`, `--port` | 重设端口 | -| `-s`, `--static` | 只使用静态文件 | -| `-l`, `--log` | 启动日记记录，使用覆盖记录格式 | +| 选项 | 描述 | +| ---------------- | -------------------------------------- | +| `-p`, `--port` | 重设端口 | +| `-s`, `--static` | 只使用静态文件 | +| `-l`, `--log` | Enable logger. Override logger format. | ## deploy @@ -101,17 +89,11 @@ $ hexo server $ hexo deploy ``` -部署网站。 - -| 参数 | 描述 | -| ------------------ | ------------------------ | -| `-g`, `--generate` | 部署之前预先生成静态文件 | +Deploys your website. -该命令可以简写为： - -```bash -$ hexo d -``` +| Option | 描述 | +| ------------------ | -------------------------- | +| `-g`, `--generate` | Generate before deployment | ## render @@ -121,9 +103,9 @@ $ hexo render <file1> [file2] ... 渲染文件。 -| 参数 | 描述 | -| ---------------- | ------------ | -| `-o`, `--output` | 设置输出路径 | +| Option | 描述 | +| ---------------- | ------------------ | +| `-o`, `--output` | Output destination | ## migrate @@ -141,15 +123,13 @@ $ hexo clean 清除缓存文件 (`db.json`) 和已生成的静态文件 (`public`)。 -在某些情况（尤其是更换主题后），如果发现您对站点的更改无论如何也不生效，您可能需要运行该命令。 - ## list ```bash $ hexo list <type> ``` -列出网站数据。 +Lists all routes. ## version @@ -157,7 +137,7 @@ $ hexo list <type> $ hexo version ``` -显示 Hexo 版本。 +Displays version information. ## config @@ -165,7 +145,7 @@ $ hexo version $ hexo config [key] [value] ``` -列出网站的配置（`_config.yml`）。如果指定了 `key`，则只展示配置中对应 `key` 的值；如果同时指定了 `key` 和 `value`，则将配置中对应的 `key` 的值修改为 `value`。 +列出网站的配置（`_config.yml`）。 如果指定了 `key`，则只展示配置中对应 `key` 的值；如果同时指定了 `key` 和 `value`，则将配置中对应的 `key` 的值修改为 `value`。 ## 选项 @@ -175,7 +155,7 @@ $ hexo config [key] [value] $ hexo --safe ``` -在安全模式下，不会加载插件和脚本。当您在安装新插件遭遇问题时，可以尝试以安全模式重新执行。 +在安全模式下，不会加载插件和脚本。 当您在安装新插件遭遇问题时，可以尝试以安全模式重新执行。 ### 调试模式 @@ -183,7 +163,7 @@ $ hexo --safe $ hexo --debug ``` -在终端中显示调试信息并记录到 `debug.log`。当您碰到问题时，可以尝试用调试模式重新执行一次，并 [提交调试信息到 GitHub](https://github.com/hexojs/hexo/issues/new?assignees=&labels=&projects=&template=bug_report.yml)。 +在终端中显示调试信息并记录到 `debug.log`。 Try this if you encounter any problems with Hexo. 当您碰到问题时，可以尝试用调试模式重新执行一次，并 [提交调试信息到 GitHub](https://github.com/hexojs/hexo/issues/new?assignees=&labels=&projects=&template=bug_report.yml)。 ### 简洁模式 @@ -191,7 +171,7 @@ $ hexo --debug $ hexo --silent ``` -隐藏终端信息。 +Silences output to the terminal. ### 自定义配置文件的路径 @@ -203,8 +183,7 @@ $ hexo server --config custom.yml $ hexo generate --config custom.yml,custom2.json,custom3.yml ``` -自定义配置文件的路径，指定这个参数后将不再使用默认的 `_config.yml`。 -你可以使用一个 YAML 或 JSON 文件的路径，也可以使用逗号分隔（无空格）的多个 YAML 或 JSON 文件的路径。例如： +自定义配置文件的路径，指定这个参数后将不再使用默认的 `_config.yml`。 Also accepts a comma-separated list (no spaces) of JSON or YAML config files that will combine the files into a single `_multiconfig.yml`. ```bash # 使用 custom.yml 代替默认的 _config.yml @@ -214,8 +193,6 @@ $ hexo server --config custom.yml $ hexo generate --config custom.yml,custom2.json,custom3.yml ``` -当你指定了多个配置文件以后，Hexo 会按顺序将这部分配置文件合并成一个 `_multiconfig.yml`。如果遇到重复的配置，排在后面的文件的配置会覆盖排在前面的文件的配置。这个原则适用于任意数量、任意深度的 YAML 和 JSON 文件。 - ### 显示草稿 ```bash diff --git a/source/zh-cn/docs/configuration.md b/source/zh-cn/docs/configuration.md index e3ca699bfa..9124c3e2c7 100644 --- a/source/zh-cn/docs/configuration.md +++ b/source/zh-cn/docs/configuration.md @@ -4,32 +4,28 @@ title: 配置 您可以在 `_config.yml` 或 [代替配置文件](#使用代替配置文件) 中修改大部分的配置。 -{% youtube A0Enyn70jKU %} - -## 网站 - -| 参数 | 描述 | -| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `title` | 网站标题 | -| `subtitle` | 网站副标题 | -| `description` | 网站描述 | -| `keywords` | 网站的关键词。支持多个关键词。 | -| `author` | 您的名字 | -| `language` | 网站使用的语言。对于简体中文用户来说，使用不同的主题可能需要设置成不同的值，请参考你的主题的文档自行设置，常见的有 `zh-Hans`和 `zh-CN`。 | -| `timezone` | 网站时区。Hexo 默认使用您电脑的时区。请参考 [时区列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 进行设置，如 `America/New_York`, `Japan`, 和 `UTC` 。一般的，对于中国大陆地区可以使用 `Asia/Shanghai`。 | - -其中，`description` 主要用于SEO，告诉搜索引擎一个关于您站点的简单描述，通常建议在其中包含您网站的关键词。`author` 参数用于主题显示文章的作者。 - -## 网址 - -| 参数 | 描述 | 默认值 | -| ---------------------------- | --------------------------------------------------------------------------------------- | --------------------------- | -| `url` | 网址, 必须以 `http://` 或 `https://` 开头 | -| `root` | 网站根目录 | `url's pathname` | -| `permalink` | 文章的 [永久链接](permalinks.html) 格式 | `:year/:month/:day/:title/` | -| `permalink_defaults` | 永久链接中各部分的默认值 | -| `pretty_urls` | 改写 [`permalink`](variables.html) 的值来美化 URL | -| `pretty_urls.trailing_index` | 是否在永久链接中保留尾部的 `index.html`，设置为 `false` 时去除 | `true` | +### 网站 + +| Setting | 描述 | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `title` | 网站标题 | +| `subtitle` | 网站副标题 | +| `description` | 网站描述 | +| `keywords` | 网站的关键词。 支持多个关键词。 | +| `author` | 您的名字 | +| `language` | 网站使用的语言。 Use a [2-letter ISO-639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) or optionally [its variant](/docs/internationalization). Default is `en`. | +| `timezone` | 网站时区。 Hexo 默认使用您电脑的时区。 请参考 [时区列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 进行设置，如 `America/New_York`, `Japan`, 和 `UTC` 。 一般的，对于中国大陆地区可以使用 `Asia/Shanghai`。 | + +### 网址 + +| Setting | 描述 | 默认值 | +| ---------------------------- | -------------------------------------------------------------- | --------------------------- | +| `url` | 网址, 必须以 `http://` 或 `https://` 开头 | | +| `root` | 网站根目录 | `url's pathname` | +| `permalink` | 文章的 [永久链接](permalinks.html) 格式 | `:year/:month/:day/:title/` | +| `permalink_defaults` | 永久链接中各部分的默认值 | | +| `pretty_urls` | 改写 [`permalink`](variables.html) 的值来美化 URL | | +| `pretty_urls.trailing_index` | 是否在永久链接中保留尾部的 `index.html`，设置为 `false` 时去除 | `true` | | `pretty_urls.trailing_html` | 是否在永久链接中保留尾部的 `.html`, 设置为 `false` 时去除 (_对尾部的 `index.html`无效_) | `true` | {% note info 网站存放在子目录 %} @@ -45,18 +41,18 @@ pretty_urls: # 此时页面的永久链接会变为 http://example.com/foo/bar/ ``` -## 目录 +### 目录 -| 参数 | 描述 | 默认值 | -| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | -| `source_dir` | 资源文件夹，这个文件夹用来存放内容。 | `source` | -| `public_dir` | 公共文件夹，这个文件夹用于存放生成的站点文件。 | `public` | -| `tag_dir` | 标签文件夹 | `tags` | -| `archive_dir` | 归档文件夹 | `archives` | -| `category_dir` | 分类文件夹 | `categories` | -| `code_dir` | Include code 文件夹，`source_dir` 下的子目录 | `downloads/code` | -| `i18n_dir` | 国际化（i18n）文件夹 | `:lang` | -| `skip_render` | 跳过指定文件的渲染。匹配到的文件将会被不做改动地复制到 `public` 目录中。您可使用 [glob 表达式](https://github.com/micromatch/micromatch#extended-globbing)来匹配路径。 | +| Setting | 描述 | 默认值 | +| -------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------- | +| `source_dir` | Source folder. Where your content is stored | `source` | +| `public_dir` | Public folder. Where the static site will be generated | `public` | +| `tag_dir` | 标签文件夹 | `tags` | +| `archive_dir` | 归档文件夹 | `archives` | +| `category_dir` | 分类文件夹 | `categories` | +| `code_dir` | Include code 文件夹，`source_dir` 下的子目录 | `downloads/code` | +| `i18n_dir` | 国际化（i18n）文件夹 | `:lang` | +| `skip_render` | 匹配到的文件将会被不做改动地复制到 `public` 目录中。 您可使用 [glob 表达式](https://github.com/micromatch/micromatch#extended-globbing)来匹配路径。 | | 例如： @@ -66,70 +62,84 @@ skip_render: "mypage/**/*" # 你也可以用这种方法来跳过对指定文章文件的渲染 skip_render: "_posts/test-post.md" # 这将会忽略对 'test-post.md' 的渲染 -``` -{% note info 提示 %} -如果您刚刚开始接触 Hexo，通常没有必要修改这一部分的值。 -{% endnote %} +## This also can be used to exclude posts, +skip_render: "_posts/test-post.md" +# will ignore the `source/_posts/test-post.md`. +``` -## 文章 - -| 参数 | 描述 | 默认值 | -| ----------------------- | --------------------------------------------------------------------------------------- | -------------- | -| `new_post_name` | 新文章的文件名称 | `:title.md` | -| `default_layout` | 预设布局 | `post` | -| `titlecase` | 把标题转换为 title case | `false` | -| `external_link` | 在新标签中打开链接 | `true` | -| `external_link.enable` | 在新标签中打开链接 | `true` | -| `external_link.field` | 对整个网站（`site`）生效或仅对文章（`post`）生效 | `site` | -| `external_link.exclude` | 需要排除的域名。主域名和子域名如 `www` 需分别配置 | `[]` | -| `filename_case` | 把文件名称转换为 (1) 小写或 (2) 大写 | `0` | -| `render_drafts` | 显示草稿 | `false` | -| `post_asset_folder` | 启用 [资源文件夹](asset-folders.html) | `false` | -| `relative_link` | 把链接改为与根目录的相对位址 | `false` | -| `future` | 显示未来的文章 | `true` | -| `syntax_highlighter` | 代码块的设置, 请参考 [代码高亮](/zh-cn/docs/syntax-highlight) 进行设置 | `highlight.js` | -| `highlight` | 代码块的设置, 请参考 [Highlight.js](/zh-cn/docs/syntax-highlight#Highlight-js) 进行设置 | -| `prismjs` | 代码块的设置, 请参考 [PrismJS](/zh-cn/docs/syntax-highlight#PrismJS) 进行设置 | - -{% note info 相对地址 %} -默认情况下，Hexo 生成的超链接都是绝对地址。例如，如果您的网站域名为 `example.com`，您有一篇文章名为 `hello`，那么绝对链接可能像这样：`http://example.com/hello.html`，它是**绝对**于域名的。相对链接像这样：`/hello.html`，也就是说，无论用什么域名访问该站点，都没有关系，这在进行反向代理时可能用到。通常情况下，建议使用绝对地址。 -{% endnote %} +### 文章 + +| Setting | 描述 | 默认值 | +| ----------------------- | -------------------------------------------------------------------------- | -------------- | +| `new_post_name` | 新文章的文件名称 | `:title.md` | +| `default_layout` | 预设布局 | `post` | +| `titlecase` | 把标题转换为 title case | `false` | +| `external_link` | 在新标签中打开链接 | | +| `external_link.enable` | 在新标签中打开链接 | `true` | +| `external_link.field` | 对整个网站（`site`）生效或仅对文章（`post`）生效 | `site` | +| `external_link.exclude` | 需要排除的域名。 主域名和子域名如 `www` 需分别配置 | `[]` | +| `filename_case` | Transform filenames to `1` lower case; `2` upper case | `0` | +| `render_drafts` | 显示草稿 | `false` | +| `post_asset_folder` | 启用 [资源文件夹](asset-folders.html) | `false` | +| `relative_link` | 把链接改为与根目录的相对位址 | `false` | +| `future` | 显示未来的文章 | `true` | +| `syntax_highlighter` | 代码块的设置, 请参考 [代码高亮](/zh-cn/docs/syntax-highlight) 进行设置 | `highlight.js` | +| `highlight` | 代码块的设置, 请参考 [Highlight.js](/zh-cn/docs/syntax-highlight#Highlight-js) 进行设置 | | +| `prismjs` | 代码块的设置, 请参考 [PrismJS](/zh-cn/docs/syntax-highlight#PrismJS) 进行设置 | | + +### Home page setting + +| Setting | 描述 | 默认值 | +| -------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------- | +| `index_generator` | Generate an archive of posts, powered by [hexo-generator-index](https://github.com/hexojs/hexo-generator-index) | | +| `index_generator.path` | Root path for your blog's index page | `''` | +| `index_generator.per_page` | Posts displayed per page. | `10` | +| `index_generator.order_by` | Posts order. Order by descending date (new to old) by default. | `-date` | +| `index_generator.pagination_dir` | URL format, see [Pagination](#Pagination) setting below | `page` | + +### 分类 & 标签 + +| Setting | 描述 | 默认值 | +| ------------------ | ---- | --------------- | +| `default_category` | 默认分类 | `uncategorized` | +| `category_map` | 分类别名 | | +| `tag_map` | 标签别名 | | -## 分类 & 标签 +例如： -| 参数 | 描述 | 默认值 | -| ------------------ | -------- | --------------- | -| `default_category` | 默认分类 | `uncategorized` | -| `category_map` | 分类别名 | -| `tag_map` | 标签别名 | +```yaml +category_map: + "yesterday's thoughts": yesterdays-thoughts + "C++": c-plus-plus +``` -## 日期 / 时间格式 +### 日期 / 时间格式 Hexo 使用 [Moment.js](http://momentjs.com/) 来解析和显示时间。 -| 参数 | 描述 | 默认值 | -| ---------------- | ------------------------------------------------------------------------------------------ | ------------ | -| `date_format` | 日期格式 | `YYYY-MM-DD` | -| `time_format` | 时间格式 | `HH:mm:ss` | +| Setting | 描述 | 默认值 | +| ---------------- | ---------------------------------------------------------------------------- | ------------ | +| `date_format` | 日期格式 | `YYYY-MM-DD` | +| `time_format` | 时间格式 | `HH:mm:ss` | | `updated_option` | 当 Front Matter 中没有指定 [`updated`](/zh-cn/docs/variables#页面变量) 时 `updated` 的取值 | `mtime` | {% note info updated_option %} `updated_option` 控制了当 Front Matter 中没有指定 `updated` 时，`updated` 如何取值： -- `mtime`: 使用文件的最后修改时间。这是从 Hexo 3.0.0 开始的默认行为。 -- `date`: 使用 `date` 作为 `updated` 的值。可被用于 Git 工作流之中，因为使用 Git 管理站点时，文件的最后修改日期常常会发生改变 -- `empty`: 直接删除 `updated`。使用这一选项可能会导致大部分主题和插件无法正常工作。 +- `mtime`: 使用文件的最后修改时间。 这是从 Hexo 3.0.0 开始的默认行为。 +- `date`: 使用 `date` 作为 `updated` 的值。 可被用于 Git 工作流之中，因为使用 Git 管理站点时，文件的最后修改日期常常会发生改变 +- `empty`: 直接删除 `updated`。 使用这一选项可能会导致大部分主题和插件无法正常工作。 -`use_date_for_updated` 选项已经在 v7.0.0+ 中被移除。请改为使用 `updated_option: 'date'`。 +`use_date_for_updated` 选项已经在 v7.0.0+ 中被移除。 请改为使用 `updated_option: 'date'`。 {% endnote %} -## 分页 +### 分页 -| 参数 | 描述 | 默认值 | -| ---------------- | ----------------------------------- | ------ | -| `per_page` | 每页显示的文章量 (0 = 关闭分页功能) | `10` | -| `pagination_dir` | 分页目录 | `page` | +| Setting | 描述 | 参数 | +| ---------------- | --------------------------------------------------------------- | ------ | +| `per_page` | Number of posts displayed on each page. `0` disables pagination | `10` | +| `pagination_dir` | URL format | `page` | 例如： @@ -141,28 +151,28 @@ pagination_dir: 'awesome-page' # http://example.com/awesome-page/2 ``` -## 扩展 +### 扩展 -| 参数 | 描述 | -| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `theme` | 当前主题名称。值为`false`时禁用主题 | -| `theme_config` | 主题的配置文件。在这里放置的配置会覆盖主题目录下的 `_config.yml` 中的配置 | -| `deploy` | 部署部分的设置 | +| Setting | 描述 | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `theme` | 当前主题名称。 值为`false`时禁用主题 | +| `theme_config` | 主题的配置文件。 在这里放置的配置会覆盖主题目录下的 `_config.yml` 中的配置 | +| `deploy` | 部署部分的设置 | | `meta_generator` | [Meta generator](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/meta#%E5%B1%9E%E6%80%A7) 标签。 值为 `false` 时 Hexo 不会在头部插入该标签 | ### 包括或不包括目录和文件 -在 Hexo 配置文件中，通过设置 include/exclude 可以让 Hexo 进行处理或忽略某些目录和文件夹。你可以使用 [glob 表达式](https://github.com/isaacs/minimatch) 对目录和文件进行匹配。 +Use the following options to explicitly process or ignore certain files/folders. Support [glob expressions](https://github.com/micromatch/micromatch#extended-globbing) for path matching. `include` 和 `exclude` 选项只会应用到 `source/` ，而 `ignore` 选项会应用到所有文件夹. -| 参数 | 描述 | -| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `include` | Hexo 默认会不包括 `source/` 下的文件和文件夹（包括名称以下划线和 `.` 开头的文件和文件夹，Hexo 的 `_posts` 和 `_data` 等目录除外）。通过设置此字段将使 Hexo 处理他们并将它们复制到 `source` 目录下。 | -| `exclude` | Hexo 不包括 `source/` 下的这些文件和目录 | -| `ignore` | Hexo 会忽略整个 Hexo 项目下的这些文件夹或文件 | +| Setting | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------- | +| `include` | Include hidden files (including files/folders with a name that starts with an underscore, with an exception\*) | +| `exclude` | 资源文件夹，这个文件夹用来存放内容。 | +| `ignore` | Ignore files/folders | -例如： +例如，使用 `--config` 指定了两个自定义配置文件： ```yaml # 处理或不处理目录或文件 @@ -171,6 +181,10 @@ include: # 处理 'source/css/_typing.css' - "css/_typing.css" # 处理 'source/_css/' 中的任何文件，但不包括子目录及其其中的文件。 + - "css/_typing.css" + # Include any file in 'source/_css/'. + - "_css/*" + # Include any file and subfolder in 'source/_css/'. - "_css/*" # 处理 'source/_css/' 中的任何文件和子目录下的任何文件 - "_css/**/*" @@ -186,44 +200,50 @@ exclude: - "js/test*" # 不处理 'source/js/' 及其子目录中任何以 'test' 开头的文件 - "js/**/test*" - # 不要用 exclude 来忽略 'source/_posts/' 中的文件。你应该使用 'skip_render'，或者在要忽略的文件的文件名之前加一个下划线 '_' - # 在这里配置一个 - "_posts/hello-world.md" 是没有用的。 + # 不要用 exclude 来忽略 'source/_posts/' 中的文件。 + - "js/test.js" + # Exclude any file in 'source/js/'. + - "js/*" + # Exclude any file and subfolder in 'source/js/'. + - "js/**/*" + # Exclude any file with filename that starts with 'test' in 'source/js/'. + - "js/test*" + # Exclude any file with filename that starts with 'test' in 'source/js/' and its subfolders. + - "js/**/test*" + # Do not use this to exclude posts in the 'source/_posts/'. + # Use skip_render for that. Or prepend an underscore to the filename. + # - "_posts/hello-world.md" # Does not work. ignore: + # Ignore any folder named 'foo'. + ignore: # 忽略任何一个名叫 'foo' 的文件夹 - "**/foo" # 只忽略 'themes/' 下的 'foo' 文件夹 - "**/themes/*/foo" # 对 'themes/' 目录下的每个文件夹中忽略名叫 'foo' 的子文件夹 - "**/themes/**/foo" + - "**/themes/*/foo" + # Same as above, but applies to every subfolders of 'themes/'. + - "**/themes/**/foo" ``` 列表中的每一项都必须用单引号或双引号包裹起来。 -`include` 和 `exclude` 并不适用于 `themes/` 目录下的文件。如果需要忽略 `themes/` 目录下的部分文件或文件夹，可以使用 `ignore` 或在文件名之前添加下划线 `_`。 +`include` 和 `exclude` 并不适用于 `themes/` 目录下的文件。 如果需要忽略 `themes/` 目录下的部分文件或文件夹，可以使用 `ignore` 或在文件名之前添加下划线 `_`。 -- `source/_posts` 文件夹是一个例外，但该文件夹下任何名称以 `_` 开头的文件或文件夹仍会被忽略。不建议在该文件夹中使用 `include` 规则。 +`source/_posts` 文件夹是一个例外，但该文件夹下任何名称以 `_` 开头的文件或文件夹仍会被忽略。 不建议在该文件夹中使用 `include` 规则。 ### 使用代替配置文件 -可以在 hexo-cli 中使用 `--config` 参数来指定自定义配置文件的路径。你可以使用一个 YAML 或 JSON 文件的路径，也可以使用逗号分隔（无空格）的多个 YAML 或 JSON 文件的路径。例如： +可以在 hexo-cli 中使用 `--config` 参数来指定自定义配置文件的路径。 你可以使用一个 YAML 或 JSON 文件的路径，也可以使用逗号分隔（无空格）的多个 YAML 或 JSON 文件的路径。 ```bash -# 用 'custom.yml' 代替 '_config.yml' -$ hexo server --config custom.yml - -# 使用 'custom.yml' 和 'custom2.json'，优先使用 'custom3.yml'，然后是 'custom2.json' -$ hexo generate --config custom.yml,custom2.json,custom3.yml -``` - -当你指定了多个配置文件以后，Hexo 会按顺序将这部分配置文件合并成一个 `_multiconfig.yml`。如果遇到重复的配置，排在后面的文件的配置会覆盖排在前面的文件的配置。这个原则适用于任意数量、任意深度的 YAML 和 JSON 文件。 - -例如，使用 `--config` 指定了两个自定义配置文件： - -``` $ hexo generate --config custom.yml,custom2.json ``` +当你指定了多个配置文件以后，Hexo 会按顺序将这部分配置文件合并成一个 `_multiconfig.yml`。 The later values take precedence. 这个原则适用于任意数量、任意深度的 YAML 和 JSON 文件。 Note that **no spaces are allowed in the list**. + 如果 `custom.yml` 中指定了 `foo: bar`，在 custom2.json 中指定了 `"foo": "dinosaur"`，那么在 `_multiconfig.yml` 中你会得到 `foo: dinosaur`。 ### 使用代替主题配置文件 @@ -270,7 +290,7 @@ logo: "a-cool-image.png" > 该特性自 Hexo 5.0.0 起提供 -独立的主题配置文件应放置于站点根目录下，支持 `yml` 或 `json` 格式。需要配置站点 `_config.yml` 文件中的 `theme` 以供 Hexo 寻找 `_config.[theme].yml` 文件。 +独立的主题配置文件应放置于站点根目录下，支持 `yml` 或 `json` 格式。 需要配置站点 `_config.yml` 文件中的 `theme` 以供 Hexo 寻找 `_config.[theme].yml` 文件。 ```yml # _config.yml @@ -306,5 +326,5 @@ logo: "a-cool-image.png" ``` {% note %} -我们强烈建议你将所有的主题配置集中在一处。如果你不得不在多处配置你的主题，那么这些信息对你将会非常有用：Hexo 在合并主题配置时，Hexo 配置文件中的 `theme_config` 的优先级最高，其次是 `_config.[theme].yml` 文件，最后是位于主题目录下的 `_config.yml` 文件。 +我们强烈建议你将所有的主题配置集中在一处。 如果你不得不在多处配置你的主题，那么这些信息对你将会非常有用：Hexo 在合并主题配置时，Hexo 配置文件中的 `theme_config` 的优先级最高，其次是 `_config.[theme].yml` 文件，最后是位于主题目录下的 `_config.yml` 文件。 The `_config.yml` file under the theme directory has the lowest priority. {% endnote %} diff --git a/source/zh-cn/docs/contributing.md b/source/zh-cn/docs/contributing.md index 63cad406a6..fbc931051c 100644 --- a/source/zh-cn/docs/contributing.md +++ b/source/zh-cn/docs/contributing.md @@ -6,7 +6,7 @@ title: 贡献 ## 开发 -我们非常欢迎您加入 Hexo 的开发，这份文件将帮助您了解开发流程。 +我们非常欢迎您加入 Hexo 的开发，这份文件将帮助您了解开发流程。 This document will help you through the process. ### 开始之前 @@ -22,7 +22,7 @@ title: 贡献 ### 工作流 -1. Fork [hexojs/hexo] +1. Fork [hexojs/hexo][] 2. 把库（repository）复制到电脑上，并安装所依赖的插件。 ```bash @@ -32,14 +32,14 @@ $ npm install $ git submodule update --init ``` -3. 新增一个功能分支。 +3. Create a feature branch. ```bash $ git checkout -b new_feature ``` -4. 开始开发。 -5. 推送（push）分支。 +4. Start hacking. +5. Push the branch: ``` $ git push origin new_feature @@ -50,23 +50,23 @@ $ git push origin new_feature ### 注意事项 - 不要修改 `package.json` 的版本号。 -- 只有在测试通过的情况下您的合并申请才会被批准，在提交前别忘了进行测试。 +- 只有在测试通过的情况下您的合并申请才会被批准，在提交前别忘了进行测试。 Don't forget to run tests before submission. ```bash $ npm test ``` -## 更新 Hexo 官方插件 +## Updating official-plugins -我们也欢迎给 [Hexo 官方插件](https://github.com/hexojs) 提交 PR 和 Issue 🤗 +我们也欢迎给 [Hexo 官方插件](https://github.com/hexojs) 提交 PR 和 Issue 🤗 🤗 ## 更新文档 -Hexo 文档开放源代码，您可以在 [hexojs/site] 找到源代码。 +Hexo 文档开放源代码，您可以在 [hexojs/site][] 找到源代码。 ### 工作流 -1. Fork [hexojs/site] +1. Fork [hexojs/site][] 2. 把库（repository）复制到电脑上，并安装所依赖的插件。 ```bash @@ -76,7 +76,7 @@ $ cd site $ npm install ``` -3. 开始编辑文件，您可以通过服务器预览变动。 +3. Start editing the documentation. 开始编辑文件，您可以通过服务器预览变动。 ```bash $ hexo server @@ -87,14 +87,14 @@ $ hexo server ### 翻译 -1. 在 `source` 文件夹中建立一个新的语言文件夹（全小写）。 +1. 在 `source` 文件夹中建立一个新的语言文件夹（全小写）。 (All lower case) 2. 把 `source` 文件夹中相关的文件（Markdown 和模板文件）复制到新的语言文件夹中。 3. 在 `source/_data/language.yml` 中新增语言。 4. 将 `en.yml` 复制到 `themes/navy/languages`中并命名为语言名称（全小写）。 -## 反馈问题 +## Reporting Issues -当您在使用 Hexo 时遇到问题，您可以尝试在 [问题解答](troubleshooting.html) 中寻找解答，或是在 [GitHub](https://github.com/hexojs/hexo/issues) 或 [Google Group](https://groups.google.com/group/hexo) 上提问。如果你没有找答案，请在 Github 报告它。 +当您在使用 Hexo 时遇到问题，您可以尝试在 [问题解答](troubleshooting.html) 中寻找解答，或是在 [GitHub](https://github.com/hexojs/hexo/issues) 或 [Google Group](https://groups.google.com/group/hexo) 上提问。 如果你没有找答案，请在 Github 报告它。 1. 在 [调试模式](commands.html#调试模式) 中重现问题。 2. 在 GitHub 上提交 Issue 时，请遵循 Issue 模板中的步骤提供调试消息和版本信息。 diff --git a/source/zh-cn/docs/data-files.md b/source/zh-cn/docs/data-files.md index ebe1f2366f..f4cea4c5bb 100644 --- a/source/zh-cn/docs/data-files.md +++ b/source/zh-cn/docs/data-files.md @@ -2,7 +2,9 @@ title: 数据文件 --- -有时您可能需要在主题中使用某些数据，而这些数据并不在文章内，并且是需要重复使用的，那么您可以考虑使用 Hexo 3.0 新增的「数据文件」功能。此功能会加载 `source/_data` 内的 YAML 或 JSON 文件，如此一来您便能在网站中复用这些文件了。 +Sometimes you may need to use some data in templates which is not directly available in your posts, or you want to reuse the data elsewhere. For such use cases, Hexo 3 introduced the new **Data files**. 此功能会加载 `source/_data` 内的 YAML 或 JSON 文件，如此一来您便能在网站中复用这些文件了。 + +{% youtube CN31plHbI-w %} 举例来说，在 `source/_data` 文件夹中新建 `menu.yml` 文件： @@ -20,7 +22,7 @@ Archives: /archives/ <% } %> ``` -渲染结果如下 : +render like this : ``` <a href="/"> Home </a> diff --git a/source/zh-cn/docs/front-matter.md b/source/zh-cn/docs/front-matter.md index 4dce38b5cb..f1ad39e37a 100644 --- a/source/zh-cn/docs/front-matter.md +++ b/source/zh-cn/docs/front-matter.md @@ -4,7 +4,9 @@ title: Front-matter {% youtube Rl48Yk4A_V8 %} -Front-matter 是文件最上方以 `---` 分隔的区域，用于指定个别文件的变量，举例来说： +Front-matter is a block of YAML or JSON at the beginning of the file that is used to configure settings for your writings. Front-matter is terminated by three dashes when written in YAML or three semicolons when written in JSON. + +**YAML** ```yaml --- @@ -13,32 +15,42 @@ date: 2013/7/13 20:46:25 --- ``` -以下是预先定义的参数，您可在模板中使用这些参数值并加以利用。 +**JSON Front-matter** + +```json +"title": "Hello World", +"date": "2013/7/13 20:46:25" +;;; +``` + +### Settings & Their Default Values -| 参数 | 描述 | 默认值 | -| ----------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | -| `layout` | 布局 | [`config.default_layout`](/zh-cn/docs/configuration#文章) | -| `title` | 标题 | 文章的文件名 | -| `date` | 建立日期 | 文件建立日期 | -| `updated` | 更新日期 | 文件更新日期 | -| `comments` | 开启文章的评论功能 | `true` | -| `tags` | 标签（不适用于分页） | -| `categories` | 分类（不适用于分页） | -| `permalink` | 覆盖文章的永久链接，永久链接应该以 `/` 或 `.html` 结尾 | `null` | -| `excerpt` | 纯文本的页面摘要。使用 [该插件](/zh-cn/docs/tag-plugins#文章摘要和截断) 来格式化文本 | -| `disableNunjucks` | 启用时禁用 Nunjucks 标签 `{{ }}`/`{% %}` 和 [标签插件](/zh-cn/docs/tag-plugins) 的渲染功能 | false | -| `lang` | 设置语言以覆盖 [自动检测](/zh-cn/docs/internationalization#路径) | 继承自 `_config.yml` | -| `published` | 文章是否发布 | 对于 `_posts` 下的文章为 `true`，对于 `_draft` 下的文章为 `false` | +| Setting | 描述 | 默认值 | +| ----------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------ | +| `layout` | 布局 | [`config.default_layout`](/docs/configuration#Writing) | +| `title` | 标题 | 文章的文件名 | +| `date` | 建立日期 | 文件建立日期 | +| `updated` | 更新日期 | 文件更新日期 | +| `comments` | 开启文章的评论功能 | `true` | +| `tags` | 标签（不适用于分页） | | +| `categories` | 分类（不适用于分页） | | +| `permalink` | Overrides the default permalink of the post. 覆盖文章的永久链接，永久链接应该以 `/` 或 `.html` 结尾 | `null` | +| `excerpt` | 纯文本的页面摘要。 使用 [该插件](/zh-cn/docs/tag-plugins#文章摘要和截断) 来格式化文本 | | +| `disableNunjucks` | 启用时禁用 Nunjucks 标签 `{{ }}`/`{% %}` 和 [标签插件](/zh-cn/docs/tag-plugins) 的渲染功能 | false | +| `lang` | 设置语言以覆盖 [自动检测](/zh-cn/docs/internationalization#路径) | 继承自 `_config.yml` | +| `published` | 文章是否发布 | 对于 `_posts` 下的文章为 `true`，对于 `_draft` 下的文章为 `false` | -## 布局 +#### 布局 -根据 `_config.yml` 中 [`default_layout`](/zh-cn/docs/configuration#文章) 的设置，默认布局是 `post` 。当文章中的布局被禁用(`layout: false`)，它将不会使用主题处理。然而，它仍然会被任何可用的渲染引擎渲染：如果一篇文章是用 Markdown 写的，并且安装了 Markdown 渲染引擎（比如默认的 [hexo-renderer-marked](https://github.com/hexojs/hexo-renderer-marked))，它将被渲染成HTML。 +根据 `_config.yml` 中 [`default_layout`](/zh-cn/docs/configuration#文章) 的设置，默认布局是 `post` 。 当文章中的布局被禁用(`layout: false`)，它将不会使用主题处理。 然而，它仍然会被任何可用的渲染引擎渲染：如果一篇文章是用 Markdown 写的，并且安装了 Markdown 渲染引擎（比如默认的 [hexo-renderer-marked](https://github.com/hexojs/hexo-renderer-marked))，它将被渲染成HTML。 除非通过 `disableNunjucks` 设置或 [渲染引擎](/zh-cn/api/renderer#禁用-Nunjucks-标签) 禁用，否则无论布局如何，[标签插件](/zh-cn/docs/tag-plugins) 总是被处理。 -## 分类和标签 +#### 分类和标签 + +Only posts support the use of categories and tags. Categories apply to posts in order, resulting in a hierarchy of classifications and sub-classifications. Tags are all defined on the same hierarchical level so the order in which they appear is not important. -只有文章支持分类和标签，您可以在 Front-matter 中设置。在其他系统中，分类和标签听起来很接近，但是在 Hexo 中两者有着明显的差别：分类具有顺序性和层次性，也就是说 `Foo, Bar` 不等于 `Bar, Foo`；而标签没有顺序和层次。 +**Example** ```yaml categories: @@ -48,18 +60,9 @@ tags: - Games ``` -{% note warn 分类方法的分歧 %} -如果您有过使用 WordPress 的经验，就很容易误解 Hexo 的分类方式。WordPress 支持对一篇文章设置多个分类，而且这些分类可以是同级的，也可以是父子分类。但是 Hexo 不支持指定多个同级分类。下面的指定方法： - -```yaml -categories: - - Diary - - Life -``` - -会使分类 `Life` 成为 `Diary` 的子分类，而不是并列分类。因此，有必要为您的文章选择尽可能准确的分类。 +If you want to apply multiple category hierarchies, use a list of names instead of a single name. If Hexo sees any categories defined this way on a post, it will treat each category for that post as its own independent hierarchy. -如果你需要为文章添加多个分类，可以尝试以下 list 中的方法。 +**Example** ```yaml categories: @@ -67,16 +70,3 @@ categories: - [Diary, Games] - [Life] ``` - -此时这篇文章同时包括三个分类： `PlayStation` 和 `Games` 分别都是父分类 `Diary` 的子分类，同时 `Life` 是一个没有子分类的分类。 -{% endnote %} - -## JSON Front-matter - -除了 YAML 外，你也可以使用 JSON 来编写 Front-matter，只要将 `---` 代换成 `;;;` 即可。 - -```json -"title": "Hello World", -"date": "2013/7/13 20:46:25" -;;; -``` diff --git a/source/zh-cn/docs/generating.md b/source/zh-cn/docs/generating.md index 737683e143..ff23e84420 100644 --- a/source/zh-cn/docs/generating.md +++ b/source/zh-cn/docs/generating.md @@ -8,9 +8,11 @@ title: 生成文件 $ hexo generate ``` +{% youtube viEJQPVCoLU %} + ### 监视文件变动 -Hexo 能够监视文件变动并立即重新生成静态文件，在生成时会比对文件的 SHA1 checksum，只有变动的文件才会写入。 +Hexo can watch for file changes and regenerate files immediately. Hexo 能够监视文件变动并立即重新生成静态文件，在生成时会比对文件的 SHA1 checksum，只有变动的文件才会写入。 ```bash $ hexo generate --watch @@ -18,15 +20,9 @@ $ hexo generate --watch ### 完成后部署 -您可执行下列的其中一个命令，让 Hexo 在生成完毕后自动部署网站，两个命令的作用是相同的。 +To deploy after generating, you can run one of the following commands. There is no difference between the two. ```bash $ hexo generate --deploy $ hexo deploy --generate ``` - -{% note info 简写 %} -上面两个命令可以简写为 -$ hexo g -d -$ hexo d -g -{% endnote %} diff --git a/source/zh-cn/docs/github-pages.md b/source/zh-cn/docs/github-pages.md old mode 100755 new mode 100644 index 5065fdd86f..548be746c6 --- a/source/zh-cn/docs/github-pages.md +++ b/source/zh-cn/docs/github-pages.md @@ -2,10 +2,10 @@ title: 在 GitHub Pages 上部署 Hexo --- -本文将使用 [GitHub Actions](https://docs.github.com/zh/actions) 部署至 GitHub Pages，此方法适用于公开或私人储存库。若你不希望将源文件夹上传到 GitHub，请参阅 [一键部署](#一键部署)。 +本文将使用 [GitHub Actions](https://docs.github.com/zh/actions) 部署至 GitHub Pages，此方法适用于公开或私人储存库。 It works in both public and private repositories. 若你不希望将源文件夹上传到 GitHub，请参阅 [一键部署](#一键部署)。 -1. 建立名为 `<你的 GitHub 用户名>.github.io` 的储存库，若之前已将 Hexo 上传至其他储存库，将该储存库重命名即可。 -2. 将 Hexo 文件夹中的文件 push 到储存库的默认分支，默认分支通常名为 `main`，旧一点的储存库可能名为 `master`。 +1. 部署完成后，前往 `https://<你的 GitHub 用户名>.github.io/<repository 的名字>` 查看网站。 If you have already uploaded to another repo, rename the repo instead. +2. 将 Hexo 文件夹中的文件 push 到储存库的默认分支，默认分支通常名为 `main`，旧一点的储存库可能名为 `master`。 The default branch is usually **main**, older repositories may use **master** branch. - 将 `main` 分支 push 到 GitHub： @@ -13,10 +13,10 @@ title: 在 GitHub Pages 上部署 Hexo $ git push -u origin main ``` -- 默认情况下 `public/` 不会被上传(也不该被上传)，确保 `.gitignore` 文件中包含一行 `public/`。整体文件夹结构应该与 [示例储存库](https://github.com/hexojs/hexo-starter) 大致相似。 +- 默认情况下 `public/` 不会被上传(也不该被上传)，确保 `.gitignore` 文件中包含一行 `public/`。 整体文件夹结构应该与 [示例储存库](https://github.com/hexojs/hexo-starter) 大致相似。 -3. 使用 `node --version` 指令检查你电脑上的 Node.js 版本，并记下该版本 (例如：`v20.y.z`) -4. 在储存库中前往 `Settings > Pages > Source`，并将 `Source` 改为 `GitHub Actions`。 +3. 使用 `node --version` 指令检查你电脑上的 Node.js 版本，并记下该版本 (例如：`v20.y.z`) Make a note of the major version (e.g., `v20.y.z`) +4. In your GitHub repo's setting, navigate to **Settings** > **Pages** > **Source**. Change the source to **GitHub Actions** and save. 5. 在储存库中建立 `.github/workflows/pages.yml`，并填入以下内容 (将 `20` 替换为上个步骤中记下的版本)： ```yml .github/workflows/pages.yml @@ -72,23 +72,21 @@ jobs: uses: actions/deploy-pages@v4 ``` -6. 部署完成后，前往 `https://<你的 GitHub 用户名>.github.io` 查看网站。 +6. Once the deployment is finished, check the webpage at _username_.github.io. -{% note info CNAME %} 若你使用了一个带有 `CNAME` 的自定义域名，你需要在 `source/` 文件夹中新增 `CNAME` 文件。 [更多信息](https://docs.github.com/zh/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site) -{% endnote %} ## 项目页面 -如果你希望网站部署在 `<你的 GitHub 用户名>.github.io` 的子目录中： +If you prefer to have a project page on GitHub: -1. 建立名为 `<repository 的名字>` 的储存库，这样你的博客网址为 `<你的 GitHub 用户名>.github.io/<repository 的名字>`，repository 的名字可以任意，例如 blog 或 hexo。 +1. Navigate to your repo on GitHub. Go to the **Settings** tab. 建立名为 `<repository 的名字>` 的储存库，这样你的博客网址为 `<你的 GitHub 用户名>.github.io/<repository 的名字>`，repository 的名字可以任意，例如 blog 或 hexo。 2. 编辑你的 `_config.yml`，将 `url:` 更改为 `<你的 GitHub 用户名>.github.io/<repository 的名字>`。 -3. 在储存库中前往 `Settings > Pages > Source`，并将 `Source` 改为 `GitHub Actions`。 +3. In your GitHub repo's setting, navigate to **Settings** > **Pages** > **Source**. Change the source to **GitHub Actions** and save. 4. Commit 并 push 到默认分支上。 -5. 部署完成后，前往 `https://<你的 GitHub 用户名>.github.io/<repository 的名字>` 查看网站。 +5. Once the deployment is finished, check the webpage at _username_.github.io/_repository_. -## 一键部署 +## One-command deployment 以下教学改编自 [一键部署](/zh-cn/docs/one-command-deployment)。 @@ -104,15 +102,10 @@ deploy: ``` 3. 执行 `hexo clean && hexo deploy` 。 -4. 浏览 `<GitHub 用户名>.github.io` 检查你的网站能否运作。 - -{% note info Windows 用户 %} -[Awesome Hexo](https://github.com/hexojs/awesome-hexo) 中收录了更多有关在 GitHub Pages 上部署 Hexo ，你也可通过搜索引擎了解更多。 -欢迎更多有志之士前来改善 Hexo 文档，不胜感激。 -{% endnote %} +4. Check the webpage at _username_.github.io. ## 参考链接 -- [GitHub Pages 使用文档](https://docs.github.com/zh/pages) -- [使用自定义 GitHub Actions 工作流进行发布](https://docs.github.com/zh/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#使用自定义-github-actions-工作流进行发布) +- [GitHub Pages 使用文档](https://docs.github.com/en/pages) +- [使用自定义 GitHub Actions 工作流进行发布](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) - [actions/deploy-github-pages-site](https://github.com/marketplace/actions/deploy-github-pages-site) diff --git a/source/zh-cn/docs/gitlab-pages.md b/source/zh-cn/docs/gitlab-pages.md index 9c4b985ffe..6613542cb0 100644 --- a/source/zh-cn/docs/gitlab-pages.md +++ b/source/zh-cn/docs/gitlab-pages.md @@ -2,11 +2,11 @@ title: 将 Hexo 部署到 GitLab Pages --- -在本教程中，我们将会使用 GitLab CI 将 Hexo 博客部署到 GitLab Pages 上。 - -1. 新建一个 repository。如果你希望你的站点能通过 `<你的 GitLab 用户名>.gitlab.io` 域名访问，你的 repository 应该直接命名为 `<你的 GitLab 用户名>.gitlab.io`。 -2. 将你的 Hexo 站点文件夹推送到 repository 中。默认情况下 `public` 目录将不会（并且不应该）被推送到 repository 中，建议你检查 `.gitignore` 文件中是否包含 `public` 一行，如果没有请加上。 -3. 在你的站点文件夹中新建 `.gitlab-ci.yml` 文件： +1. 如果你更希望你的站点部署在 `<你的 GitLab 用户名>.gitlab.io` 的子目录中，你的 repository 需要直接命名为子目录的名字，这样你的站点可以通过 `https://<你的 GitLab 用户名>.gitlab.io/<repository 的名字>` 访问。 你需要检查你的 Hexo 配置文件，将 `url` 的值修改为 `https://<你的 GitLab 用户名>.gitlab.io/<repository 的名字>`、将 `root` 的值修改为 `/<repository 的名字>/` +2. Enable Shared Runners via **Settings** > **CI/CD** > **Runners** > **Enable shared runners for this project**. +3. 将你的 Hexo 站点文件夹推送到 repository 中。 默认情况下 `public` 目录将不会（并且不应该）被推送到 repository 中，建议你检查 `.gitignore` 文件中是否包含 `public` 一行，如果没有请加上。 The folder structure should be roughly similar to [this repo](https://gitlab.com/pages/hexo). +4. Check what version of Node.js you are using on your local machine with `node --version`. Make a note of the major version (e.g., `v16.y.z`) +5. Add `.gitlab-ci.yml` file to the root folder of your repo (alongside \_config.yml & package.json) with the following content (replacing `16` with the major version of Node.js you noted in previous step): ```yml image: node:10-alpine # use nodejs v10 LTS @@ -28,19 +28,18 @@ pages: - master ``` -4. GitLab CI 应该会自动开始运行，构建成功以后你应该可以在 `https://<你的 GitLab 用户名>.gitlab.io` 查看你的网站。 -5. (可选) 如果你需要查看生成的文件，可以在 [job artifact](https://docs.gitlab.com/ee/ci/pipelines/job_artifacts.html) 中找到。 - -{% note info %} -在 GitLab.com 上，GitLab CI 是默认启用的。如果你使用的是自托管的 GitLab，你可能需要在 `Settings -> CI / CD -> Shared Runners` 启用 GitLab CI。 -{% endnote %} +6. GitLab CI 应该会自动开始运行，构建成功以后你应该可以在 `https://<你的 GitLab 用户名>.gitlab.io` 查看你的网站。 +7. (可选) 如果你需要查看生成的文件，可以在 [job artifact](https://docs.gitlab.com/ee/ci/pipelines/job_artifacts.html) 中找到。 ## Project page -如果你更希望你的站点部署在 `<你的 GitLab 用户名>.gitlab.io` 的子目录中，你的 repository 需要直接命名为子目录的名字，这样你的站点可以通过 `https://<你的 GitLab 用户名>.gitlab.io/<repository 的名字>` 访问。你需要检查你的 Hexo 配置文件，将 `url` 的值修改为 `https://<你的 GitLab 用户名>.gitlab.io/<repository 的名字>`、将 `root` 的值修改为 `/<repository 的名字>/` +If you prefer to have a project page on GitLab: + +1. Go to **Settings** > **General** > **Advanced** > **Change path**. Change the value to a name, so the website is available at <b>username.gitlab.io/_repository_</b>. It can be any name, like _blog_ or _hexo_. +2. Edit **\_config.yml**, change the `url:` value to `https://username.gitlab.io/repository`. +3. Commit and push. ## 参考链接 -- [GitLab Pages 相关文档](https://docs.gitlab.com/ee/user/project/pages/index.html) +- [GitLab Pages 相关文档](https://docs.gitlab.com/ee/user/project/pages/) - [GitLab CI 相关文档](https://docs.gitlab.com/ee/ci/yaml/) -- [在百度上搜索 "Hexo GitLab"](https://www.baidu.com/s?wd=Hexo%20GitLab) diff --git a/source/zh-cn/docs/helpers.md b/source/zh-cn/docs/helpers.md index 8bd98391c5..f8ee6c0724 100644 --- a/source/zh-cn/docs/helpers.md +++ b/source/zh-cn/docs/helpers.md @@ -2,23 +2,27 @@ title: 辅助函数（Helpers） --- -辅助函数帮助您在模版中快速插入内容。辅助函数不能在源文件中使用。 +辅助函数帮助您在模版中快速插入内容。 辅助函数不能在源文件中使用。 + +You could easily [write your own custom helper](https://hexo.io/api/helper.html) or use our ready-made helpers. + +{% youtube Uc53pW0GJHU %} ## 网址 ### url_for -在路径前加上根路径，从 Hexo 2.7 开始您应该使用此函数而不是 `config.root + path`。 +在路径前加上根路径和域名。 输出会被自动转码。 ```js <%- url_for(path, [option]) %> ``` -| 参数 | 描述 | 默认值 | -| ---------- | ---------------- | --------------------------- | +| Option | 描述 | 默认值 | +| ---------- | -------- | ------------------------- | | `relative` | 是否输出相对链接 | `config.relative_link` 的值 | -**示例：** +**class_level** ```yml _config.yml @@ -30,8 +34,7 @@ root: /blog/ // /blog/a/path ``` -是否输出相对链接，默认遵循配置文件中 `relative_link` 的值 -例如， post/page 的相对路径值可能是 `/foo/bar/index.html` +是否输出相对链接，默认遵循配置文件中 `relative_link` 的值 例如， post/page 的相对路径值可能是 `/foo/bar/index.html` ```yml _config.yml @@ -45,6 +48,9 @@ relative_link: true * 即使配置文件中启用了 relative_link，你也可以使用 relative 参数禁用相对链接输出，反之亦然 */ <%- url_for('/css/style.css', {relative: false}) %> +// /css/style.css + */ +<%- url_for('/css/style.css', {relative: false}) %> // /css/style.css ``` @@ -63,22 +69,42 @@ relative_link: true // ../../css/style.css ``` +### full_url_for + +Returns a URL with the `config.url` prefixed. Output is encoded automatically. + +```js +<%- full_url_for(path) %> +``` + +**示例：** + +```yml +_config.yml +url: https://example.com/blog # example +``` + +```js +<%- full_url_for('/a/path') %> +// https://example.com/blog/a/path +``` + ### gravatar 根据邮箱地址返回 Gravatar 头像 URL。 -如果你不指定 `options` 参数，将会应用默认参数。否则，你可以将其设置为一个数字，这个数字将会作为 Gravatar 的大小参数。最后，如果你设置它一个对象，它将会被转换为 Gravatar 的一个查询字符串参数。 +如果你不指定 `options` 参数，将会应用默认参数。 否则，你可以将其设置为一个数字，这个数字将会作为 Gravatar 的大小参数。 最后，如果你设置它一个对象，它将会被转换为 Gravatar 的一个查询字符串参数。 ```js <%- gravatar(email, [options]) %> ``` -| 参数 | 描述 | 默认值 | -| ---- | ---------------- | ------ | -| `s` | 图片大小 | 80 | -| `d` | 默认头像 | -| `f` | 强制使用默认图象 | -| `r` | 头像等级限制 | +| Option | 描述 | 默认值 | +| ------ | -------- | --- | +| `s` | 图片大小 | 80 | +| `d` | 默认头像 | | +| `f` | 强制使用默认图象 | | +| `r` | Rating | | 访问 [Gravatar](https://en.gravatar.com/site/implement/images/) 了解更多。 @@ -95,31 +121,11 @@ relative_link: true // https://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787?s=40&d=https%3A%2F%2Fvia.placeholder.com%2F150 ``` -### full_url_for - -在路径前加上根路径和域名。输出会被自动转码。 - -```js -<%- full_url_for(path) %> -``` - -**示例：** - -```yml -_config.yml -url: https://example.com/blog # example -``` - -```js -<%- full_url_for('/a/path') %> -// https://example.com/blog/a/path -``` - ## HTML 标签 ### css -加载 CSS 文件。`path` 可以是数组或字符串，如果 `path` 开头不是 `/` 或任何协议，则会自动加上根路径；如果后面没有加上 `.css` 扩展名的话，也会自动加上。对于自定义属性请使用对象类型。 +加载 CSS 文件。 `path` can be an array or a string. `path` can be a string, an array, an object or an array of objects. `path` 可以是数组或字符串，如果 `path` 开头不是 `/` 或任何协议，则会自动加上根路径；如果后面没有加上 `.css` 扩展名的话，也会自动加上。 对于自定义属性请使用对象类型。 ```js <%- css(path, ...) %> @@ -145,7 +151,7 @@ url: https://example.com/blog # example ### js -加载 JavaScript 文件。`path` 可以是数组或字符串，如果 `path` 开头不是 `/` 或任何协议，则会自动加上根路径；如果后面没有加上 `.js` 扩展名的话，也会自动加上。对于自定义属性请使用对象类型。 +加载 JavaScript 文件。 `path` can be a string, an array, an object or an array of objects. `path` 可以是数组或字符串，如果 `path` 开头不是 `/` 或任何协议，则会自动加上根路径；如果后面没有加上 `.js` 扩展名的话，也会自动加上。 对于自定义属性请使用对象类型。 ```js <%- js(path, ...) %> @@ -177,11 +183,11 @@ url: https://example.com/blog # example <%- link_to(path, [text], [options]) %> ``` -| 参数 | 描述 | 默认值 | -| ---------- | ---------------- | ------ | -| `external` | 在新视窗打开链接 | false | -| `class` | Class 名称 | -| `id` | ID | +| Option | 描述 | 默认值 | +| ---------- | -------- | ----- | +| `external` | 在新视窗打开链接 | false | +| `class` | Class 名称 | | +| `id` | ID | | **示例：** @@ -204,14 +210,14 @@ url: https://example.com/blog # example <%- mail_to(path, [text], [options]) %> ``` -| 参数 | 描述 | -| --------- | ----------- | -| `class` | Class 名称 | -| `id` | ID | -| `subject` | 邮件主题 | -| `cc` | 抄送（CC） | -| `bcc` | 密送（BCC） | -| `body` | 邮件内容 | +| Option | 描述 | +| --------- | -------- | +| `class` | Class 名称 | +| `id` | ID | +| `subject` | 邮件主题 | +| `cc` | CC | +| `bcc` | 密送（BCC） | +| `body` | 邮件内容 | **示例：** @@ -231,13 +237,13 @@ url: https://example.com/blog # example <%- image_tag(path, [options]) %> ``` -| 参数 | 描述 | -| -------- | -------------- | -| `alt` | 图片的替代文字 | -| `class` | Class 名称 | -| `id` | ID | -| `width` | 图片宽度 | -| `height` | 图片高度 | +| Option | 描述 | +| -------- | -------- | +| `alt` | 图片的替代文字 | +| `class` | Class 名称 | +| `id` | ID | +| `width` | 图片宽度 | +| `height` | 图片高度 | ### favicon_tag @@ -255,10 +261,10 @@ url: https://example.com/blog # example <%- feed_tag(path, [options]) %> ``` -| 参数 | 描述 | 默认值 | -| ------- | --------- | -------------- | +| Option | 描述 | 默认值 | +| ------- | ------- | -------------- | | `title` | Feed 标题 | `config.title` | -| `type` | Feed 类型 | +| `type` | Feed 类型 | | **示例：** @@ -274,11 +280,11 @@ url: https://example.com/blog # example // <link rel="alternate" href="/atom.xml" title="Hexo" type="application/atom+xml"> ``` -## 条件函数 +## Conditional Tags ### is_current -检查 `path` 是否符合目前页面的网址。开启 `strict` 选项启用严格比对。 +检查 `path` 是否符合目前页面的网址。 开启 `strict` 选项启用严格比对。 ```js <%- is_current(path, [strict]) %> @@ -286,7 +292,7 @@ url: https://example.com/blog # example ### is_home -检查当前页面是否为首页。 +检查当前页面是否为文章。 ```js <%- is_home() %> @@ -294,7 +300,7 @@ url: https://example.com/blog # example ### is_home_first_page (+6.3.0) -检查当前页面是否为首页的第一页。 +检查当前页面是否为独立页面。 ```js <%- is_home_first_page() %> @@ -302,7 +308,7 @@ url: https://example.com/blog # example ### is_post -检查当前页面是否为文章。 +检查当前页面是否为存档页面。 ```js <%- is_post() %> @@ -310,7 +316,7 @@ url: https://example.com/blog # example ### is_page -检查当前页面是否为独立页面。 +检查当前页面是否为年度归档页面。 ```js <%- is_page() %> @@ -318,7 +324,7 @@ url: https://example.com/blog # example ### is_archive -检查当前页面是否为存档页面。 +检查当前页面是否为月度归档页面。 ```js <%- is_archive() %> @@ -326,7 +332,7 @@ url: https://example.com/blog # example ### is_year -检查当前页面是否为年度归档页面。 +Check whether the current page is a yearly archive page. ```js <%- is_year() %> @@ -334,7 +340,7 @@ url: https://example.com/blog # example ### is_month -检查当前页面是否为月度归档页面。 +检查当前页面是否为首页。 ```js <%- is_month() %> @@ -342,8 +348,7 @@ url: https://example.com/blog # example ### is_category -检查当前页面是否为分类归档页面。 -如果给定一个字符串作为参数，将会检查目前是否为指定分类。 +检查当前页面是否为分类归档页面。 如果给定一个字符串作为参数，将会检查目前是否为指定分类。 ```js <%- is_category() %> @@ -352,8 +357,7 @@ url: https://example.com/blog # example ### is_tag -检查当前页面是否为标签归档页面。 -如果给定一个字符串作为参数，将会检查目前是否为指定标签。 +检查当前页面是否为标签归档页面。 如果给定一个字符串作为参数，将会检查目前是否为指定标签。 ```js <%- is_tag() %> @@ -382,6 +386,7 @@ url: https://example.com/blog # example ```js <%- strip_html('It\'s not <b>important</b> anymore!') %> +// It's not important anymore! %> // It's not important anymore! ``` @@ -434,7 +439,7 @@ url: https://example.com/blog # example ### word_wrap -使每行的字符串长度不超过 `length`。`length` 预设为 80。 +使每行的字符串长度不超过 `length`。 `length` 预设为 80。 ```js <%- word_wrap(str, [length]) %> @@ -449,7 +454,7 @@ url: https://example.com/blog # example ### truncate -移除超过 `length` 长度的字符串。`length` 的默认值是 30。 +移除超过 `length` 长度的字符串。 `length` 的默认值是 30。 ```js <%- truncate(text, length) %> @@ -464,6 +469,12 @@ url: https://example.com/blog # example <%- truncate('Once upon a time in a world far far away', {length: 17, separator: ' '}) %> // Once upon a... +<%- truncate('And they found that many people were sleeping better.', {length: 25, omission: '... (continued)'}) %> +// And they f... (continued) + +<%- truncate('Once upon a time in a world far far away', {length: 17, separator: ' '}) %> +// Once upon a... + <%- truncate('And they found that many people were sleeping better.', {length: 25, omission: '... (continued)'}) %> // And they f... (continued) ``` @@ -487,20 +498,20 @@ url: https://example.com/blog # example ### partial -加载其他模板文件，您可在 `locals` 设定区域变量。 +Loads other template files. You can define local variables in `locals`. ```js <%- partial(layout, [locals], [options]) %> ``` -| 参数 | 描述 | 默认值 | -| ------- | ------------------------------------------------------ | ------- | -| `cache` | 缓存（使用 Fragment cache） | `false` | -| `only` | 限制局部变量。在模板中只能使用 `locals` 中设定的变量。 | `false` | +| Option | 描述 | 默认值 | +| ------- | --------------------------------- | ------- | +| `cache` | 缓存（使用 Fragment cache） | `false` | +| `only` | 限制局部变量。 在模板中只能使用 `locals` 中设定的变量。 | `false` | ### fragment_cache -局部缓存。它储存局部内容，下次使用时就能直接使用缓存。 +局部缓存。 它储存局部内容，下次使用时就能直接使用缓存。 ```js <%- fragment_cache(id, fn); @@ -518,7 +529,7 @@ url: https://example.com/blog # example ### date -插入格式化的日期。`date` 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js] 对象。`format` 默认为 `date_format` 配置信息。 +插入格式化的日期。 `date` 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js][] 对象。 `format` 默认为 `date_format` 配置信息。 ```js <%- date(date, [format]) %> @@ -536,7 +547,7 @@ url: https://example.com/blog # example ### date_xml -插入 XML 格式的日期。`date` 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js] 对象。 +插入 XML 格式的日期。 `date` 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js][] 对象。 ```js <%- date_xml(date) %> @@ -551,7 +562,7 @@ url: https://example.com/blog # example ### time -插入格式化的时间。`date` 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js] 对象。`format` 默认为 `time_format` 配置信息。 +插入格式化的时间。 `date` 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js][] 对象。 `format` 默认为 `time_format` 配置信息。 ```js <%- time(date, [format]) %> @@ -569,7 +580,7 @@ url: https://example.com/blog # example ### full_date -插入格式化的日期和时间。`date` 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js] 对象。`format` 默认为 `date_format + time_format`。 +插入格式化的日期和时间。 `date` 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js][] 对象。 `format` 默认为 `date_format + time_format`。 ```js <%- full_date(date, [format]) %> @@ -587,7 +598,7 @@ url: https://example.com/blog # example ### relative_date -插入相对当前的时间。`date` 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js] 对象。 +插入相对当前的时间。 `date` 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js][] 对象。 ```js <%- relative_date(date) %> @@ -605,7 +616,7 @@ url: https://example.com/blog # example ### time_tag -插入时间标签。`date` 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js] 对象。`format` 默认为 `date_format` 配置信息。 +插入时间标签。 `date` 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js][] 对象。 `format` 默认为 `date_format` 配置信息。 ```js <%- time_tag(date, [format]) %> @@ -623,7 +634,7 @@ url: https://example.com/blog # example ### moment -[Moment.js] 函数库。 +[Moment.js][] 函数库。 ## 列表 @@ -635,17 +646,17 @@ url: https://example.com/blog # example <%- list_categories([options]) %> ``` -| 参数 | 描述 | 默认值 | -| ------------ | -------------------------------------------------------------------------------------------------------- | -------- | -| `orderby` | 分类排列方式 | name | -| `order` | 分类排列顺序。`1`, `asc` 升序；`-1`, `desc` 降序。 | 1 | -| `show_count` | 显示每个分类的文章总数 | true | -| `style` | 分类列表的显示方式。使用 `list` 以无序列表（unordered list）方式显示。 | list | -| `separator` | 分类间的分隔符号。只有在 `style` 不是 `list` 时有用。 | , | -| `depth` | 要显示的分类层级。`0` 显示所有层级的分类；`-1` 和 `0` 很类似，但是显示不分层级；`1` 只显示第一层的分类。 | 0 | -| `class` | 分类列表的 class 名称。 | category | -| `transform` | 改变分类名称显示方法的函数 | -| `suffix` | 为链接添加前缀 | None | +| Option | 描述 | 默认值 | +| ------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `orderby` | 分类排列方式 | name | +| `order` | 排列顺序。 `1`, `asc` 升序；`-1`, `desc` 降序。 | 1 | +| `show_count` | 显示每个分类的文章总数 | true | +| `style` | Style to display the category list. 分类列表的显示方式。 使用 `list` 以无序列表（unordered list）方式显示。 Use `false` or any other value to disable it. | list | +| `separator` | 分类间的分隔符号。 只有在 `style` 不是 `list` 时有用。 | , | +| `depth` | 要显示的分类层级。 `0` 显示所有层级的分类；`-1` 和 `0` 很类似，但是显示不分层级；`1` 只显示第一层的分类。 | 0 | +| `class` | 分类列表的 class 名称。 | category | +| `transform` | 改变分类名称显示方法的函数 | | +| `suffix` | 为链接添加前缀 | None | **示例：** @@ -672,27 +683,27 @@ url: https://example.com/blog # example <%- list_tags([options]) %> ``` -| 选项 | 描述 | 预设值 | -| ------------ | ----------------------------------------------------------------------------------- | ------ | -| `orderby` | 标签排列方式 | name | -| `order` | 标签排列顺序。`1`, `asc` 升序；`-1`, `desc` 降序。 | 1 | -| `show_count` | 显示每个标签的文章总数 | true | -| `style` | 标签列表的显示方式。使用 `list` 以无序列表（unordered list）方式显示。 | list | -| `separator` | 标签间的分隔符号。只有在 `style` 不是 `list` 时有用。 | , | -| `class` | 标签列表的类名（字符串）或自定义每个标签的类（对象，见下文）。 | tag | -| `transform` | 改变标签名称显示方法的函数。请查看 [list_categories](#list-categories) 中给出的例子 | -| `amount` | 要显示的标签数量（0 = 无限制） | 0 | -| `suffix` | 为链接添加前缀 | None | +| 选项 | 描述 | Default | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------- | ------- | +| `orderby` | Order of categories | name | +| `order` | 分类排列顺序。 `1`, `asc` 升序；`-1`, `desc` 降序。 | 1 | +| `show_count` | 显示每个标签的文章总数 | true | +| `style` | Style to display the tag list. 标签列表的显示方式。 使用 `list` 以无序列表（unordered list）方式显示。 Use `false` or any other value to disable it. | list | +| `separator` | 标签间的分隔符号。 只有在 `style` 不是 `list` 时有用。 | , | +| `class` | 标签列表的类名（字符串）或自定义每个标签的类（对象，见下文）。 | tag | +| `transform` | 改变标签名称显示方法的函数。 请查看 [list_categories](#list-categories) 中给出的例子 | | +| `amount` | 要显示的标签数量（0 = 无限制） | 0 | +| `suffix` | 为链接添加前缀 | None | 类的高级定制： -| 选项 | 描述 | 预设值 | -| ------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -| `class.ul` | `<ul>` 类名 （只适用于样式 `list`） | `tag-list` （列表样式） | -| `class.li` | `<li>` 类名 （只适用于样式 `list`） | `tag-list-item` （列表样式） | -| `class.a` | `<a>` 类名 | `tag-list-link` （列表样式） `tag-link` （普通样式） | -| `class.label` | `<span>` 类名，标签 label 存储在这里（仅适用于普通样式，当 `class.label` 被设置时，标签被放置在 `<span>` 中） | `tag-label` （普通样式） | -| `class.count` | `<span>` 类名，标签 counter 存储在这里 （仅当 `show_count` 为 `true`） | `tag-list-count` （列表样式） `tag-count` （普通样式） | +| 选项 | 描述 | Default | +| ------------- | --------------------------------------------------------------------------------------- | ------------------------------------------ | +| `class.ul` | `<ul>` 类名 （只适用于样式 `list`） | `tag-list` （列表样式） | +| `class.li` | `<li>` 类名 （只适用于样式 `list`） | `tag-list-item` （列表样式） | +| `class.a` | `<a>` 类名 | `tag-list-link` （列表样式） `tag-link` （普通样式） | +| `class.label` | `<span>` 类名，标签 label 存储在这里（仅适用于普通样式，当 `class.label` 被设置时，标签被放置在 `<span>` 中） | `tag-label` （普通样式） | +| `class.count` | `<span>` 类名，标签 counter 存储在这里 （仅当 `show_count` 为 `true`） | `tag-list-count` （列表样式） `tag-count` （普通样式） | 示例： @@ -711,16 +722,16 @@ url: https://example.com/blog # example <%- list_archives([options]) %> ``` -| 参数 | 描述 | 默认值 | -| ------------ | ----------------------------------------------------------------------------------- | --------- | -| `type` | 类型。此设定可为 `yearly` 或 `monthly`。 | monthly | -| `order` | 排列顺序。`1`, `asc` 升序；`-1`, `desc` 降序。 | 1 | -| `show_count` | 显示每个归档的文章总数 | true | -| `format` | 日期格式 | MMMM YYYY | -| `style` | 归档列表的显示方式。使用 `list` 以无序列表（unordered list）方式显示。 | list | -| `separator` | 归档间的分隔符号。只有在 `style` 不是 `list` 时有用。 | , | -| `class` | 归档列表的 class 名称。 | archive | -| `transform` | 改变归档名称显示方法的函数。请查看 [list_categories](#list-categories) 中给出的例子 | +| Option | 描述 | 默认值 | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------- | --------- | +| `type` | 类型。 此设定可为 `yearly` 或 `monthly`。 | monthly | +| `order` | 标签排列顺序。 `1`, `asc` 升序；`-1`, `desc` 降序。 | 1 | +| `show_count` | 显示每个归档的文章总数 | true | +| `format` | 日期格式 | MMMM YYYY | +| `style` | Style to display the archive list. 归档列表的显示方式。 使用 `list` 以无序列表（unordered list）方式显示。 Use `false` or any other value to disable it. | list | +| `separator` | 归档间的分隔符号。 只有在 `style` 不是 `list` 时有用。 | , | +| `class` | 归档列表的 class 名称。 | archive | +| `transform` | 改变归档名称显示方法的函数。 请查看 [list_categories](#list-categories) 中给出的例子 | | ### list_posts @@ -730,15 +741,15 @@ url: https://example.com/blog # example <%- list_posts([options]) %> ``` -| 参数 | 描述 | 默认值 | -| ----------- | ----------------------------------------------------------------------------------- | ------ | -| `orderby` | 文章排列方式 | date | -| `order` | 文章排列顺序。`1`, `asc` 升序；`-1`, `desc` 降序。 | -1 | -| `style` | 文章列表的显示方式。使用 `list` 以无序列表（unordered list）方式显示。 | list | -| `separator` | 文章间的分隔符号。只有在 `style` 不是 `list` 时有用。 | , | -| `class` | 文章列表的 class 名称。 | post | -| `amount` | 要显示的文章数量（0 = 无限制） | 6 | -| `transform` | 改变文章名称显示方法的函数。请查看 [list_categories](#list-categories) 中给出的例子 | +| Option | 描述 | 默认值 | +| ----------- | --------------------------------------------------------------------------------------------- | ---- | +| `orderby` | Order of posts | date | +| `order` | 文章排列顺序。 `1`, `asc` 升序；`-1`, `desc` 降序。 | 1 | +| `style` | 文章列表的显示方式。 使用 `list` 以无序列表（unordered list）方式显示。 Use `false` or any other value to disable it. | list | +| `separator` | 文章间的分隔符号。 只有在 `style` 不是 `list` 时有用。 | , | +| `class` | 文章列表的 class 名称。 | post | +| `amount` | 要显示的文章数量（0 = 无限制） | 6 | +| `transform` | 改变文章名称显示方法的函数。 请查看 [list_categories](#list-categories) 中给出的例子 | | ### tagcloud @@ -748,52 +759,62 @@ url: https://example.com/blog # example <%- tagcloud([tags], [options]) %> ``` -| 参数 | 描述 | 默认值 | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -| `min_font` | 最小字体尺寸 | 10 | -| `max_font` | 最大字体尺寸 | 20 | -| `unit` | 字体尺寸的单位 | px | -| `amount` | 标签总量 | 40 | -| `orderby` | 标签排列方式 | name | -| `order` | 标签排列顺序。`1`, `sac` 升序；`-1`, `desc` 降序 | 1 | -| `color` | 使用颜色 | false | -| `start_color` | 开始的颜色。您可使用十六进位值（`#b700ff`），rgba（`rgba(183, 0, 255, 1)`），hsla（`hsla(283, 100%, 50%, 1)`）或 [颜色关键字]。此变量仅在 `color` 参数开启时才有用。 | -| `end_color` | 结束的颜色。您可使用十六进位值（`#b700ff`），rgba（`rgba(183, 0, 255, 1)`），hsla（`hsla(283, 100%, 50%, 1)`）或 [颜色关键字]。此变量仅在 `color` 参数开启时才有用。 | -| `class` | 标签的 class name 前缀 | -| `level` | 不同 class name 的总数。此变量仅在 `class` 参数设定时才有用。 | 10 | -| `show_count` (+6.3.0) | 显示每个标签的文章总数 | false | -| `count_class` (+6.3.0) | 标签文章总数的 class | `count` | +| Option | 描述 | 默认值 | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------- | +| `min_font` | 最小字体尺寸 | 10 | +| `max_font` | 最大字体尺寸 | 20 | +| `unit` | 字体尺寸的单位 | px | +| `amount` | 标签总量 | unlimited | +| `orderby` | 标签排列方式 | name | +| `order` | 标签排列顺序。 `1`, `sac` 升序；`-1`, `desc` 降序 | 1 | +| `color` | 使用颜色 | false | +| `start_color` | 开始的颜色。 您可使用十六进位值（`#b700ff`），rgba（`rgba(183, 0, 255, 1)`），hsla（`hsla(283, 100%, 50%, 1)`）或 [颜色关键字][]。 此变量仅在 `color` 参数开启时才有用。 | | +| `end_color` | 结束的颜色。 您可使用十六进位值（`#b700ff`），rgba（`rgba(183, 0, 255, 1)`），hsla（`hsla(283, 100%, 50%, 1)`）或 [颜色关键字][]。 此变量仅在 `color` 参数开启时才有用。 | | +| `class` | 标签的 class name 前缀 | | +| `level` | 不同 class name 的总数。 此变量仅在 `class` 参数设定时才有用。 | 10 | +| `show_count` (+6.3.0) | 显示每个标签的文章总数 | false | +| `count_class` (+6.3.0) | 标签文章总数的 class | count | + +**示例：** + +```js +// Default options +<%- tagcloud() %> + +// Limit number of tags to 30 +<%- tagcloud({amount: 30}) %> +``` ## 其他 ### paginator -插入分页链接。 +Inserts a paginator. ```js <%- paginator(options) %> ``` -| 参数 | 描述 | 默认值 | -| -------------------------- | --------------------------------------------------------------------- | ------------- | -| `base` | 基础网址 | / | -| `format` | 网址格式 | page/%d/ | -| `total` | 分页总数 | 1 | -| `current` | 目前页数 | 0 | -| `prev_text` | 上一页链接的文字。仅在 `prev_next` 设定开启时才有用。 | Prev | -| `next_text` | 下一页链接的文字。仅在 `prev_next` 设定开启时才有用。 | Next | -| `space` | 空白文字 | … | -| `prev_next` | 显示上一页和下一页的链接 | true | -| `end_size` | 显示于两侧的页数 | 1 | -| `mid_size` | 显示于中间的页数 | 2 | -| `show_all` | 显示所有页数。如果开启此参数的话，`end_size` 和 `mid_size` 就没用了。 | false | -| `escape` | 转义 HTML 标签 | true | -| `page_class` | 分页链接的 class 名称 | `page-number` | -| `current_class` (+6.3.0) | 当前页链接的 class 名称 | `current` | -| `space_class` (+6.3.0) | 空白文字的 class 名称 | `space` | -| `prev_class` (+6.3.0) | 上一页链接的 class 名称 | `extend prev` | -| `next_class` (+6.3.0) | 下一页链接的 class 名称 | `extend next` | -| `force_prev_next` (+6.3.0) | 强制显示上一页和下一页的链接 | false | +| Option | 描述 | 默认值 | +| -------------------------- | ----------------------------------------------- | ------------- | +| `base` | 基础网址 | / | +| `format` | 网址格式 | page/%d/ | +| `total` | 分页总数 | 1 | +| `current` | 目前页数 | 0 | +| `prev_text` | 上一页链接的文字。 仅在 `prev_next` 设定开启时才有用。 | Prev | +| `next_text` | 下一页链接的文字。 仅在 `prev_next` 设定开启时才有用。 | Next | +| `space` | 空白文字 | … | +| `prev_next` | 显示上一页和下一页的链接 | true | +| `end_size` | 显示于两侧的页数 | 1 | +| `mid_size` | 显示于中间的页数 | 2 | +| `show_all` | 显示所有页数。 如果开启此参数的话，`end_size` 和 `mid_size` 就没用了。 | false | +| `escape` | 转义 HTML 标签 | true | +| page_class | 分页链接的 class 名称 | `page-number` | +| `current_class` (+6.3.0) | 当前页链接的 class 名称 | `current` | +| `space_class` (+6.3.0) | 空白文字的 class 名称 | `space` | +| `prev_class` (+6.3.0) | 上一页链接的 class 名称 | `extend prev` | +| `next_class` (+6.3.0) | 下一页链接的 class 名称 | `extend next` | +| `force_prev_next` (+6.3.0) | 强制显示上一页和下一页的链接 | false | **示例：** @@ -838,11 +859,11 @@ url: https://example.com/blog # example <%- search_form(options) %> ``` -| 参数 | 描述 | 默认值 | -| -------- | --------------------------------------------------------------------------------------------- | ----------- | -| `class` | 表单的 class name | search-form | -| `text` | 搜索提示文字 | Search | -| `button` | 显示搜索按钮。此参数可为布尔值（boolean）或字符串，当设定是字符串的时候，即为搜索按钮的文字。 | false | +| Option | 描述 | 默认值 | +| -------- | ---------------------------------------------------------------------------------------------------------- | ----------- | +| `class` | 表单的 class name | search-form | +| `text` | 搜索提示文字 | Search | +| `button` | 显示搜索按钮。 The value can be a boolean or a string. If the value is a string, it'll be the text of the button. | false | ### number_format @@ -852,11 +873,11 @@ url: https://example.com/blog # example <%- number_format(number, [options]) %> ``` -| 参数 | 描述 | 默认值 | -| ----------- | ----------------------------------------- | ------ | -| `precision` | 数字精度。此选项可为 `false` 或非负整数。 | false | -| `delimiter` | 千位数分隔符号 | , | -| `separator` | 整数和小数之间的分隔符号 | . | +| Option | 描述 | 默认值 | +| ----------- | -------------------------- | ----- | +| `precision` | 数字精度。 此选项可为 `false` 或非负整数。 | false | +| `delimiter` | 千位数分隔符号 | , | +| `separator` | 整数和小数之间的分隔符号 | . | **示例：** @@ -894,31 +915,31 @@ url: https://example.com/blog # example ### open_graph -插入 open graph 资源。 +Inserts [Open Graph][] data. ```js <%- open_graph([options]) %> ``` -| 参数 | 描述 | 默认值 | -| --------------- | ------------------------------------------ | --------------------------------------------------- | -| `title` | 页面标题 (`og:title`) | `page.title` | -| `type` | 页面类型 (`og:type`) | article(post page)<br>website(non-post page) | -| `url` | 页面网址 (`og:url`) | `url` | -| `image` | 页面图片 (`og:image`) | 内容中的图片 | -| `author` | 文章作者 (`og:article:author`) | `config.author` | -| `date` | 文章发表时间 (`og:article:published_time`) | 页面发表时间 | -| `updated` | 文章修改时间 (`og:article:modified_time`) | 页面修改时间 | -| `language` | 文章语言 (`og:locale`) | `page.lang \|\| page.language \|\| config.language` | -| `site_name` | 网站名称 (`og:site_name`) | `config.title` | -| `description` | 页面描述 (`og:description`) | 内容摘要或前 200 字 | -| `twitter_card` | Twitter 卡片类型 (`twitter:card`) | summary | -| `twitter_id` | Twitter ID (`twitter:creator`) | -| `twitter_site` | Twitter 网站 (`twitter:site`) | -| `twitter_image` | Twitter 图片 (`twitter:image`) | -| `google_plus` | Google+ 个人资料链接 | -| `fb_admins` | Facebook 管理者 ID | -| `fb_app_id` | Facebook 应用程序 ID | +| Option | 描述 | 默认值 | +| --------------- | ------------------------------------ | ------------------------------------------------------- | +| `title` | 页面标题 (`og:title`) | `page.title` | +| `type` | 页面类型 (`og:type`) | article(post page)<br>website(non-post page) | +| `url` | 页面网址 (`og:url`) | `url` | +| `image` | 页面图片 (`og:image`) | 内容中的图片 | +| `author` | 文章作者 (`og:article:author`) | `config.author` | +| `date` | 文章发表时间 (`og:article:published_time`) | 页面发表时间 | +| `updated` | 文章修改时间 (`og:article:modified_time`) | 页面修改时间 | +| `language` | 文章语言 (`og:locale`) | `page.lang \|\| page.language \|\| config.language` | +| `site_name` | 网站名称 (`og:site_name`) | `config.title` | +| `description` | 页面描述 (`og:description`) | 内容摘要或前 200 字 | +| `twitter_card` | Twitter 卡片类型 (`twitter:card`) | summary | +| `twitter_id` | Twitter ID (`twitter:creator`) | | +| `twitter_site` | Twitter 网站 (`twitter:site`) | | +| `twitter_image` | Twitter 图片 (`twitter:image`) | | +| `google_plus` | Google+ 个人资料链接 | | +| `fb_admins` | Facebook 管理者 ID | | +| `fb_app_id` | Facebook 应用程序 ID | | ### toc @@ -928,18 +949,18 @@ url: https://example.com/blog # example <%- toc(str, [options]) %> ``` -| 参数 | 描述 | 默认值 | -| ----------------------- | --------------------------- | ----------------- | -| `class` | Class 名称 | `toc` | -| `class_item` (+6.3.0) | 目录元素的 Class 名称 | `${class}-item` | +| Option | 描述 | 默认值 | +| ----------------------- | ------------------- | ----------------- | +| `class` | Class 名称 | `toc` | +| `class_item` (+6.3.0) | 目录元素的 Class 名称 | `${class}-item` | | `class_link` (+6.3.0) | 目录内链接的 Class 名称 | `${class}-link` | -| `class_text` (+6.3.0) | 目录链接内文本的 Class 名称 | `${class}-text` | -| `class_child` (+6.3.0) | 目录内子列表的 Class 名称 | `${class}-child` | -| `class_number` (+6.3.0) | 目录序号的 Class 名称 | `${class}-number` | -| `class_level` | 目录层级的 Class 名称前缀 | `${class}-level` | -| `list_number` | 显示编号 | true | -| `max_depth` | 生成 TOC 的最大深度 | 6 | -| `min_depth` | 生成 TOC 的最小深度 | 1 | +| `class_text` (+6.3.0) | 目录链接内文本的 Class 名称 | `${class}-text` | +| `class_child` (+6.3.0) | Class name of child | `${class}-child` | +| `class_number` (+6.3.0) | 目录序号的 Class 名称 | `${class}-number` | +| `class_level` (+6.3.0) | 目录层级的 Class 名称前缀 | `${class}-level` | +| `list_number` | 显示编号 | true | +| `max_depth` | 生成 TOC 的最大深度 | 6 | +| `min_depth` | 生成 TOC 的最小深度 | 1 | **示例：** @@ -951,7 +972,7 @@ url: https://example.com/blog # example 带有 `data-toc-unnumbered="true"` 属性的标题将被标记为未编号（不显示列表编号）。 -{% note warn "警告！" %} +{% note warn "警告！" %} %} 对于使用 `data-toc-unnumbered="true"`，渲染引擎必须要有添加 CSS 类的选项。 请看下面的 PR。 diff --git a/source/zh-cn/docs/index.md b/source/zh-cn/docs/index.md index 929b472416..8e0722d15b 100644 --- a/source/zh-cn/docs/index.md +++ b/source/zh-cn/docs/index.md @@ -2,26 +2,26 @@ title: 文档 --- -欢迎使用 Hexo，本文档将帮助您快速上手。如果您在使用过程中遇到问题，请查看 [问题解答](troubleshooting.html) 中的解答，或者在 [GitHub](https://github.com/hexojs/hexo/issues)、[Google Group](https://groups.google.com/group/hexo) 上提问。 +欢迎使用 Hexo，本文档将帮助您快速上手。 如果您在使用过程中遇到问题，请查看 [问题解答](troubleshooting.html) 中的解答，或者在 [GitHub](https://github.com/hexojs/hexo/issues)、[Google Group](https://groups.google.com/group/hexo) 上提问。 ## 什么是 Hexo？ -Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 [Markdown](http://daringfireball.net/projects/markdown/)（或其他标记语言）解析文章，在几秒内，即可利用靓丽的主题生成静态网页。 - -{% youtube PsXWbI2Mqu0 %} +Hexo 是一个快速、简洁且高效的博客框架。 Hexo 使用 [Markdown](http://daringfireball.net/projects/markdown/)（或其他标记语言）解析文章，在几秒内，即可利用靓丽的主题生成静态网页。 ## 安装 -安装 Hexo 只需几分钟时间，若您在安装过程中遇到问题或无法找到解决方式，请 [提交问题](https://github.com/hexojs/hexo/issues)，我们会尽力解决您的问题。 +It only takes a few minutes to set up Hexo. If you encounter a problem and can't find the solution here, please [submit a GitHub issue](https://github.com/hexojs/hexo/issues) and we'll help. -### 安装前提 +{% youtube PsXWbI2Mqu0 %} + +### Requirements 安装 Hexo 相当简单，只需要先安装下列应用程序即可： - [Node.js](http://nodejs.org/) (Node.js 版本需不低于 10.13，建议使用 Node.js 12.0 及以上版本) - [Git](http://git-scm.com/) -如果您的电脑中已经安装上述必备程序，那么恭喜您！你可以直接前往 [安装 Hexo](#安装-Hexo) 步骤。 +如果您的电脑中已经安装上述必备程序，那么恭喜您！ 你可以直接前往 [安装 Hexo](#安装-Hexo) 步骤。 如果您的电脑中尚未安装所需要的程序，请根据以下安装指示完成安装。 @@ -33,23 +33,19 @@ Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 [Markdown](h - Linux (Fedora, Red Hat, CentOS)：`sudo yum install git-core` {% note warn Mac 用户 %} -如果在编译时可能会遇到问题，请先到 App Store 安装 Xcode，Xcode 完成后，启动并进入 **Preferences -> Download -> Command Line Tools -> Install** 安装命令行工具。 -{% endnote %} - -{% note info Windows 用户 %} -对于中国大陆地区用户，可以前往 [淘宝 Git for Windows 镜像](https://npmmirror.com/mirrors/git-for-windows/) 下载 git 安装包。 +You may encounter some problems when compiling. Please install Xcode from App Store first. 如果在编译时可能会遇到问题，请先到 App Store 安装 Xcode，Xcode 完成后，启动并进入 **Preferences -> Download -> Command Line Tools -> Install** 安装命令行工具。 {% endnote %} ### 安装 Node.js -Node.js 为大多数平台提供了官方的 [安装程序](https://nodejs.org/zh-cn/download/)。对于中国大陆地区用户，可以前往 [淘宝 Node.js 镜像](https://npmmirror.com/mirrors/node/) 下载。 +Node.js 为大多数平台提供了官方的 [安装程序](https://nodejs.org/zh-cn/download/)。 其它的安装方法： - Windows：通过 [nvs](https://github.com/jasongin/nvs/)（推荐）或者 [nvm](https://github.com/nvm-sh/nvm) 安装。 - Mac：使用 [Homebrew](https://brew.sh/) 或 [MacPorts](http://www.macports.org/) 安装。 - Linux（DEB/RPM-based）：从 [NodeSource](https://github.com/nodesource/distributions) 安装。 -- 其它：使用相应的软件包管理器进行安装，可以参考由 Node.js 提供的 [指导](https://nodejs.org/en/download/package-manager/)。 +- Others: Install it through respective package manager. 其它：使用相应的软件包管理器进行安装，可以参考由 Node.js 提供的 [指导](https://nodejs.org/en/download/package-manager/)。 对于 Mac 和 Linux 同样建议使用 nvs 或者 nvm，以避免可能会出现的权限问题。 @@ -57,8 +53,8 @@ Node.js 为大多数平台提供了官方的 [安装程序](https://nodejs.org/z 使用 Node.js 官方安装程序时，请确保勾选 **Add to PATH** 选项（默认已勾选） {% endnote %} -{% note warn For Mac / Linux 用户 %} -如果在尝试安装 Hexo 的过程中出现 `EACCES` 权限错误，请遵循 [由 npmjs 发布的指导](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) 修复该问题。强烈建议 **不要** 使用 root、sudo 等方法覆盖权限 +{% note info Windows 用户 %} +如果在尝试安装 Hexo 的过程中出现 `EACCES` 权限错误，请遵循 [由 npmjs 发布的指导](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) 修复该问题。 {% endnote %} {% note info Linux %} @@ -90,6 +86,8 @@ $ npm install hexo echo 'PATH="$PATH:./node_modules/.bin"' >> ~/.profile ``` +安装 Hexo 只需几分钟时间，若您在安装过程中遇到问题或无法找到解决方式，请 [提交问题](https://github.com/hexojs/hexo/issues)，我们会尽力解决您的问题。 + ### Node.js 版本限制 如果你坚持使用旧的 Node.js，你可以考虑安装 Hexo 的过去版本。 @@ -98,15 +96,15 @@ echo 'PATH="$PATH:./node_modules/.bin"' >> ~/.profile 我们强烈建议永远安装 [最新版本](https://www.npmjs.com/package/hexo?activeTab=versions) 的 Hexo，以及 [推荐的 Node.js 版本](#安装前提)。 -| Hexo 版本 | 最低版本 (Node.js 版本) | 最高版本 (Node.js 版本) | -| ----------- | ----------------------- | ----------------------- | -| 7.0+ | 14.0.0 | latest | -| 6.2+ | 12.13.0 | latest | -| 6.0+ | 12.13.0 | 18.5.0 | -| 5.0+ | 10.13.0 | 12.0.0 | -| 4.1 - 4.2 | 8.10 | 10.0.0 | -| 4.0 | 8.6 | 8.10.0 | -| 3.3 - 3.9 | 6.9 | 8.0.0 | -| 3.2 - 3.3 | 0.12 | 未知 | -| 3.0 - 3.1 | 0.10 或 iojs | 未知 | -| 0.0.1 - 2.8 | 0.10 | 未知 | +| Hexo 版本 | 最低版本 (Node.js 版本) | 最高版本 (Node.js 版本) | +| ----------- | ----------------- | ----------------- | +| 7.0+ | 14.0.0 | latest | +| 6.2+ | 12.13.0 | latest | +| 6.0+ | 12.13.0 | 18.5.0 | +| 5.0+ | 10.13.0 | 12.0.0 | +| 4.1 - 4.2 | 8.10 | 10.0.0 | +| 4.0 | 8.6 | 8.10.0 | +| 3.3 - 3.9 | 6.9 | 8.0.0 | +| 3.2 - 3.3 | 0.12 | 未知 | +| 3.0 - 3.1 | 0.10 或 iojs | 未知 | +| 0.0.1 - 2.8 | 0.10 | 未知 | diff --git a/source/zh-cn/docs/internationalization.md b/source/zh-cn/docs/internationalization.md index b57a10ced6..a5fd5a498a 100644 --- a/source/zh-cn/docs/internationalization.md +++ b/source/zh-cn/docs/internationalization.md @@ -2,7 +2,7 @@ title: 国际化（i18n） --- -若要让您的网站以不同语言呈现，您可使用国际化（internationalization）功能。请先在 `_config.yml` 中调整 `language` 设定，这代表的是预设语言，您也可设定多个语言来调整预设语言的顺位。 +若要让您的网站以不同语言呈现，您可使用国际化（internationalization）功能。 请先在 `_config.yml` 中调整 `language` 设定，这代表的是预设语言，您也可设定多个语言来调整预设语言的顺位。 You can also set multiple languages and modify the order of default languages. ```yaml language: zh-tw @@ -14,11 +14,11 @@ language: ### 语言文件 -语言文件可以使用 YAML 或 JSON 编写，并放在主题文件夹中的 `languages` 文件夹。您可以在语言文件中使用 [printf 格式](https://github.com/alexei/sprintf.js)。 +Language files can be YAML or JSON files. 语言文件可以使用 YAML 或 JSON 编写，并放在主题文件夹中的 `languages` 文件夹。 您可以在语言文件中使用 [printf 格式](https://github.com/alexei/sprintf.js)。 ### 模板 -在模板中，通过 `__` 或 `_p` 辅助函数，即可取得翻译后的字符串，前者用于一般使用；而后者用于复数字符串。例如： +Use `__` or `_p` helpers in templates to get the translated strings. The former is for normal usage and the latter is for plural strings. For example: ```yaml en.yml index: @@ -46,7 +46,7 @@ index: i18n_dir: :lang ``` -`i18n_dir` 的预设值是 `:lang`，也就是说 Hexo 会捕获网址中的第一段以检测语言，举例来说： +在模板中，通过 `__` 或 `_p` 辅助函数，即可取得翻译后的字符串，前者用于一般使用；而后者用于复数字符串。 例如： ```plain /index.html => en @@ -54,4 +54,4 @@ i18n_dir: :lang /zh-tw/index.html => zh-tw ``` -捕获到的字符串唯有在语言文件存在的情况下，才会被当作是语言，因此例二 `/archives/index.html` 中的 `archives` 就不被当成是语言。 +The string will only be served as a language when the language file exists. 捕获到的字符串唯有在语言文件存在的情况下，才会被当作是语言，因此例二 `/archives/index.html` 中的 `archives` 就不被当成是语言。 diff --git a/source/zh-cn/docs/migration.md b/source/zh-cn/docs/migration.md index 9d03a09300..85b7505ca9 100644 --- a/source/zh-cn/docs/migration.md +++ b/source/zh-cn/docs/migration.md @@ -10,7 +10,7 @@ title: 迁移 $ npm install hexo-migrator-rss --save ``` -插件安装完成后，执行下列命令，从 RSS 迁移所有文章。`source` 可以是文件路径或网址。 +插件安装完成后，执行下列命令，从 RSS 迁移所有文章。 `source` 可以是文件路径或网址。 ```bash $ hexo migrate rss <source> @@ -20,13 +20,17 @@ $ hexo migrate rss <source> 把 `_posts` 文件夹内的所有文件复制到 `source/_posts` 文件夹，并在 `_config.yml` 中修改 `new_post_name` 参数。 +把 Octopress `source/_posts` 文件夹内的所有文件转移到 Hexo 的 `source/_posts` 文件夹，并修改 `_config.yml` 中的 `new_post_name` 参数。 + ```yaml new_post_name: :year-:month-:day-:title.md ``` ## Octopress -把 Octopress `source/_posts` 文件夹内的所有文件转移到 Hexo 的 `source/_posts` 文件夹，并修改 `_config.yml` 中的 `new_post_name` 参数。 +Move all files in the Octopress `source/_posts` folder to `source/_posts` + +Modify the `new_post_name` setting in `_config.yml`: ```yaml new_post_name: :year-:month-:day-:title.md @@ -42,15 +46,13 @@ $ npm install hexo-migrator-wordpress --save 在 WordPress 仪表盘中导出数据("Tools" → "Export" → "WordPress")（详情参考[WP支持页面](https://wordpress.com/zh-cn/support/export/)）。 -插件安装完成后，执行下列命令来迁移所有文章。`source` 可以是 WordPress 导出的文件路径或网址。 +Now run: ```bash $ hexo migrate wordpress <source> ``` -{% note warn 注意 %} -这个插件并不能完美地实现WordPress->Hexo的数据转换，尤其是在处理WordPress的分类方面存在问题（见[Front-matter中的分类与标签](https://hexo.io/zh-cn/docs/front-matter#分类和标签)）。因此，建议您在迁移完成后，手工审阅所有生成的markdown文件，检查其中是否有错误。对于文章数量较大的WordPress站点，这项工作可能要花很长的时间。 -{% endnote %} +`source` 可以是 WordPress 导出的文件路径或网址。 ## Joomla @@ -61,8 +63,11 @@ $ npm install hexo-migrator-joomla --save ``` 使用 [J2XML](http://extensions.joomla.org/extensions/migration-a-conversion/data-import-a-export/12816?qh=YToxOntpOjA7czo1OiJqMnhtbCI7fQ%3D%3D) 组件导出 Joomla 文章。 -插件安装完成后，执行下列命令来迁移所有文章。`source` 可以是 Joomla 导出的文件路径或网址。 + +Now run: ```bash $ hexo migrate joomla <source> ``` + +`source` 可以是 Joomla 导出的文件路径或网址。 diff --git a/source/zh-cn/docs/one-command-deployment.md b/source/zh-cn/docs/one-command-deployment.md index 6467c4fdac..7be97e1395 100644 --- a/source/zh-cn/docs/one-command-deployment.md +++ b/source/zh-cn/docs/one-command-deployment.md @@ -1,23 +1,23 @@ --- -title: 部署 +title: One-Command Deployment --- -{% youtube B0yVJ46CTR8 %} - -Hexo 提供了快速方便的一键部署功能，让您只需一条命令就能将网站部署到服务器上。 +Hexo provides a fast and easy deployment strategy. You only need one single command to deploy your site to your server. ```bash $ hexo deploy ``` -在开始之前，您必须先在 `_config.yml` 中修改参数，一个正确的部署配置中至少要有 `type` 参数，例如： +Install the necessary plugin(s) that is compatible with the deployment method provided by your server/repository. + +Deployment is usually configured through **\_config.yml**. A valid configuration must have the `type` field. For example: ```yaml deploy: type: git ``` -您可同时使用多个 deployer，Hexo 会依照顺序执行每个 deployer。 +您可同时使用多个 deployer，Hexo 会依照顺序执行每个 deployer。 Hexo will execute each deployer in order. ```yaml deploy: @@ -29,19 +29,15 @@ deploy: 关于更多的部署插件，请参考 [插件](https://hexo.io/plugins/) 列表。 -{% note warn 缩进 %} -YAML依靠缩进来确定元素间的从属关系。因此，请确保每个deployer的缩进长度相同，并且使用空格缩进。 -{% endnote %} - ## Git -1. 安装 [hexo-deployer-git]。 +1. 安装 [hexo-deployer-git][]。 ```bash $ npm install hexo-deployer-git --save ``` -2. 修改配置。 +2. Edit **\_config.yml** (with example values shown below as comments): ```yaml deploy: @@ -51,35 +47,23 @@ deploy: message: [message] ``` -| 参数 | 描述 | 默认 | -| --------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| `repo` | 库（Repository）地址 | -| `branch` | 分支名称 | `gh-pages` (GitHub)<br>`coding-pages` (Coding.net)<br>`master` (others) | -| `message` | 自定义提交信息 | `Site updated: {% raw %}{{ now('YYYY-MM-DD HH:mm:ss') }}{% endraw %}`) | -| `token` | 可选的令牌值，用于认证 repo。用 `$` 作为前缀从而从环境变量中读取令牌 | +| Option | 描述 | 默认 | +| --------- | ---------------------------------------- | -------------------------------------------------------------------------------------- | +| `repo` | URL of the target repository | | +| `branch` | 分支名称 | `gh-pages` (GitHub)<br>`coding-pages` (Coding.net)<br>`master` (others) | +| `message` | 自定义提交信息 | `<code>Site updated: {% raw %}{{ now('YYYY-MM-DD HH:mm:ss') }}{% endraw %}`)</code> | +| `token` | 可选的令牌值，用于认证 repo。 用 `$` 作为前缀从而从环境变量中读取令牌 | | -3. 生成站点文件并推送至远程库。执行 `hexo clean && hexo deploy`。 +3. 此外，如果您的 Github Pages 需要使用 CNAME 文件**自定义域名**，请将 CNAME 文件置于 `source` 目录下，只有这样 `hexo deploy` 才能将 CNAME 文件一并推送至部署分支。 - 除非你使用令牌或 SSH 密钥认证，否则你会被提示提供目标仓库的用户名和密码。 -- hexo-deployer-git 并不会存储你的用户名和密码. 请使用 [git-credential-cache](https://git-scm.com/docs/git-credential-cache) 来临时存储它们。 +- hexo-deployer-git 并不会存储你的用户名和密码. 请使用 [git-credential-cache](https://git-scm.com/docs/git-credential-cache) 来临时存储它们。 Use [git-credential-cache](https://git-scm.com/docs/git-credential-cache) to store them temporarily. -4. 登入 Github/BitBucket/Gitlab，请在库设置（Repository Settings）中将默认分支设置为`_config.yml`配置中的分支名称。稍等片刻，您的站点就会显示在您的Github Pages中。 - -### 这一切是如何发生的？ - -当执行 `hexo deploy` 时，Hexo 会将 `public` 目录中的文件和目录推送至 `_config.yml` 中指定的远端仓库和分支中，并且**完全覆盖**该分支下的已有内容。 - -{% note warn For 使用 Git 管理站点目录的用户 %} -由于 Hexo 的部署默认使用分支 `master`，所以如果你同时正在使用 Git 管理你的站点目录，你应当注意你的部署分支应当不同于写作分支。 -一个好的实践是将站点目录和 Pages 分别存放在两个不同的 Git 仓库中，可以有效避免相互覆盖。 -Hexo 在部署你的站点生成的文件时并不会更新你的站点目录。因此你应该手动提交并推送你的写作分支。 -{% endnote %} - -此外，如果您的 Github Pages 需要使用 CNAME 文件**自定义域名**，请将 CNAME 文件置于 `source` 目录下，只有这样 `hexo deploy` 才能将 CNAME 文件一并推送至部署分支。 +4. 登入 Github/BitBucket/Gitlab，请在库设置（Repository Settings）中将默认分支设置为`_config.yml`配置中的分支名称。 稍等片刻，您的站点就会显示在您的Github Pages中。 ## Heroku -安装 [hexo-deployer-heroku]。 +安装 [hexo-deployer-heroku][]。 ```bash $ npm install hexo-deployer-heroku --save @@ -94,16 +78,16 @@ deploy: message: [message] ``` -| 参数 | 描述 | -| --------- | ------------------------------------------------------------------------------------------- | -| `repo` | Heroku 库（Repository）地址 | -| `message` | 自定提交信息 (默认为 `Site updated: {% raw %}{{ now('YYYY-MM-DD HH:mm:ss') }}{% endraw %}`) | +| Option | 描述 | +| -------------------- | ---------------------------------------------------------------------------------- | +| `repo`, `repository` | Heroku 库（Repository）地址 | +| `message` | 自定提交信息 (默认为 `Site updated: {% raw %}{{ now('YYYY-MM-DD HH:mm:ss') }}{% endraw %}`) | ## Netlify -[Netlify](https://www.netlify.com/) 是一个提供网络托管的综合平台。它集持续集成（CI）CDN 自定义域名 HTTPS 持续部署（CD）等诸多功能于一身。您可以通过以下两种方式将Hexo站点部署到Netlify。 +[Netlify](https://www.netlify.com/) provides continuous deployment (Git-triggered builds), an intelligent global CDN, full DNS (including custom domains), automated HTTPS, asset acceleration, and a lot more. It is a unified platform that automates your code to create high-performance, easily maintainable sites and web apps. -首先，也是最通用的方式，就是使用Netlify提供的网页端用户界面。前往[新建一个网站页面](https://app.netlify.com/start)，选择需要关联的 Github/BitBucket/Gitlab 库，然后遵循网站提示。 +There are two different ways to deploy your sites on Netlify. 首先，也是最通用的方式，就是使用Netlify提供的网页端用户界面。 前往[新建一个网站页面](https://app.netlify.com/start)，选择需要关联的 Github/BitBucket/Gitlab 库，然后遵循网站提示。 另一种方式是使用Netlify提供的命令行客户端工具 [Node based CLI](https://www.netlify.com/docs/cli/) 管理和部署您的站点。 @@ -111,7 +95,7 @@ deploy: ## Rsync -安装 [hexo-deployer-rsync]。 +安装 [hexo-deployer-rsync][]。 ```bash $ npm install hexo-deployer-rsync --save @@ -131,19 +115,15 @@ deploy: ignore_errors: [true|false] ``` -| 参数 | 描述 | 默认值 | -| --------------- | ---------------------- | ------ | -| `host` | 远程主机的地址 | -| `user` | 使用者名称 | -| `root` | 远程主机的根目录 | -| `port` | 端口 | 22 | -| `delete` | 删除远程主机上的旧文件 | true | -| `verbose` | 显示调试信息 | true | -| `ignore_errors` | 忽略错误 | false | - -{% note info rsync部署模块的工作方式 %} -需要注意的是，要求您提供的实际上是一个能通过SSH登陆远程主机的Linux用户。Hexo会自动处理关于rsync使用的一切操作。因此，您需要在远程主机上为您的Hexo站点建立一个用户，并允许其通过SSH登陆。不过，这里的`port`，的确是指rsync监听的端口，请确保防火墙打开了该端口。 -{% endnote %} +| Option | 描述 | 默认值 | +| --------------- | ----------- | ----- | +| `host` | 远程主机的地址 | | +| `user` | 使用者名称 | | +| `root` | 远程主机的根目录 | | +| `port` | 端口 | 22 | +| `delete` | 删除远程主机上的旧文件 | true | +| `verbose` | 显示调试信息 | true | +| `ignore_errors` | 忽略错误 | false | ## OpenShift @@ -151,7 +131,7 @@ deploy: `hexo-deployer-openshift` 已于2022年被弃用。 {% endnote %} -安装 [hexo-deployer-openshift]。 +安装 [hexo-deployer-openshift][]。 ```bash $ npm install hexo-deployer-openshift --save @@ -166,14 +146,14 @@ deploy: message: [message] ``` -| 参数 | 描述 | -| --------- | ------------------------------------------------------------------------------------------- | -| `repo` | OpenShift 库（Repository）地址 | +| Option | 描述 | +| --------- | ---------------------------------------------------------------------------------- | +| `repo` | OpenShift 库（Repository）地址 | | `message` | 自定提交信息 (默认为 `Site updated: {% raw %}{{ now('YYYY-MM-DD HH:mm:ss') }}{% endraw %}`) | ## FTPSync -安装 [hexo-deployer-ftpsync]。 +安装 [hexo-deployer-ftpsync][]。 ```bash $ npm install hexo-deployer-ftpsync --save @@ -193,25 +173,19 @@ deploy: verbose: [true|false] ``` -| 参数 | 描述 | 默认值 | -| ------------- | ---------------------------------------------- | ------ | -| `host` | 远程主机的地址 | -| `user` | 使用者名称 | -| `pass` | 密码 | -| `remote` | 远程主机的根目录 | `/` | -| `port` | 端口 | 21 | -| `clear` | 在上传前移除远程主机的根目录下所有的文件和目录 | false | -| `ignore` | 忽略的文件或目录 | -| `connections` | 使用的连接数 | 1 | -| `verbose` | 显示调试信息 | false | - -{% note warn FTP部署可能出现的问题 %} -您可能需要预先通过其他方式将所有文件上传到远程主机中。否则初次使用ftpsync插件就可能出现报错。另外，由于FTP协议的特征，它每传送一个文件就需要一次握手，相对速度较慢。 -{% endnote %} +| Option | 描述 | 默认值 | +| --------- | ----------------------- | ----- | +| `host` | 远程主机的地址 | | +| `user` | 使用者名称 | | +| `pass` | 密码 | | +| `remote` | 远程主机的根目录 | `/` | +| `port` | 端口 | 21 | +| `clear` | 在上传前移除远程主机的根目录下所有的文件和目录 | false | +| `verbose` | 显示调试信息 | false | ## SFTP -安装 [hexo-deployer-sftp]。 +安装 [hexo-deployer-sftp][]。 Deploys the site via SFTP, allowing for passwordless connections using ssh-agent. ```bash $ npm install hexo-deployer-sftp --save @@ -232,20 +206,22 @@ deploy: agent: [path/to/agent/socket] ``` -| 参数 | 描述 | 默认值 | -| ------------ | --------------------------- | ---------------- | -| `host` | 远程主机的地址 | -| `user` | 使用者名称 | -| `pass` | 密码 | -| `remotePath` | 远程主机的根目录 | `/` | -| `port` | 端口 | 22 | -| `privateKey` | ssh私钥的目录地址 | -| `passphrase` | （可省略）ssh私钥的密码短语 | -| `agent` | ssh套接字的目录地址 | `$SSH_AUTH_SOCK` | +| Option | 描述 | 默认值 | +| ------------- | ----------------------------------------------- | ---------------- | +| `host` | 远程主机的地址 | | +| `port` | 端口 | 22 | +| `user` | 使用者名称 | | +| `pass` | 密码 | | +| `privateKey` | ssh私钥的目录地址 | | +| `passphrase` | Optional passphrase for the private key | | +| `agent` | ssh套接字的目录地址 | `$SSH_AUTH_SOCK` | +| `remotePath` | 远程主机的根目录 | `/` | +| `forceUpload` | Override existing files | false | +| `concurrency` | Max number of SFTP tasks processed concurrently | 100 | ## Vercel -[Vercel](https://vercel.com) 是一个云平台，使开发人员能够托管 Jamstack 网站和网络服务，这些网站和服务可即时部署，自动扩展，无需监督，零配置。他们提供全球边缘网络、SSL 加密、资源压缩、缓存失效等服务。 +[Vercel](https://vercel.com) 是一个云平台，使开发人员能够托管 Jamstack 网站和网络服务，这些网站和服务可即时部署，自动扩展，无需监督，零配置。 他们提供全球边缘网络、SSL 加密、资源压缩、缓存失效等服务。 步骤 1: 在你的 `package.json` 文件中添加一个构建脚本： @@ -261,19 +237,19 @@ deploy: 要通过 [Git整合Vercel](https://vercel.com/docs/git-integrations) 部署 Hexo 应用程序，请确保它已被推送到 Git 仓库。 -使用 [导入流](https://vercel.com/import/git) 将该项目导入 Vercel。在导入过程中，你会发现所有相关的选项都是预先配置好的；但是，你可以选择改变其中的任何选项，这些选项的清单可以在 [这里](https://vercel.com/docs/build-step#build-&-development-settings) 找到。 +使用 [导入流](https://vercel.com/import/git) 将该项目导入 Vercel。 在导入过程中，你会发现所有相关的选项都是预先配置好的；但是，你可以选择改变其中的任何选项，这些选项的清单可以在 [这里](https://vercel.com/docs/build-step#build-&-development-settings) 找到。 在你的项目被导入后，所有后续推送到分支的内容都会产生 [预览部署](https://vercel.com/docs/platform/deployments#preview) ，而对 [生产分支](https://vercel.com/docs/git-integrations#production-branch)（通常是“主分支”）所做的所有更改都会导致 [生产部署](https://vercel.com/docs/platform/deployments#production)。 -此外，你也可以点击下面的部署按钮来创建一个新的项目： +或者，您可以单击下面的部署按钮创建新项目： [![部署Vercel](https://vercel.com/button)](https://vercel.com/new/hexo) ## Bip -[Bip](https://bip.sh) 是一项商业托管服务，为静态网站提供零停机部署、全球 CDN、SSL、无限带宽等。计划以以每个域为基础，随用随付的方式提供。 +[Bip](https://bip.sh) 是一项商业托管服务，为静态网站提供零停机部署、全球 CDN、SSL、无限带宽等。 计划以以每个域为基础，随用随付的方式提供。 -由于 Bip 为 Hexo 提供了开箱即用的支持，因此开始使用是很容易的。本指南假定你已经有 [一个Bip域和已经安装Bip CLI](https://bip.sh/getstarted)。 +由于 Bip 为 Hexo 提供了开箱即用的支持，因此开始使用是很容易的。 本指南假定你已经有 [一个Bip域和已经安装Bip CLI](https://bip.sh/getstarted)。 1: 初始化你的项目目录 @@ -281,7 +257,7 @@ deploy: $ bip init ``` -按照提示，你会被提问到你想部署到哪个域。Bip 会检测到你正在使用 Hexo ，并自动设置项目设置，如源文件目录。 +按照提示，你会被提问到你想部署到哪个域。 Bip 会检测到你正在使用 Hexo ，并自动设置项目设置，如源文件目录。 2: 部署你的网站 @@ -299,7 +275,7 @@ $ hexo generate —deploy && bip deploy [RSS3](https://rss3.io) 是一个为 Web 3.0 时代的内容和社交网络设计的开放协议。 -1. 安装 [hexo-deployer-rss3] +1. 安装 [hexo-deployer-rss3][] 2. 修改配置。 @@ -316,14 +292,14 @@ deploy: # 所有部署器的根配置块 secret: ee8b74626f12b61c1a4bde3b8c331ad390567c86ba779c9b18561ee92c1cbff0 ``` -| 参数 | 描述 | -| ----------------- | ----------------------- | -| `endpoint` | 一个 RSS3 Hub 的链接 | -| `privateKey` | 您的私钥， 64 字节 | -| `ipfs/deploy` | 是否部署到 IPFS 上 | -| `ipfs/gateway` | IPFS API 网关 | -| `ipfs/api/key` | IPFS 网关相关的验证内容 | -| `ipfs/api/secret` | IPFS 网关相关的验证内容 | +| 参数 | 描述 | +| ----------------- | --------------- | +| `endpoint` | 一个 RSS3 Hub 的链接 | +| `privateKey` | 您的私钥， 64 字节 | +| `ipfs/deploy` | 是否部署到 IPFS 上 | +| `ipfs/gateway` | IPFS API 网关 | +| `ipfs/api/key` | IPFS 网关相关的验证内容 | +| `ipfs/api/secret` | IPFS 网关相关的验证内容 | 3. 生成静态文件 @@ -353,13 +329,13 @@ edgio init --connector=@edgio/hexo edgio deploy ``` -或者，您可以单击下面的部署按钮创建新项目： +此外，你也可以点击下面的部署按钮来创建一个新的项目： [![Deploy To Edgio](https://docs.edg.io/button.svg)](https://app.layer0.co/deploy?repo=https%3A%2F%2Fgithub.com%2Fedgio-docs%2Fedgio-hexo-example) ## 其他方法 -Hexo 生成的所有文件都放在 `public` 文件夹中，您可以将它们复制到您喜欢的地方。 +Hexo 生成的所有文件都放在 `public` 文件夹中，您可以将它们复制到您喜欢的地方。 You can copy them to wherever you like. [hexo-deployer-git]: https://github.com/hexojs/hexo-deployer-git [hexo-deployer-heroku]: https://github.com/hexojs/hexo-deployer-heroku diff --git a/source/zh-cn/docs/permalinks.md b/source/zh-cn/docs/permalinks.md index 83f67eecd6..3e8bf4c57a 100644 --- a/source/zh-cn/docs/permalinks.md +++ b/source/zh-cn/docs/permalinks.md @@ -8,22 +8,22 @@ title: 永久链接（Permalinks） 除了下列变量外，您还可使用除了 `:path` 和 `:permalink` 之外 Front-matter 中的所有属性。 -| 变量 | 描述 | -| ------------- | ---------------------------------------------------------------- | -| `:year` | 文章的发表年份（4 位数） | -| `:month` | 文章的发表月份（2 位数） | -| `:i_month` | 文章的发表月份（不含前导零） | -| `:day` | 文章的发表日期 (2 位数) | -| `:i_day` | 文章的发表日期（不含前导零） | -| `:hour` | 文章发表时的小时 (2 位数) | -| `:minute` | 文章发表时的分钟 (2 位数) | -| `:second` | 文章发表时的秒钟 (2 位数) | -| `:title` | 文件名称 (相对于 "source/\_posts/" 文件夹) | -| `:name` | 文件名称 | -| `:post_title` | 文章标题 | +| 变量 | 描述 | +| ------------- | --------------------------------------------------- | +| `:year` | 文章的发表年份（4 位数） | +| `:month` | 文章的发表月份（2 位数） | +| `:i_month` | 文章的发表月份（不含前导零） | +| `:day` | 文章的发表日期 (2 位数) | +| `:i_day` | 文章的发表日期（不含前导零） | +| `:hour` | 文章发表时的小时 (2 位数) | +| `:minute` | 文章发表时的分钟 (2 位数) | +| `:second` | 文章发表时的秒钟 (2 位数) | +| `:title` | 文件名称 (相对于 "source/\_posts/" 文件夹) | +| `:name` | 文件名称 | +| `:post_title` | 文章标题 | | `:id` | 文章 ID (_[清除缓存](/zh-cn/docs/commands#clean)时不具有持久性_) | -| `:category` | 分类。如果文章没有分类，则是 `default_category` 配置信息。 | -| `:hash` | 文件名（与 `:title` 相同）和日期的 SHA1 哈希值（12位16进制数） | +| `:category` | 分类。 如果文章没有分类，则是 `default_category` 配置信息。 | +| `:hash` | 文件名（与 `:title` 相同）和日期的 SHA1 哈希值（12位16进制数） | 您可在 `permalink_defaults` 参数下调整永久链接中各变量的默认值： @@ -42,7 +42,7 @@ categories: - bar ``` -| 参数 | 结果 | +| Setting | 结果 | | ------------------------------- | --------------------------- | | `:year/:month/:day/:title/` | 2013/07/14/hello-world/ | | `:year-:month-:day-:title.html` | 2013-07-14-hello-world.html | @@ -57,7 +57,7 @@ categories: - bar ``` -| 参数 | 结果 | +| Setting | 结果 | | --------------------------- | ----------------------------- | | `:year/:month/:day/:title/` | 2013/07/14/lorem/hello-world/ | | `:year/:month/:day/:name/` | 2013/07/14/hello-world/ | diff --git a/source/zh-cn/docs/plugins.md b/source/zh-cn/docs/plugins.md index 745321ddc1..aa23dbacbc 100644 --- a/source/zh-cn/docs/plugins.md +++ b/source/zh-cn/docs/plugins.md @@ -2,25 +2,26 @@ title: 插件 --- -Hexo 有强大的插件系统，使您能轻松扩展功能而不用修改核心模块的源码。在 Hexo 中有两种形式的插件： +Hexo 有强大的插件系统，使您能轻松扩展功能而不用修改核心模块的源码。 在 Hexo 中有两种形式的插件： ### 脚本（Scripts） -如果您的代码很简单，建议您编写脚本，您只需要把 JavaScript 文件放到 `scripts` 文件夹，在启动时就会自动加载。 +如果您的代码较复杂，或是您想要发布到 NPM 上，建议您编写插件。 首先，在 `node_modules` 文件夹中建立文件夹，文件夹名称开头必须为 `hexo-`，如此一来 Hexo 才会在启动时加载；否则 Hexo 将会忽略它。 ### 插件（Packages） -如果您的代码较复杂，或是您想要发布到 NPM 上，建议您编写插件。首先，在 `node_modules` 文件夹中建立文件夹，文件夹名称开头必须为 `hexo-`，如此一来 Hexo 才会在启动时加载；否则 Hexo 将会忽略它。 +If your code is complicated or if you want to publish it to the NPM registry, we recommend using a plugin. First, create a folder in the `node_modules` folder. The name of this folder must begin with `hexo-` or Hexo will ignore it. 文件夹内至少要包含 2 个文件：一个是主程序，另一个是 `package.json`，描述插件的用途和所依赖的插件。 ```plain . +. ├── index.js └── package.json ``` -`package.json` 中至少要包含 `name`, `version`, `main` 属性，例如： +编辑 `source/_data/plugins/<your-plugin-name>.yml` 并添加您的插件。 例如： ```json package.json { @@ -30,20 +31,22 @@ Hexo 有强大的插件系统，使您能轻松扩展功能而不用修改核心 } ``` +You'll also need to list your plugin as a dependency in the root `package.json` of your hexo instance in order for Hexo to detect and load it. + ### 工具 您可以使用 Hexo 提供的官方工具插件来加速开发： -- [hexo-fs]：文件 IO -- [hexo-util]：工具程式 -- [hexo-i18n]：本地化（i18n） -- [hexo-pagination]：生成分页数据 +- [hexo-fs][]：文件 IO +- [hexo-util][]：工具程式 +- [hexo-i18n][]：本地化（i18n） +- [hexo-pagination][]：生成分页数据 ### 发布 -当您完成插件后，可以考虑将它发布到 [插件列表](/plugins)，让更多人能够使用您的插件。发布插件的步骤和 [更新文档](contributing.html#更新文档) 非常类似。 +当您完成插件后，可以考虑将它发布到 [插件列表](/plugins)，让更多人能够使用您的插件。 发布插件的步骤和 [更新文档](contributing.html#更新文档) 非常类似。 -1. Fork [hexojs/site] +1. Fork [hexojs/site][] 2. 把库（repository）复制到电脑上，并安装所依赖的插件。 ```shell @@ -54,10 +57,11 @@ Hexo 有强大的插件系统，使您能轻松扩展功能而不用修改核心 3. 在 `source/_data/plugins/` 中创建一个新的 yaml 文件，使用您的插件名称作为文件名。 -4. 编辑 `source/_data/plugins/<your-plugin-name>.yml` 并添加您的插件。例如： +4. Edit `source/_data/plugins/<your-plugin-name>.yml` and add your plugin. For example: ```yaml description: Server module for Hexo. + description: Server module for Hexo. link: https://github.com/hexojs/hexo-server tags: - official diff --git a/source/zh-cn/docs/server.md b/source/zh-cn/docs/server.md index 4c3bd16de6..9af2a1346e 100644 --- a/source/zh-cn/docs/server.md +++ b/source/zh-cn/docs/server.md @@ -2,15 +2,15 @@ title: 服务器 --- -## [hexo-server] +## [hexo-server][] -Hexo 3.0 把服务器独立成了个别模块，您必须先安装 [hexo-server] 才能使用。 +With the release of Hexo 3, the server has been separated from the main module. Hexo 3.0 把服务器独立成了个别模块，您必须先安装 [hexo-server][] 才能使用。 ```bash $ npm install hexo-server --save ``` -安装完成后，输入以下命令以启动服务器，您的网站会在 `http://localhost:4000` 下启动。在服务器启动期间，Hexo 会监视文件变动并自动更新，您无须重启服务器。 +Once the server has been installed, run the following command to start the server. 安装完成后，输入以下命令以启动服务器，您的网站会在 `http://localhost:4000` 下启动。 在服务器启动期间，Hexo 会监视文件变动并自动更新，您无须重启服务器。 ```bash $ hexo server @@ -24,7 +24,7 @@ $ hexo server -p 5000 ### 静态模式 -在静态模式下，服务器只处理 `public` 文件夹内的文件，而不会处理文件变动，在执行时，您应该先自行执行 `hexo generate`，此模式通常用于生产环境（production mode）下。 +In static mode, only files in the `public` folder will be served and file watching is disabled. You have to run `hexo generate` before starting the server. Usually used in production. ```bash $ hexo server -s @@ -32,16 +32,10 @@ $ hexo server -s ### 自定义 IP -服务器默认运行在 `0.0.0.0`，您可以覆盖默认的 IP 设置，如下： +服务器默认运行在 `0.0.0.0`，您可以覆盖默认的 IP 设置，如下： You can override the default IP setting. ```bash $ hexo server -i 192.168.1.1 ``` -指定这个参数后，您就只能通过该IP才能访问站点。例如，对于一台使用无线网络的笔记本电脑，除了指向本机的`127.0.0.1`外，通常还有一个`192.168.*.*`的局域网IP，如果像上面那样使用`-i`参数，就不能用`127.0.0.1`来访问站点了。对于有公网IP的主机，如果您指定一个局域网IP作为`-i`参数的值，那么就无法通过公网来访问站点。 - [hexo-server]: https://github.com/hexojs/hexo-server -[Connect]: https://github.com/senchalabs/connect -[morgan]: https://github.com/expressjs/morgan -[Forever]: https://github.com/nodejitsu/forever -[PM2]: https://github.com/Unitech/pm2 diff --git a/source/zh-cn/docs/setup.md b/source/zh-cn/docs/setup.md index 161855c23a..edfa913366 100644 --- a/source/zh-cn/docs/setup.md +++ b/source/zh-cn/docs/setup.md @@ -1,5 +1,5 @@ --- -title: 建站 +title: Setup --- {% youtube xvIRGmKWpFM %} @@ -12,10 +12,11 @@ $ cd <folder> $ npm install ``` -新建完成后，指定文件夹的目录如下： +Once initialized, here's what your project folder will look like: ```plain . +. ├── _config.yml ├── package.json ├── scaffolds @@ -27,11 +28,11 @@ $ npm install ### \_config.yml -网站的 [配置](configuration.html) 信息，您可以在此配置大部分的参数。 +网站的 [配置](configuration.html) 信息，您可以在此配置大部分的参数。 You can configure most settings here. ### package.json -应用程序的信息。[EJS](https://ejs.co/), [Stylus](http://learnboost.github.io/stylus/) 和 [Markdown](http://daringfireball.net/projects/markdown/) 渲染引擎 已默认安装，您可以自由移除。 +应用程序的信息。 [EJS](https://ejs.co/), [Stylus](http://learnboost.github.io/stylus/) 和 [Markdown](http://daringfireball.net/projects/markdown/) 渲染引擎 已默认安装，您可以自由移除。 If you want, you can uninstall them later. ```json package.json { @@ -58,14 +59,12 @@ $ npm install ### scaffolds -[模版](writing#模版（Scaffold）) 文件夹。当您新建文章时，Hexo 会根据 scaffold 来创建文件。 - -Hexo 的模板是指在新建的文章文件中默认填充的内容。例如，如果您修改 `scaffold/post.md` 中的 Front-matter 内容，那么每次新建一篇文章时都会包含这个修改。 +[模版](writing#模版（Scaffold）) 文件夹。 当您新建文章时，Hexo 会根据 scaffold 来创建文件。 ### source -资源文件夹是存放用户资源的地方。除 `_posts` 文件夹之外，开头命名为 `_` (下划线)的文件 / 文件夹和隐藏的文件将会被忽略。Markdown 和 HTML 文件会被解析并放到 `public` 文件夹，而其他文件会被拷贝过去。 +资源文件夹是存放用户资源的地方。 This is where you put your site's content. 除 `_posts` 文件夹之外，开头命名为 `_` (下划线)的文件 / 文件夹和隐藏的文件将会被忽略。 Markdown 和 HTML 文件会被解析并放到 `public` 文件夹，而其他文件会被拷贝过去。 ### themes -[主题](themes.html) 文件夹。Hexo 会根据主题来生成静态页面。 +[主题](themes.html) 文件夹。 Hexo 会根据主题来生成静态页面。 diff --git a/source/zh-cn/docs/syntax-highlight.md b/source/zh-cn/docs/syntax-highlight.md index 157cc41df6..b2ae7931b5 100644 --- a/source/zh-cn/docs/syntax-highlight.md +++ b/source/zh-cn/docs/syntax-highlight.md @@ -1,8 +1,8 @@ --- -title: 代码高亮 +title: Syntax Highlighting --- -Hexo 对 [highlight.js](https://github.com/highlightjs/highlight.js) 与 [prismjs](https://github.com/PrismJS/prism) 两种代码高亮库提供内建支持。本篇教程将展示如何将 Hexo 的内建语法高亮组件整合至你的模板中。 +Hexo 对 [highlight.js](https://github.com/highlightjs/highlight.js) 与 [prismjs](https://github.com/PrismJS/prism) 两种代码高亮库提供内建支持。 本篇教程将展示如何将 Hexo 的内建语法高亮组件整合至你的模板中。 ## 如何在文章中插入代码块 @@ -21,13 +21,9 @@ code snippet code snippet ``` ```` - -上面的第三种是 Markdown 的 fenced code block 语法。Hexo 对其进行了扩展，使其支持更多特性。在[标签插件文档](tag-plugins#代码块)中你可以找到可用的选项。 - -> 提示：Hexo 支持用任何格式书写文章，只需安装相应渲染插件即可。不论文章以何种格式书写（Markdown、EJS、Swig、Nunjuck、Pug、ASCIIDoc），上述三种代码块语法总是可用。 - +上面的第三种是 Markdown 的 fenced code block 语法。 Hexo 对其进行了扩展，使其支持更多特性。 在[标签插件文档](tag-plugins#代码块)中你可以找到可用的选项。 +> 提示：Hexo 支持用任何格式书写文章，只需安装相应渲染插件即可。 It can be in markdown, ejs, swig, nunjucks, pug, asciidoc, etc. Regardless of the format used, those three code block syntax will always be available. ## 配置 - v7.0.0以下： ```yaml @@ -92,7 +88,7 @@ v7.0.0及以上： syntax_highlighter: # empty ``` -当 `highlight.enable` 和 `prismjs.enable` 均为 `false` （v7.0.0以下）或 `syntax_highlighter` 为空（v7.0.0及以上）时，代码块输出的 HTML 由相应的渲染器控制。举个例子：[`marked.js`](https://github.com/markedjs/marked)（Hexo 的默认 Markdown 渲染器 [`hexo-renderer-marked`](https://github.com/hexojs/hexo-renderer-marked) 由此驱动）会把语言加入 `<code>` 标签的 `class` 中： +当 `highlight.enable` 和 `prismjs.enable` 均为 `false` （v7.0.0以下）或 `syntax_highlighter` 为空（v7.0.0及以上）时，代码块输出的 HTML 由相应的渲染器控制。 举个例子：[`marked.js`](https://github.com/markedjs/marked)（Hexo 的默认 Markdown 渲染器 [`hexo-renderer-marked`](https://github.com/hexojs/hexo-renderer-marked) 由此驱动）会把语言加入 `<code>` 标签的 `class` 中： ````markdown ```yaml @@ -144,7 +140,7 @@ highlight: hljs: false ``` -`highlight.js` 默认开启，用作 Hexo 的服务端高亮组件。如果你需要在浏览器端运行 `highlight.js`，请把它关闭。 +`highlight.js` 默认开启，用作 Hexo 的服务端高亮组件。 如果你需要在浏览器端运行 `highlight.js`，请把它关闭。 > 「服务端高亮」指语法高亮在 `hexo generate` 或 `hexo server` 时完成。 @@ -154,7 +150,7 @@ highlight: > 提示：如果你想使用「子语言高亮」功能（例如在高亮 HTML 时同时高亮内部嵌入的 JavaScript 代码），请开启 `auto_detect`，并且在文章中插入代码块时不要标注语言。 -{% note warn "警告！" %} +{% note warn "警告！" %} %} `auto_detect` 十分耗费资源。 如果你不需要使用「子语言高亮」功能，或者不介意在书写代码块时标记语言，请不要启用此功能。 {% endnote %} @@ -181,17 +177,17 @@ Hexo 通过用 `<figure>` 和 `<table>` 包裹其代码块为其添加了行号 </figure> ``` -这不是 `highlight.js` 的行为，因此需要为 `<figure>` 和 `<table>` 添加自定义 CSS 代码。部分主题对此提供内建支持。 +这不是 `highlight.js` 的行为，因此需要为 `<figure>` 和 `<table>` 添加自定义 CSS 代码。 部分主题对此提供内建支持。 -你大概也注意到了，所有代码块的 `class` 都没有 `hljs-` 前缀。我们 [为此专门准备了一个章节](#hljs)。 +你大概也注意到了，所有代码块的 `class` 都没有 `hljs-` 前缀。 我们 [为此专门准备了一个章节](#hljs)。 ### line_threshold (+6.1.0) -接受一个可选的阈值，只有代码块的行数超过这个阈值才显示行数。默认值为 `0`。 +接受一个可选的阈值，只有代码块的行数超过这个阈值才显示行数。 默认值为 `0`。 ### tab_replace -用代码内的 tab (`\t`) 替换为给定值，默认值是两个空格。 +Replace tabs inside code block with given string. By default it is 2 spaces. ### exclude_languages (+6.1.0) @@ -199,7 +195,7 @@ Hexo 通过用 `<figure>` 和 `<table>` 包裹其代码块为其添加了行号 ### wrap -为了支持行号显示，Hexo 将输出包裹在了 `<figure>` 和 `<table>` 内部。如果要保持 `highlight.js` 原来的行为，你需要将 `line_number` 和 `wrap` **全部**关闭。 +为了支持行号显示，Hexo 将输出包裹在了 `<figure>` 和 `<table>` 内部。 如果要保持 `highlight.js` 原来的行为，你需要将 `line_number` 和 `wrap` **全部**关闭。 ```html <pre><code class="yaml"> @@ -208,8 +204,8 @@ Hexo 通过用 `<figure>` 和 `<table>` 包裹其代码块为其添加了行号 </code></pre> ``` -{% note warn "警告！" %} -因为 `line_number` 功能依赖 `wrap`，你无法在配置中关闭 `wrap` 而又开启 `line_number`。如果你将 `line_number` 设置为 `true` 的话，`wrap` 将被自动开启。 +{% note warn "警告！" %} %} +Because `line_number` feature relies on `wrap`, you can't disable `wrap` with `line_number` enabled: If you set `line_number` to `true`, `wrap` will be automatically enabled. {% endnote %} ### hljs @@ -253,37 +249,37 @@ prismjs: tab_replace: "" ``` -PrismJS 默认禁用。启用 PrismJS 前应设置 `highlight.enable` 为 `false`（v7.0.0以下）或设置 `syntax_highlighter` 为 `prismjs`（v7.0.0及以上）。 +PrismJS 默认禁用。 启用 PrismJS 前应设置 `highlight.enable` 为 `false`（v7.0.0以下）或设置 `syntax_highlighter` 为 `prismjs`（v7.0.0及以上）。 ### preprocess Hexo 内建的 PrismJS 支持浏览器端高亮（`preprocess` 设置为 `false`）和服务器端高亮（`preprocess` 设置为 `true`）两种方式。 -使用服务器端高亮时（`preprocess` 设置为 `true`），只需要在站点引入 Prismjs 的主题（CSS 样式表）即可；而使用浏览器端高亮时（`preprocess` 设置为 `false`），需要将 JavaScript 文件也引入。 +当 `preprocess` 与 `line_number` 均设置为 `true` 时，只需要引入 `prism-line-numbers.css` 即可启用行号显示。 如果 `preprocess` 和 `line_number` 均被关闭，则需要将 `prism-line-numbers.css` 和 `prism-line-numbers.js` 都引入才能启用行号显示。 -PrismJS 主要是面向浏览器的。因此，在服务器端高亮模式下只有部分插件可用： +`preprocess` 设置为 `false` 时所有 PrismJS 插件均可用，只需额外注意以下几点： -- [行号显示](https://prismjs.com/plugins/line-numbers/)：需要引入`prism-line-numbers.css`，无需引入`prism-line-numbers.js`。Hexo 将生成其所需的 HTML 代码片段。 +- [行号显示](https://prismjs.com/plugins/line-numbers/)：需要引入`prism-line-numbers.css`，无需引入`prism-line-numbers.js`。 Hexo 将生成其所需的 HTML 代码片段。 - [语言显示](https://prismjs.com/plugins/show-language/)：当代码块有标注语言时，Hexo 总会添加 `data-language` 属性。 - Hexo 也支持其它不需要特殊 HTML 代码格式的 PrismJS 插件，不过你需要引入它们的 JavaScript 文件。 -`preprocess` 设置为 `false` 时所有 PrismJS 插件均可用，只需额外注意以下几点： +All prism plugins are supported if `preprocess` is set to `false`. Here are a few things you should still pay attention to: -- [行号显示](https://prismjs.com/plugins/line-numbers/)：当 `preprocess` 设置为 `false` 时，Hexo 不会生成插件所需的 HTML 代码格式。`prism-line-numbers.css` 和 `prism-line-numbers.js`均需被引入。 +- [行号显示](https://prismjs.com/plugins/line-numbers/)：当 `preprocess` 设置为 `false` 时，Hexo 不会生成插件所需的 HTML 代码格式。 `prism-line-numbers.css` 和 `prism-line-numbers.js`均需被引入。 - [语言显示](https://prismjs.com/plugins/show-language/)：当代码块有标注语言时，Hexo 总会添加 `data-language` 属性。 -- [高亮特定行](https://prismjs.com/plugins/line-highlight/): Hexo 的[代码块标签插件](tag-plugins#代码块)和[反引号代码块标签插件](tag-plugins#反引号代码块)都支持高亮特定行的语法（即 `mark` 选项）。当 `mark` 项被设置时，Hexo 将生成其所需的 HTML 代码格式。 +- [高亮特定行](https://prismjs.com/plugins/line-highlight/): Hexo 的[代码块标签插件](tag-plugins#代码块)和[反引号代码块标签插件](tag-plugins#反引号代码块)都支持高亮特定行的语法（即 `mark` 选项）。 当 `mark` 项被设置时，Hexo 将生成其所需的 HTML 代码格式。 ### line_number -当 `preprocess` 与 `line_number` 均设置为 `true` 时，只需要引入 `prism-line-numbers.css` 即可启用行号显示。如果 `preprocess` 和 `line_number` 均被关闭，则需要将 `prism-line-numbers.css` 和 `prism-line-numbers.js` 都引入才能启用行号显示。 +因为 `line_number` 功能依赖 `wrap`，你无法在配置中关闭 `wrap` 而又开启 `line_number`。 如果你将 `line_number` 设置为 `true` 的话，`wrap` 将被自动开启。 ### line_threshold (+6.1.0) -接受一个可选的阈值，只有代码块的行数超过这个阈值才显示行数。默认值为 `0`。 +接受一个可选的阈值，只有代码块的行数超过这个阈值才显示行数。 默认值为 `0`。 ### tab_replace -用代码内的 tab (`\t`) 替换为给定值，默认值是两个空格。 +Replace `\t` inside code block with given string. By default it is 2 spaces. ## 其它参考资料 diff --git a/source/zh-cn/docs/tag-plugins.md b/source/zh-cn/docs/tag-plugins.md index 437d145dff..88f8d587b7 100644 --- a/source/zh-cn/docs/tag-plugins.md +++ b/source/zh-cn/docs/tag-plugins.md @@ -2,15 +2,17 @@ title: 标签插件（Tag Plugins） --- -标签插件和 Front-matter 中的标签不同，它们是用于在文章中快速插入特定内容的插件。 +标签插件和 Front-matter 中的标签不同，它们是用于在文章中快速插入特定内容的插件。 They are ported from Octopress and provide a useful way for you to quickly add specific content to your posts. 虽然你可以使用任何格式书写你的文章，但是标签插件永远可用，且语法也都是一致的。 +{% youtube I07XMi7MHd4 %} + _标签插件不应该被包裹在 Markdown 语法中，例如： `[]({% post_path lorem-ipsum %})` 是不被支持的。_ ## 引用块 -在文章中插入引言，可包含作者、来源和标题。 +Perfect for adding quotes to your post, with optional author, source and title information. **别号：** quote @@ -22,7 +24,7 @@ content ### 示例 -**没有提供参数，则只输出普通的 blockquote** +**No arguments. Plain blockquote.** ``` {% blockquote %} @@ -39,11 +41,12 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque hendrerit ``` {% blockquote David Levithan, Wide Awake %} Do not just seek happiness for yourself. Seek happiness for all. Through kindness. Through mercy. +{% endblockquote %} Seek happiness for all. Through kindness. Through mercy. {% endblockquote %} ``` {% blockquote David Levithan, Wide Awake %} -Do not just seek happiness for yourself. Seek happiness for all. Through kindness. Through mercy. +Do not just seek happiness for yourself. Seek happiness for all. Through kindness. Through mercy. Seek happiness for all. Through kindness. Through mercy. {% endblockquote %} **引用 Twitter** @@ -51,11 +54,12 @@ Do not just seek happiness for yourself. Seek happiness for all. Through kindnes ``` {% blockquote @DevDocs https://twitter.com/devdocs/status/356095192085962752 %} NEW: DevDocs now comes with syntax highlighting. http://devdocs.io +{% endblockquote %} http://devdocs.io {% endblockquote %} ``` {% blockquote @DevDocs https://twitter.com/devdocs/status/356095192085962752 %} -NEW: DevDocs now comes with syntax highlighting. http://devdocs.io +NEW: DevDocs now comes with syntax highlighting. http://devdocs.io http://devdocs.io {% endblockquote %} **引用网络上的文章** @@ -64,6 +68,7 @@ NEW: DevDocs now comes with syntax highlighting. http://devdocs.io {% blockquote Seth Godin http://sethgodin.typepad.com/seths_blog/2009/07/welcome-to-island-marketing.html Welcome to Island Marketing %} Every interaction is both precious and an opportunity to delight. {% endblockquote %} +{% endblockquote %} ``` {% blockquote Seth Godin http://sethgodin.typepad.com/seths_blog/2009/07/welcome-to-island-marketing.html Welcome to Island Marketing %} @@ -72,7 +77,7 @@ Every interaction is both precious and an opportunity to delight. ## 代码块 -在文章中插入代码。 +A useful feature for adding code snippets to your post. **别名：** code @@ -84,14 +89,14 @@ code snippet 以 `option:value` 的格式指定额外选项，例如：`line_number:false first_line:5`。 -| 额外选项 | 描述 | 默认值 | -| ---------------- | ----------------------------------------------------------------------------------------------------------- | ------ | -| `line_number` | 显示行号 | `true` | -| `line_threshold` | 只有代码块的行数超过该阈值，才显示行数 | `0` | -| `highlight` | 启用代码高亮 | `true` | -| `first_line` | 指定第一个行号 | `1` | -| `mark` | 突出显示特定的行，每个值用逗号分隔。 使用破折号指定数字范围<br>例如： `mark:1,4-7,10` 将标记第1、4至7和10行 | -| `wrap` | 用 [`<table>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table) 包裹代码块 | `true` | +| 额外选项 | 描述 | 默认值 | +| ---------------- | ------------------------------------------------------------------------------------------ | ------ | +| `line_number` | 显示行号 | `true` | +| `line_threshold` | 只有代码块的行数超过该阈值，才显示行数 | `0` | +| `highlight` | 启用代码高亮 | `true` | +| `first_line` | 指定第一个行号 | `1` | +| `mark` | 突出显示特定的行，每个值用逗号分隔。 使用破折号指定数字范围<br>例如： `mark:1,4-7,10` 将标记第1、4至7和10行 | | +| `wrap` | 用 [`<table>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table) 包裹代码块 | `true` | ### 示例 @@ -119,7 +124,7 @@ alert('Hello World!'); [rectangle setX: 10 y: 10 width: 20 height: 20]; {% endcodeblock %} -**附加说明** +**在文章中插入代码。** ``` {% codeblock Array.map %} @@ -141,23 +146,22 @@ _.compact([0, 1, false, 2, '', 3]); ``` {% codeblock _.compact http://underscorejs.org/#compact Underscore.js %} -\_.compact([0, 1, false, 2, '', 3]); -=> [1, 2, 3] +\_.compact([0, 1, false, 2, '', 3]); => [1, 2, 3] {% endcodeblock %} ## 反引号代码块 -另一种形式的代码块，不同的是它使用三个反引号来包裹。 +This is identical to using a code block, but instead uses three backticks to delimit the block. {% raw %} -`` [language] [title] [url] [link text] +``[language] [title] [url] [link text] code snippet `` {% endraw %} ## Pull Quote -在文章中插入 Pull quote。 +To add pull quotes to your posts: ``` {% pullquote [class] %} @@ -168,7 +172,7 @@ content ## jsFiddle (`v7.0.0` 中被移除) {% note warn %} -如果你正在使用 `v7.0.0+`，请使用 [hexo-tag-embed](https://github.com/hexojs/hexo-tag-embed) 替代。 +The tag was removed in Hexo 7.0.0. 如果你正在使用 `v7.0.0+`，请使用 [hexo-tag-embed](https://github.com/hexojs/hexo-tag-embed) 替代。 {% endnote %} 在文章中嵌入 jsFiddle。 @@ -183,7 +187,7 @@ content 如果你正在使用 `v7.0.0+`，请使用 [hexo-tag-embed](https://github.com/hexojs/hexo-tag-embed) 替代。 {% endnote %} -在文章中嵌入 Gist。 +To embed a Gist snippet: ``` {% gist gist_id [filename] %} @@ -215,7 +219,7 @@ content ## Include Code -插入 `source/downloads/code` 文件夹内的代码文件。`source/downloads/code` 不是固定的，取决于你在配置文件中 `code_dir` 的配置。 +插入 `source/downloads/code` 文件夹内的代码文件。 `source/downloads/code` 不是固定的，取决于你在配置文件中 `code_dir` 的配置。 ``` {% include_code [title] [lang:language] [from:line] [to:line] path/to/file %} @@ -294,15 +298,15 @@ content 如果你正在使用 `v7.0.0+`，请使用 [hexo-tag-embed](https://github.com/hexojs/hexo-tag-embed) 替代。 {% endnote %} -在文章中插入 Vimeo 视频。 +Inserts a responsive or specified size Vimeo video. ``` {% vimeo video_id %} ``` -## 引用文章 +## Include Posts -引用其他文章的链接。 +Include links to other posts. ``` {% post_path filename %} @@ -311,35 +315,36 @@ content 在使用此标签时可以忽略文章文件所在的路径或者文章的永久链接信息、如语言、日期。 -例如，在文章中使用 `{% raw %}{% post_link how-to-bake-a-cake %}{% endraw %}` 时，只需有一个名为 `how-to-bake-a-cake.md` 的文章文件即可。即使这个文件位于站点文件夹的 `source/posts/2015-02-my-family-holiday` 目录下、或者文章的永久链接是 `2018/en/how-to-bake-a-cake`，都没有影响。 +例如，在文章中使用 `{% raw %}{% post_link how-to-bake-a-cake %}{% endraw %}` 时，只需有一个名为 `how-to-bake-a-cake.md` 的文章文件即可。 + +This will work as long as the filename of the post is `how-to-bake-a-cake.md`, even if the post is located at `source/posts/2015-02-my-family-holiday` and has permalink `2018/en/how-to-bake-a-cake`. 默认链接文字是文章的标题，你也可以自定义要显示的文本。 -默认对文章的标题和自定义标题里的特殊字符进行转义。可以使用 `escape` 选项，禁止对特殊字符进行转义。 +默认对文章的标题和自定义标题里的特殊字符进行转义。 可以使用 `escape` 选项，禁止对特殊字符进行转义。 例如： -**链接使用文章的标题** +**Display title of the post.** `{% raw %}{% post_link hexo-3-8-released %}{% endraw %}` {% post_link hexo-3-8-released %} -**链接使用自定义文字** +**Display custom text.** `{% raw %}{% post_link hexo-3-8-released '通往文章的链接' %}{% endraw %}` {% post_link hexo-3-8-released '通往文章的链接' %} -**对标题的特殊字符进行转义** +**Escape title.** ``` {% post_link hexo-4-released 'How to use <b> tag in title' %} ``` - {% post_link hexo-4-released 'How to use <b> tag in title' %} -**禁止对标题的特殊字符进行转义** +**Do not escape title.** ``` {% post_link hexo-4-released '<b>bold</b> custom title' false %} @@ -347,7 +352,7 @@ content {% post_link hexo-4-released '<b>bold</b> custom title' false %} -## 引用资源 +## Include Assets 引用文章的资源，与 [资源文件夹](/zh-cn/docs/asset-folders) 一起使用。 @@ -399,13 +404,13 @@ _hexo-renderer-marked 3.1.0+ 可以（可选）自动解析图片的文章路径 ### url_for (7.0.0+) -返回一个带有根路径前缀的URL。输出将会自动编码。 +返回一个带有根路径前缀的URL。 输出将会自动编码。 ``` {% url_for text path [relative] %} ``` -**示例：** +**例如：** ```yml _config.yml @@ -420,8 +425,7 @@ root: /blog/ # example <a href="/blog/index.html">blog</a> ``` -是否输出相对链接，默认遵循配置文件中 `relative_link` 的值 -例如， post/page 的路径值可能是 `/foo/bar/index.html` +是否输出相对链接，默认遵循配置文件中 `relative_link` 的值 例如， post/page 的路径值可能是 `/foo/bar/index.html` ```yml _config.yml @@ -448,7 +452,7 @@ relative_link: true ### full_url_for (7.0.0+) -返回一个以 `config.url` 为前缀的URL。输出将会自动编码。 +返回一个以 `config.url` 为前缀的URL。 输出将会自动编码。 ``` {% full_url_for text path %} @@ -471,7 +475,7 @@ url: https://example.com/blog # example ## Raw -如果您想在文章中插入 Swig 标签，可以尝试使用 Raw 标签，以免发生解析异常。 +If certain content is causing processing issues in your posts, wrap it with the `raw` tag to avoid rendering errors. ``` {% raw %} @@ -479,30 +483,14 @@ content {% endraw %} ``` -## 文章摘要和截断 +## Post Excerpt -在文章中使用 `<!-- more -->`，那么 `<!-- more -->` 之前的文字将会被视为摘要。首页中将只出现这部分文字，同时这部分文字也会出现在正文之中。 +在文章中使用 `<!-- more -->`，那么 `<!-- more -->` 之前的文字将会被视为摘要。 `excerpt:` value in the [front-matter](/docs/front-matter#Settings-amp-Their-Default-Values), if specified, will take precedent. -例如： +**示例：** ``` Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. <!-- more --> Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. ``` - -首页中将只会出现 - -``` -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. -``` - -正文中则会出现 - -``` -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. - -Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. -``` - -注意，摘要可能会被 Front Matter 中的 `excerpt` 覆盖。 diff --git a/source/zh-cn/docs/templates.md b/source/zh-cn/docs/templates.md index 9159f71405..4f6f9f83a5 100644 --- a/source/zh-cn/docs/templates.md +++ b/source/zh-cn/docs/templates.md @@ -2,20 +2,22 @@ title: 模版 --- -模板决定了网站内容的呈现方式，每个主题至少都应包含一个 `index` 模板，以下是各页面相对应的模板名称： - -| 模板 | 用途 | 回退 | -| ---------- | -------- | --------- | -| `index` | 首页 | -| `post` | 文章 | `index` | -| `page` | 分页 | `index` | -| `archive` | 归档 | `index` | +Templates define the presentation of your website by describing what each page should look like. The table below shows the corresponding template for every available page. 模板决定了网站内容的呈现方式，每个主题至少都应包含一个 `index` 模板，以下是各页面相对应的模板名称： + +{% youtube mb65bQ4iUc4 %} + +| 模板 | Page | 回退 | +| ---------- | ---- | --------- | +| `index` | 首页 | | +| `post` | 文章 | `index` | +| `page` | 分页 | `index` | +| `archive` | 归档 | `index` | | `category` | 分类归档 | `archive` | | `tag` | 标签归档 | `archive` | ## 布局（Layout） -如果页面结构类似，例如两个模板都有页首（Header）和页脚（Footer），您可考虑通过「布局」让两个模板共享相同的结构。一个布局文件必须要能显示 `body` 变量的内容，如此一来模板的内容才会被显示，举例来说： +如果页面结构类似，例如两个模板都有页首（Header）和页脚（Footer），您可考虑通过「布局」让两个模板共享相同的结构。 一个布局文件必须要能显示 `body` 变量的内容，如此一来模板的内容才会被显示，举例来说： For example: ```html index.ejs index @@ -41,11 +43,11 @@ index </html> ``` -每个模板都默认使用 `layout` 布局，您可在 front-matter 指定其他布局，或是设为 `false` 来关闭布局功能，您甚至可在布局中再使用其他布局来建立嵌套布局。 +By default, the `layout` template is used by all other templates. 每个模板都默认使用 `layout` 布局，您可在 front-matter 指定其他布局，或是设为 `false` 来关闭布局功能，您甚至可在布局中再使用其他布局来建立嵌套布局。 It's even possible to build a complex nested structure by including more layout templates in your top layout. -## 局部模版（Partial） +## Partials -局部模板让您在不同模板之间共享相同的组件，例如页首（Header）、页脚（Footer）或侧边栏（Sidebar）等，可利用局部模板功能分割为个别文件，让维护更加便利。举例来说： +Partials are useful for sharing components between your templates. Typical examples include headers, footers or sidebars. You may want to put your partials in separate files to make maintaining your website significantly more convenient. For example: ```html partial/header.ejs <h1 id="logo"><%= config.title %></h1> @@ -63,7 +65,7 @@ index <div id="content">Home page</div> ``` -### 局部变量 +## 局部变量 您可以在局部模板中指定局部变量并使用。 @@ -85,11 +87,11 @@ index ## 优化 -如果您的主题太过于复杂，或是需要生成的文件量太过于庞大，可能会大幅降低性能，除了简化主题外，您可以考虑 Hexo 2.7 新增的局部缓存（Fragment Caching） 功能。 +If your theme is exceedingly complex or if the number of files to generate becomes too large, Hexo's file generation performance may begin to decrease considerably. 如果您的主题太过于复杂，或是需要生成的文件量太过于庞大，可能会大幅降低性能，除了简化主题外，您可以考虑 Hexo 2.7 新增的局部缓存（Fragment Caching） 功能。 -本功能借鉴于 [Ruby on Rails](http://guides.rubyonrails.org/caching_with_rails.html#fragment-caching)，它储存局部内容，下次便能直接使用缓存内容，可以减少文件夹查询并使生成速度更快。 +本功能借鉴于 [Ruby on Rails](http://guides.rubyonrails.org/caching_with_rails.html#fragment-caching)，它储存局部内容，下次便能直接使用缓存内容，可以减少文件夹查询并使生成速度更快。 It causes content to be saved as fragments and cached for when additional requests are made. This can reduce the number of database queries and can also speed up file generation. -它可用于页首、页脚、侧边栏等文件不常变动的位置，举例来说： +局部模板让您在不同模板之间共享相同的组件，例如页首（Header）、页脚（Footer）或侧边栏（Sidebar）等，可利用局部模板功能分割为个别文件，让维护更加便利。 举例来说： ```js <%- fragment_cache('header', function(){ @@ -104,6 +106,5 @@ index ``` {% note warn %} -`fragment_cache()` 将会缓存第一次的渲染结果，并在之后直接输出缓存的结果。因此只有在不同页面的渲染结果都相同时才应使用局部缓存。 -比如，在配置中启用了 `relative_link` 后不应该使用局部缓存，因为相对链接在每个页面可能不同。 +`fragment_cache()` 将会缓存第一次的渲染结果，并在之后直接输出缓存的结果。 因此只有在不同页面的渲染结果都相同时才应使用局部缓存。 This should only be used on partials that are expected **not** to change across different pages. Otherwise, it should **not** be enabled. 比如，在配置中启用了 `relative_link` 后不应该使用局部缓存，因为相对链接在每个页面可能不同。 This is because relative links may appear differently across pages. {% endnote %} diff --git a/source/zh-cn/docs/themes.md b/source/zh-cn/docs/themes.md index 1ea231b9e0..d4be3ee201 100644 --- a/source/zh-cn/docs/themes.md +++ b/source/zh-cn/docs/themes.md @@ -2,10 +2,13 @@ title: 主题 --- -创建 Hexo 主题非常容易，您只要在 `themes` 文件夹内，新增一个任意名称的文件夹，并修改 `_config.yml` 内的 `theme` 设定，即可切换主题。一个主题可能会有以下的结构： +{% youtube 5ROIU_9dYe4 %} + +创建 Hexo 主题非常容易，您只要在 `themes` 文件夹内，新增一个任意名称的文件夹，并修改 `_config.yml` 内的 `theme` 设定，即可切换主题。 To start using your theme, modify the `theme` setting in your site's `_config.yml`. 一个主题可能会有以下的结构： ```plain . +. ├── _config.yml ├── languages ├── layout @@ -15,15 +18,15 @@ title: 主题 ### \_config.yml -主题的配置文件。和 Hexo 配置文件不同，主题配置文件修改时会自动更新，无需重启 Hexo Server。 +主题的配置文件。 和 Hexo 配置文件不同，主题配置文件修改时会自动更新，无需重启 Hexo Server。 ### languages -语言文件夹。请参见 [国际化 (i18n)](internationalization.html)。 +语言文件夹。 请参见 [国际化 (i18n)](internationalization.html)。 ### layout -布局文件夹。用于存放主题的模板文件，决定了网站内容的呈现方式，Hexo 内建 [Nunjucks] 模板引擎，您可以另外安装插件来获得 [EJS] 或 [Pug] 支持，Hexo 根据模板文件的扩展名来决定所使用的模板引擎，例如： +布局文件夹。 This folder contains the theme's template files, which define the appearance of your website. 用于存放主题的模板文件，决定了网站内容的呈现方式，Hexo 内建 [Nunjucks][] 模板引擎，您可以另外安装插件来获得 [EJS][] 或 [Pug][] 支持，Hexo 根据模板文件的扩展名来决定所使用的模板引擎，例如： Hexo chooses the template engine based on the file extension of the template (just like the posts). For example: ```plain layout.ejs - 使用 EJS @@ -34,19 +37,19 @@ layout.swig - 使用 Swig ### scripts -脚本文件夹。在启动时，Hexo 会加载此文件夹内的 JavaScript 文件，请参见 [插件](plugins.html) 以获得更多信息。 +脚本文件夹。 在启动时，Hexo 会加载此文件夹内的 JavaScript 文件，请参见 [插件](plugins.html) 以获得更多信息。 For more info, see [plugins](plugins.html). ### source -资源文件夹，除了模板以外的 Asset，例如 CSS、JavaScript 文件等，都应该放在这个文件夹中。文件或文件夹开头名称为 `_`（下划线）或隐藏的文件会被忽略。 +Source folder. Place your assets (e.g. CSS and JavaScript files) here. 文件或文件夹开头名称为 `_`（下划线）或隐藏的文件会被忽略。 -如果文件可以被渲染的话，会经过解析然后储存到 `public` 文件夹，否则会直接拷贝到 `public` 文件夹。 +Hexo will process and save all renderable files to the `public` folder. Non-renderable files will be copied to the `public` folder directly. ### 发布 -当您完成主题后，可以考虑将它发布到 [主题列表](/themes)，让更多人能够使用您的主题。在发布前建议先进行 [主题单元测试](https://github.com/hexojs/hexo-theme-unit-test)，确保每一项功能都能正常使用。发布主题的步骤和 [更新文档](contributing.html#更新文档) 非常类似。 +当您完成主题后，可以考虑将它发布到 [主题列表](/themes)，让更多人能够使用您的主题。 在发布前建议先进行 [主题单元测试](https://github.com/hexojs/hexo-theme-unit-test)，确保每一项功能都能正常使用。 发布主题的步骤和 [更新文档](contributing.html#更新文档) 非常类似。 -1. Fork [hexojs/site] +1. Fork [hexojs/site][] 2. 把库（repository）复制到电脑上，并安装所依赖的插件。 ```shell @@ -57,10 +60,11 @@ layout.swig - 使用 Swig 3. 在 `source/_data/themes/` 中创建一个新的 yaml 文件，使用您的主题名称作为文件名。 -4. 编辑 `source/_data/themes/<your-theme-name>.yml` 并添加您的主题。例如： +4. 编辑 `source/_data/themes/<your-theme-name>.yml` 并添加您的主题。 例如： ```yaml description: A brand new default theme for Hexo. + description: A brand new default theme for Hexo. link: https://github.com/hexojs/hexo-theme-landscape preview: http://hexo.io/hexo-theme-landscape tags: @@ -71,7 +75,7 @@ layout.swig - 使用 Swig - one_column ``` -5. 在 `source/themes/screenshots` 中添加一张截图（名称与主题相同），图片必须为 800x500 的 PNG 文件。 +5. 在 `source/themes/screenshots` 中添加一张截图（名称与主题相同），图片必须为 800x500 的 PNG 文件。 It must be a 800\*500px PNG. 6. 推送（push）分支。 7. 建立一个新的合并申请（pull request）并描述改动。 diff --git a/source/zh-cn/docs/troubleshooting.md b/source/zh-cn/docs/troubleshooting.md index 360909e7b6..33ebd1ed8a 100644 --- a/source/zh-cn/docs/troubleshooting.md +++ b/source/zh-cn/docs/troubleshooting.md @@ -1,8 +1,8 @@ --- -title: 问题解答 +title: Troubleshooting --- -在使用 Hexo 时，您可能会遇到一些问题，下列的常见问题解答可能会对您有所帮助。如果您在这里找不到解答，可以在 [GitHub](https://github.com/hexojs/hexo/issues) 或 [Google Group](https://groups.google.com/group/hexo) 上提问。 +在使用 Hexo 时，您可能会遇到一些问题，下列的常见问题解答可能会对您有所帮助。 如果您在这里找不到解答，可以在 [GitHub](https://github.com/hexojs/hexo/issues) 或 [Google Group](https://groups.google.com/group/hexo) 上提问。 ## YAML 解析错误 @@ -11,7 +11,7 @@ JS-YAML: incomplete explicit mapping pair; a key node is missed at line 18, colu last_updated: Last updated: %s ``` -如果 YAML 字符串中包含冒号（`:`）的话，请加上引号。 +Wrap the string with quotations if it contains colons. ```plain JS-YAML: bad indentation of a mapping entry at line 18, column 31: @@ -28,14 +28,12 @@ JS-YAML: bad indentation of a mapping entry at line 18, column 31: Error: EMFILE, too many open files ``` -虽然 Node.js 有非阻塞 I/O，同步 I/O 的数量仍被系统所限制，在生成大量静态文件的时候，您可能会碰到 EMFILE 错误，您可以尝试提高同步 I/O 的限制数量来解决此问题。 +虽然 Node.js 有非阻塞 I/O，同步 I/O 的数量仍被系统所限制，在生成大量静态文件的时候，您可能会碰到 EMFILE 错误，您可以尝试提高同步 I/O 的限制数量来解决此问题。 You may come across an EMFILE error when trying to generate a large number of files. You can try to run the following command to increase the number of allowed synchronous I/O operations. ```bash $ ulimit -n 10000 ``` -（这一命令只对Linux系统有效） - **Error: cannot modify limit** 如果遇到以下错误： @@ -57,13 +55,13 @@ ulimit: open files: cannot modify limit: Operation not permitted # '*' applies to all users and '-' set both soft and hard limits ``` -- 上述设置在某些情况下可能不适用，请确保 `/etc/pam.d/login` 和 `/etc/pam.d/lightdm` 有以下一行(如果这些文件不存在，请忽略此步骤)： +- 上述设置在某些情况下可能不适用，请确保 `/etc/pam.d/login` 和 `/etc/pam.d/lightdm` 有以下一行(如果这些文件不存在，请忽略此步骤)： (Ignore this step if those files do not exist) ``` session required pam_limits.so ``` -2. 如果你使用的是 [基于systemd](https://en.wikipedia.org/wiki/Systemd#Adoption) 的发行版，systemd 可能会覆盖 `limits.conf`。如果想要在 systemd 中设置限制，请在 `/etc/systemd/system.conf` 和 `/etc/systemd/user.conf` 中添加以下一行： +2. 如果你使用的是 [基于systemd](https://en.wikipedia.org/wiki/Systemd#Adoption) 的发行版，systemd 可能会覆盖 `limits.conf`。 如果想要在 systemd 中设置限制，请在 `/etc/systemd/system.conf` 和 `/etc/systemd/user.conf` 中添加以下一行： ``` DefaultLimitNOFILE=10000 @@ -71,6 +69,22 @@ DefaultLimitNOFILE=10000 3. 重启 +## Process Out of Memory + +如果你遇到了这个错误，有可能是你的文件名、分类或者标签的名字混淆了大写和小写，你可以尝试检查每一个标签和分类的名称，是否大小写一致来修复这一问题。 + +``` +FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - process out of memory +``` + +Increase Node.js heap memory size by changing the first line of `hexo-cli` (`which hexo` to look for the file). + +``` +#!/usr/bin/env node --max_old_space_size=8192 +``` + +[Out of memory while generating a huge blog · Issue #1735 · hexojs/hexo](https://github.com/hexojs/hexo/issues/1735) + ## Git 部署问题 ### RPC failed @@ -85,7 +99,18 @@ fatal: 'username.github.io' does not appear to be a git repository ### Error: ENOENT: no such file or directory -如果你遇到了这个错误，有可能是你的文件名、分类或者标签的名字混淆了大写和小写，你可以尝试检查每一个标签和分类的名称，是否大小写一致来修复这一问题。 +If you get an error like `Error: ENOENT: no such file or directory` it's probably due to mixing uppercase and lowercase letters in your tags, categories, or filenames. Git cannot automatically merge this change, so it breaks the automatic branching. + +To fix this, try + +1. Check every tag's and category's case and make sure they are the same. +1. Commit +1. Clean and build: `./node_modules/.bin/hexo clean && ./node_modules/.bin/hexo generate` +1. Manually copy the public folder to your desktop +1. Switch branch from your master branch to your deployment branch locally +1. Copy the contents of the public folder from your desktop into the deployment branch +1. Commit. You should see any merge conflicts appear that you can manually resolve. +1. Switch back to your master branch and deploy normally: `./node_modules/.bin/hexo deploy` ## 服务器问题 @@ -93,7 +118,7 @@ fatal: 'username.github.io' does not appear to be a git repository Error: listen EADDRINUSE ``` -您可能同时开启两个 Hexo 服务器，或者有其他应用程序正在占用相同的端口，请尝试修改 `port` 参数，或是在启动 Hexo 服务器时加上 `-p` 选项。 +您可能同时开启两个 Hexo 服务器，或者有其他应用程序正在占用相同的端口，请尝试修改 `port` 参数，或是在启动 Hexo 服务器时加上 `-p` 选项。 Try to modify the `port` setting or start the Hexo server with the `-p` flag. ```bash $ hexo server -p 5000 @@ -105,7 +130,7 @@ $ hexo server -p 5000 npm ERR! node-waf configure build ``` -当您尝试安装以 C/C++ 或其他非 JavaScript 语言所编写的插件时，可能会遇到此类问题，请确认您已经在电脑上安装相对应的编译器。 +当您尝试安装以 C/C++ 或其他非 JavaScript 语言所编写的插件时，可能会遇到此类问题，请确认您已经在电脑上安装相对应的编译器。 Make sure you have installed the right compiler on your computer. ## DTrace 错误 （Mac OS X） @@ -125,7 +150,7 @@ $ npm install hexo --no-optional ## 在 Jade 或 Swig 遍历数据 -Hexo 使用 [Warehouse] 存储数据，它不是一般数组所以必须先进行类型转型才能遍历。 +Hexo 使用 [Warehouse][] 存储数据，它不是一般数组所以必须先进行类型转型才能遍历。 It's not an array so you may have to transform objects into iterables. ``` {% for post in site.posts.toArray() %} @@ -134,7 +159,7 @@ Hexo 使用 [Warehouse] 存储数据，它不是一般数组所以必须先进 ## 数据没有更新 -有时数据可能没有被更新，或是生成的文件与修改前的相同，您可以尝试清除缓存并再执行一次。 +Some data cannot be updated, or the newly generated files are identical to those of the last version. Clean the cache and try again. ```bash $ hexo clean @@ -152,10 +177,9 @@ $ hexo clean } ``` -## 转义（Escape）内容 +## Escape Contents -Hexo 使用 [Nunjucks] 来解析文章（旧版本使用 [Swig]，两者语法类似），内容若包含 `{{ }}` 或 `{% %}` 可能导致解析错误，您可以用 [`raw`](/zh-cn/docs/tag-plugins#Raw) 标签包裹，单反引号 `` `{{ }}` `` 或 三反引号 来避免潜在问题发生。 -此外，Nunjucks 标签也可以通过渲染器的选项（如果支持的话）、[API](/zh-cn/api/renderer#禁用-Nunjucks-标签) 或 [front-matter](/zh-cn/docs/front-matter) 来禁用。 +Hexo 使用 [Nunjucks][] 来解析文章（旧版本使用 [Swig][]，两者语法类似），内容若包含 `{{ }}` 或 `{% %}` 可能导致解析错误，您可以用 [`raw`](/zh-cn/docs/tag-plugins#Raw) 标签包裹，单反引号 `` `{{ }}` `` 或 三反引号 来避免潜在问题发生。 Content wrapped with `{{ }}` or `{% %}` will get parsed and may cause problems. You can skip the parsing by wrapping it with the [`raw`](/docs/tag-plugins#Raw) tag plugin, a single backtick `` `{{ }}` `` or a triple backtick. 此外，Nunjucks 标签也可以通过渲染器的选项（如果支持的话）、[API](/zh-cn/api/renderer#禁用-Nunjucks-标签) 或 [front-matter](/zh-cn/docs/front-matter) 来禁用。 ``` {% raw %} @@ -171,7 +195,7 @@ Hello {{ world }} ## ENOSPC 错误 （Linux） -运行 `$ hexo server` 命令有时会返回这样的错误： +在执行 `hexo server` 后返回如下错误： ``` Error: watch ENOSPC ... @@ -185,28 +209,22 @@ $ echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo 这将会提高你能监视的文件数量。 -[Warehouse]: https://github.com/hexojs/warehouse -[Swig]: https://node-swig.github.io/swig-templates/ -[Nunjucks]: https://mozilla.github.io/nunjucks/ - ## EMPERM Error (Windows Subsystem for Linux) -在执行 `hexo server` 后返回如下错误： +运行 `$ hexo server` 命令有时会返回这样的错误： ``` Error: watch /path/to/hexo/theme/ EMPERM ``` -这是由于你使用的 WSL 版本不支持监听文件系统改动。 最新版的 WSL 已经解决了这一问题。 - -您也仍然可以通过先使用 `hexo g` 生成文件然后将其作为静态服务器运行来从 WSL 环境运行服务器： +这是由于你使用的 WSL 版本不支持监听文件系统改动。 Therefore, the live updating feature of hexo's server is currently unavailable. 您也仍然可以通过先使用 `hexo g` 生成文件然后将其作为静态服务器运行来从 WSL 环境运行服务器： ```sh $ hexo generate $ hexo server -s ``` -关于 WSL 的这一 Issue 请前往 https://github.com/Microsoft/BashOnWindows/issues/216 查看。目前这一问题已经得到了解决。 +This is [a known BashOnWindows issue](https://github.com/Microsoft/BashOnWindows/issues/216), and on 15 Aug 2016, the Windows team said they would work on it. You can get progress updates and encourage them to prioritize it on [the issue's UserVoice suggestion page](https://wpdev.uservoice.com/forums/266908-command-prompt-console-bash-on-ubuntu-on-windo/suggestions/13469097-support-for-filesystem-watchers-like-inotify). ## 模板渲染错误 @@ -217,7 +235,36 @@ FATAL Something's wrong. Maybe you can find the solution here: http://hexo.io/do Template render error: (unknown path) ``` -一种可能的原因是你的文件中存在一些不可被识别的字符，比如不可见的零宽度字符。 +Possible cause: + +- 一种可能的原因是你的文件中存在一些不可被识别的字符，比如不可见的零宽度字符。 +- Incorrect use or limitation of [tag plugin](/docs/tag-plugins). + + - Block-style tag plugin with content is not enclosed with `{% endplugin_name %}` + + ``` + # Incorrect + {% codeblock %} + fn() + {% codeblock %} + + # Incorrect + {% codeblock %} + fn() + + # Correct + {% codeblock %} + fn() + {% endcodeblock %} + ``` + + - Having Nunjucks-like syntax in a tag plugin, e.g. [`{#`](https://mozilla.github.io/nunjucks/templating.html#comments). A workaround for this example is to use [triple backtick](/docs/tag-plugins#Backtick-Code-Block) instead. [Escape Contents](/docs/troubleshooting#Escape-Contents) section has more details. + + ``` + {% codeblock lang:bash %} + Size of array is ${#ARRAY} + {% endcodeblock %} + ``` ## YAMLException (Issue [#4917](https://github.com/hexojs/hexo/issues/4917)) @@ -226,16 +273,25 @@ Template render error: (unknown path) ``` YAMLException: Specified list of YAML types (or a single Type object) contains a non-Type object. at ... + at ... ``` 这可能是由于存在包管理器无法自动修复的不正确的依赖项（即 `js-yaml`）引起的，您需要手动更新它： +```sh +npm ERR! node-waf configure build +``` + +or + ```sh $ npm install js-yaml@latest # 如果您使用 yarn 作为包管理器，请运行下面这个命令： $ yarn add js-yaml@latest ``` +if you use `yarn`. + [Warehouse]: https://github.com/hexojs/warehouse [Swig]: https://node-swig.github.io/swig-templates/ [Nunjucks]: https://mozilla.github.io/nunjucks/ diff --git a/source/zh-cn/docs/variables.md b/source/zh-cn/docs/variables.md index 7c16e324ca..57d898c1dc 100644 --- a/source/zh-cn/docs/variables.md +++ b/source/zh-cn/docs/variables.md @@ -2,96 +2,98 @@ title: 变量 --- +{% youtube T9oAax-IRw0 %} + ### 全局变量 -| 变量 | 描述 | 类型 | -| -------- | -------------------------------------------------- | ---------------------------------- | -| `site` | [网站变量](#网站变量) | `object`; 见 [网站变量](#网站变量) | +| 变量 | 描述 | 类型 | +| -------- | -------------------------------- | ------------------------- | +| `site` | Sitewide information. | `object`; 见 [网站变量](#网站变量) | | `page` | 针对该页面的内容以及 front-matter 中自定义的变量。 | `object`; 见 [页面变量](#页面变量) | -| `config` | 网站配置 | `object` (站点的配置文件) | -| `theme` | 主题配置。继承自网站配置。 | `object` (主题配置文件) | -| `path` | 当前页面的路径（不含根路径） | `string` | -| `url` | 当前页面的完整网址 | `string` | -| `env` | 环境变量 | `object` | +| `config` | 网站配置 | `object` (站点的配置文件) | +| `theme` | 主题配置。 继承自网站配置。 | `object` (主题配置文件) | +| `path` | 当前页面的路径（不含根路径） | `string` | +| `url` | 当前页面的完整网址 | `string` | +| `env` | 环境变量 | ??? | {% note warn %} -从 Hexo 5.0.0 开始，Lodash 已从全局变量中移除。迁移时 [You-Dont-Need-Lodash-Underscore](https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore) 或许能为你提供帮助。 +从 Hexo 5.0.0 开始，Lodash 已从全局变量中移除。 迁移时 [You-Dont-Need-Lodash-Underscore](https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore) 或许能为你提供帮助。 {% endnote %} ### 网站变量 -| 变量 | 描述 | 类型 | -| ----------------- | -------- | -------------------------------------- | +| 变量 | 描述 | 类型 | +| ----------------- | ---- | --------------------------- | | `site.posts` | 所有文章 | `array`，包含了站点全部的文章 `object` | | `site.pages` | 所有分页 | `array`，包含了站点全部的分页 `object` | | `site.categories` | 所有分类 | `array`，包含了站点全部的分类 `object` | -| `site.tags` | 所有标签 | `array`，包含了站点全部的标签 `object` | +| `site.tags` | 所有标签 | `object` 或 `null` | ### 页面变量 **页面（`page`）** -| 变量 | 描述 | 类型 | -| ------------------ | ------------------------------------------------------------------- | ------------------ | -| `page.title` | 页面标题 | `string` | -| `page.date` | 页面建立日期 | [Moment.js] 对象 | -| `page.updated` | 页面更新日期 | [Moment.js] 对象 | -| `page.comments` | 留言是否开启 | `boolean` | -| `page.layout` | 布局名称 | `string` | -| `page.content` | 页面的完整内容 | `string` | -| `page.excerpt` | 页面摘要 | `string` | -| `page.more` | 除了页面摘要的其余内容 | `string` | -| `page.source` | 页面原始路径 | `string` | -| `page.full_source` | 页面的完整原始路径 | `string` | -| `page.path` | 页面网址（不含根路径）。我们通常在主题中使用 `url_for(page.path)`。 | `string` | -| `page.permalink` | 页面的完整网址 | `string` | -| `page.prev` | 上一个页面。如果此为第一个页面则为 `null`。 | `object` 或 `null` | -| `page.next` | 下一个页面。如果此为最后一个页面则为 `null`。 | `object` 或 `null` | -| `page.raw` | 文章的原始内容 | `string` | -| `page.photos` | 文章的照片（用于相簿） | `array` | -| `page.link` | 文章的外部链接（用于链接文章） | `string` | +| 变量 | 描述 | 类型 | +| ------------------ | --------------------------------------------- | ---------------- | +| `page.title` | Article title | `string` | +| `page.date` | Article created date | [Moment.js][] 对象 | +| `page.updated` | 页面更新日期 | [Moment.js][] 对象 | +| `page.comments` | Comment enabled or not | `boolean` | +| `page.layout` | 布局名称 | `string` | +| `page.content` | 页面的完整内容 | `string` | +| `page.excerpt` | Article excerpt | `string` | +| `page.more` | 除了页面摘要的其余内容 | `string` | +| `page.source` | The path of the source file | `string` | +| `page.full_source` | 页面的完整原始路径 | `string` | +| `page.path` | 页面网址（不含根路径）。 我们通常在主题中使用 `url_for(page.path)`。 | `string` | +| `page.permalink` | Full (encoded) URL of the article | `string` | +| `page.prev` | 上一个页面。 如果此为第一个页面则为 `null`。 | ??? | +| `page.next` | 下一个页面。 如果此为最后一个页面则为 `null`。 | ??? | +| `page.raw` | 文章的原始内容 | ??? | +| `page.photos` | 文章的照片（用于相簿） | array | +| `page.link` | 文章的外部链接（用于链接文章） | `string` | **文章 (`post`):** 与 `page` 布局相同，但新增以下变量。 -| 变量 | 描述 | 类型 | -| ----------------- | ------------------------- | --------- | -| `page.published` | 如果该文章已发布则为 true | `boolean` | -| `page.categories` | 该文章的所有分类 | `array` | -| `page.tags` | 该文章的所有标签 | `array` | +| 变量 | 描述 | 类型 | +| ----------------- | ------------------------------- | --------------------------- | +| `page.published` | True if the post is not a draft | `boolean` | +| `page.categories` | 该文章的所有分类 | `array`，包含了站点全部的标签 `object` | +| `page.tags` | 该文章的所有标签 | `object` 或 `null` | **首页（`index`）** -| 变量 | 描述 | 类型 | -| ------------------ | ------------------------------------------------------------------------- | -------- | -| `page.per_page` | 每页显示的文章数量 | `number` | -| `page.total` | 总页数 | `number` | -| `page.current` | 目前页数 | `number` | -| `page.current_url` | 目前分页的网址 | `string` | -| `page.posts` | 本页文章 ([Data Model](https://hexojs.github.io/warehouse/)) | `object` | -| `page.prev` | 上一页的页数。如果此页是第一页的话则为 `0`。 | `number` | -| `page.prev_link` | 上一页的网址。如果此页是第一页的话则为 `''`。 | `string` | -| `page.next` | 下一页的页数。如果此页是最后一页的话则为 `0`。 | `number` | -| `page.next_link` | 下一页的网址。如果此页是最后一页的话则为 `''`。 | `string` | -| `page.path` | 当前页面的路径（不含根目录）。我们通常在主题中使用 `url_for(page.path)`。 | `string` | +| 变量 | 描述 | 类型 | +| ------------------ | -------------------------------------------------------- | -------- | +| `page.per_page` | 每页显示的文章数量 | `number` | +| `page.total` | 总页数 | `number` | +| `page.current` | 目前页数 | `number` | +| `page.current_url` | 目前分页的网址 | `string` | +| `page.posts` | 本页文章 ([Data Model](https://hexojs.github.io/warehouse/)) | `object` | +| `page.prev` | 上一页的页数。 如果此页是第一页的话则为 `0`。 | `number` | +| `page.prev_link` | 上一页的网址。 如果此页是第一页的话则为 `''`。 | `string` | +| `page.next` | 下一页的页数。 如果此页是最后一页的话则为 `0`。 | `number` | +| `page.next_link` | 下一页的网址。 如果此页是最后一页的话则为 `''`。 | `string` | +| `page.path` | 当前页面的路径（不含根目录）。 我们通常在主题中使用 `url_for(page.path)`。 | `string` | -**归档 (`archive`)** ：与 `index` 布局相同，但新增以下变量。 +**分类 (`category`)** ：与 `index` 布局相同，但新增以下变量。 -| 变量 | 描述 | 类型 | -| -------------- | ---------------------------- | --------- | -| `page.archive` | 等于 `true` | `boolean` | -| `page.year` | 年份归档 (4位) | `number` | +| 变量 | 描述 | 类型 | +| -------------- | ---------------- | --------- | +| `page.archive` | 等于 `true` | `boolean` | +| `page.year` | 年份归档 (4位) | `number` | | `page.month` | 月份归档 (没有前导零的2位数) | `number` | -**分类 (`category`)** ：与 `index` 布局相同，但新增以下变量。 +**标签 (`tag`)** ：与 `index` 布局相同，但新增以下变量。 -| 变量 | 描述 | 类型 | -| --------------- | -------- | -------- | +| 变量 | 描述 | 类型 | +| --------------- | ---- | -------- | | `page.category` | 分类名称 | `string` | -**标签 (`tag`)** ：与 `index` 布局相同，但新增以下变量。 +**归档 (`archive`)** ：与 `index` 布局相同，但新增以下变量。 -| 变量 | 描述 | 类型 | -| ---------- | -------- | -------- | +| 变量 | 描述 | 类型 | +| ---------- | ---- | -------- | | `page.tag` | 标签名称 | `string` | [Moment.js]: http://momentjs.com/ diff --git a/source/zh-cn/docs/writing.md b/source/zh-cn/docs/writing.md index 85e31152fa..830609b4dc 100644 --- a/source/zh-cn/docs/writing.md +++ b/source/zh-cn/docs/writing.md @@ -10,65 +10,65 @@ title: 写作 $ hexo new [layout] <title> ``` -您可以在命令中指定文章的布局（layout），默认为 `post`，可以通过修改 `_config.yml` 中的 `default_layout` 参数来指定默认布局。 +`post` is the default `layout`, but you can supply your own. 您可以在命令中指定文章的布局（layout），默认为 `post`，可以通过修改 `_config.yml` 中的 `default_layout` 参数来指定默认布局。 -### 布局（Layout） +## 布局（Layout） -Hexo 有三种默认布局：`post`、`page` 和 `draft`。在创建这三种不同类型的文件时，它们将会被保存到不同的路径；而您自定义的其他布局和 `post` 相同，都将储存到 `source/_posts` 文件夹。 +Hexo 有三种默认布局：`post`、`page` 和 `draft`。 Files created by each of them is saved to a different path. Newly created posts are saved to the `source/_posts` folder. -| 布局 | 路径 | +| 布局 | 路径 | | ------- | ---------------- | | `post` | `source/_posts` | | `page` | `source` | | `draft` | `source/_drafts` | {% note tip 禁用布局 %} -如果你不希望一篇文章（post/page）使用主题处理，请在它的 front-matter 中设置 `layout: false`。详情请参考[本节](/zh-cn/docs/front-matter#布局)。 +如果你不希望一篇文章（post/page）使用主题处理，请在它的 front-matter 中设置 `layout: false`。 详情请参考[本节](/zh-cn/docs/front-matter#布局)。 {% endnote %} -### 文件名称 +## 文件名称 -Hexo 默认以标题做为文件名称，但您可编辑 `new_post_name` 参数来改变默认的文件名称，举例来说，设为 `:year-:month-:day-:title.md` 可让您更方便的通过日期来管理文章。你可以使用以下占位符： +By default, Hexo uses the post title as its filename. You can edit the `new_post_name` setting in `_config.yml` to change the default filename. For example, `:year-:month-:day-:title.md` will prefix filenames with the post creation date. 你可以使用以下占位符： -| 变量 | 描述 | -| ---------- | ----------------------------------- | -| `:title` | 标题（小写，空格将会被替换为短杠） | -| `:year` | 建立的年份，比如， `2015` | -| `:month` | 建立的月份（有前导零），比如， `04` | -| `:i_month` | 建立的月份（无前导零），比如， `4` | -| `:day` | 建立的日期（有前导零），比如， `07` | -| `:i_day` | 建立的日期（无前导零），比如， `7` | +| Placeholder | 描述 | +| ----------- | -------------------- | +| `:title` | 标题（小写，空格将会被替换为短杠） | +| `:year` | 建立的年份，比如， `2015` | +| `:month` | 建立的月份（有前导零），比如， `04` | +| `:i_month` | 建立的月份（无前导零），比如， `4` | +| `:day` | 建立的日期（有前导零），比如， `07` | +| `:i_day` | 建立的日期（无前导零），比如， `7` | -### 草稿 +## 草稿 -刚刚提到了 Hexo 的一种特殊布局：`draft`，这种布局在建立时会被保存到 `source/_drafts` 文件夹，您可通过 `publish` 命令将草稿移动到 `source/_posts` 文件夹，该命令的使用方式与 `new` 十分类似，您也可在命令中指定 `layout` 来指定布局。 +Previously, we mentioned a special layout in Hexo: `draft`. Posts initialized with this layout are saved to the `source/_drafts` folder. You can use the `publish` command to move drafts to the `source/_posts` folder. `publish` works in a similar way to the `new` command. ```bash $ hexo publish [layout] <title> ``` -草稿默认不会显示在页面中，您可在执行时加上 `--draft` 参数，或是在 `_config.yml` 中把 `render_drafts` 参数设为 `true` 来预览草稿。 +Drafts are not displayed by default. You can add the `--draft` option when running Hexo or enable the `render_drafts` setting in `_config.yml` to render drafts. -## 模版（Scaffold） +## Scaffolds -在新建文章时，Hexo 会根据 `scaffolds` 文件夹内相对应的文件来建立文件，例如： +在新建文章时，Hexo 会根据 `scaffolds` 文件夹内相对应的文件来建立文件，例如： For example: ```bash $ hexo new photo "My Gallery" ``` -在执行这行指令时，Hexo 会尝试在 `scaffolds` 文件夹中寻找 `photo.md`，并根据其内容建立文章，以下是您可以在模版中使用的变量： +在执行这行指令时，Hexo 会尝试在 `scaffolds` 文件夹中寻找 `photo.md`，并根据其内容建立文章，以下是您可以在模版中使用的变量： The following placeholders are available in scaffolds: -| 变量 | 描述 | -| -------- | ------------ | -| `layout` | 布局 | -| `title` | 标题 | -| `date` | 文件建立日期 | +| Placeholder | 描述 | +| ----------- | ------ | +| `layout` | 布局 | +| `title` | 标题 | +| `date` | 文件建立日期 | -### 支持的格式 +## 支持的格式 Hexo 支持以任何格式书写文章，只要安装了相应的渲染插件。 -例如，Hexo 默认安装了 `hexo-renderer-marked` 和 `hexo-renderer-ejs`，因此你不仅可以用 Markdown 写作，你还可以用 EJS 写作。如果你安装了 `hexo-renderer-pug`，你甚至可以用 Pug 模板语言书写文章。 +例如，Hexo 默认安装了 `hexo-renderer-marked` 和 `hexo-renderer-ejs`，因此你不仅可以用 Markdown 写作，你还可以用 EJS 写作。 如果你安装了 `hexo-renderer-pug`，你甚至可以用 Pug 模板语言书写文章。 只需要将文章的扩展名从 `md` 改成 `ejs`，Hexo 就会使用 `hexo-renderer-ejs` 渲染这个文件，其他格式同理。 diff --git a/source/zh-cn/index.md b/source/zh-cn/index.md index a52484a2e8..f91a131dca 100644 --- a/source/zh-cn/index.md +++ b/source/zh-cn/index.md @@ -12,7 +12,7 @@ comments: false <i class="fa fa-bolt"></i> </div> <h3 class="intro-feature-title">超快速度</h3> - <p class="intro-feature-desc">Node.js 所带来的超快生成速度，让上百个页面在几秒内瞬间完成渲染。</p> + <p class="intro-feature-desc">Node.js 所带来的超快生成速度，让上百个页面在几秒内瞬间完成渲染。 Hundreds of files take only seconds to build.</p> </div> </li> <li class="intro-feature-wrap"> @@ -34,8 +34,8 @@ comments: false <div class="intro-feature-icon"> <i class="fa fa-cog"></i> </div> - <h3 class="intro-feature-title">插件和可扩展性</h3> - <p class="intro-feature-desc">强大的 API 带来无限的可能，与数种模板引擎（EJS，Pug，Nunjucks）和工具（Babel，PostCSS，Less/Sass）轻易集成</p> + <h3 class="intro-feature-title">Plugins</h3> + <p class="intro-feature-desc">Features powerful APIs for limitless extensibility. 强大的 API 带来无限的可能，与数种模板引擎（EJS，Pug，Nunjucks）和工具（Babel，PostCSS，Less/Sass）轻易集成 Easily integrate with existing NPM packages (Babel, PostCSS, Less/Sass, etc).</p> </div> </li> </ul>