diff --git a/source/zh-tw/api/box.md b/source/zh-tw/api/box.md index 8291f1133f..e8388ecebc 100644 --- a/source/zh-tw/api/box.md +++ b/source/zh-tw/api/box.md @@ -2,13 +2,15 @@ title: 箱子（Box） --- -「箱子」是 Hexo 用來處理特定資料夾中的檔案的容器，在 Hexo 中有兩個箱子，分別是 `hexo.source` 和 `hexo.theme`，前者用於處理 `source` 資料夾，而後者用於處理主題資料夾。 +Box is a container used for processing files in a specified folder. 「箱子」是 Hexo 用來處理特定資料夾中的檔案的容器，在 Hexo 中有兩個箱子，分別是 `hexo.source` 和 `hexo.theme`，前者用於處理 `source` 資料夾，而後者用於處理主題資料夾。 The former is used to process the `source` folder and the latter to process the `theme` folder. ## 載入檔案 -箱子提供了兩種方法來載入檔案：`process`, `watch`，前者用於載入資料夾內的所有檔案；而後者除了執行 `process` 以外，還會繼續監看檔案變動。 +箱子提供了兩種方法來載入檔案：`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() 停止檔案監看 }); +}); ``` ## 路徑比對 -箱子提供了多種路徑比對的模式，您可使用正規表達式（regular expression）、函數、或是一種類似於 Express 的路徑字串，例如： +Box provides many ways for path matching. You can use a regular expression, a function or an Express-style pattern string. For example: ```plain posts/:id => posts/89 posts/*path => posts/2015/title ``` -您可參考 [util.Pattern] 以獲得更多資訊。 +您可參考 [util.Pattern][] 以獲得更多資訊。 ## 處理器（Processor） -處理器（Processor）是箱子中非常重要的元素，它用於處理檔案，您可使用上述的路徑比對來限制該處理器所要處理的檔案類型。使用 `addProcessor` 來註冊處理器。 +處理器（Processor）是箱子中非常重要的元素，它用於處理檔案，您可使用上述的路徑比對來限制該處理器所要處理的檔案類型。 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) { }); ``` -箱子在處理時會把目前處理的檔案內容（`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` | 檔案相對於箱子的路徑 | -| `type` | 檔案類型。有 `create`, `update`, `skip`, `delete`。 | -| `params` | 從路徑比對中取得的資訊 | +| `path` | 檔案相對於箱子的路徑 | +| `type` | 檔案類型。 有 `create`, `update`, `skip`, `delete`。 | +| `params` | The information from path matching. | 箱子還提供了一些方法，讓您無須自行處理檔案 IO。 -| 方法 | 描述 | -| ------------ | ---------------- | -| `read` | 讀取檔案 | -| `readSync` | 同步讀取檔案 | -| `stat` | 讀取檔案狀態 | -| `statSync` | 同步讀取檔案狀態 | -| `render` | 渲染檔案 | -| `renderSync` | 同步渲染檔案 | +| 方法 | 描述 | +| ------------ | ------------------------- | +| `read` | 讀取檔案 | +| `readSync` | 同步讀取檔案 | +| `stat` | Read the status of a file | +| `statSync` | 同步讀取檔案狀態 | +| `render` | 渲染檔案 | +| `renderSync` | 同步渲染檔案 | [util.Pattern]: https://github.com/hexojs/hexo-util#patternrule diff --git a/source/zh-tw/api/console.md b/source/zh-tw/api/console.md index f71660a008..c569ce29e1 100644 --- a/source/zh-tw/api/console.md +++ b/source/zh-tw/api/console.md @@ -2,7 +2,7 @@ title: 控制台（Console） --- -控制台是 Hexo 與使用者之間溝通的橋樑。 +控制台是 Hexo 與使用者之間溝通的橋樑。 It registers and describes the available console commands. ## 概要 @@ -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 -控制台各個參數的說明，例如： +The description of each argument of a console command. For example: ```js { @@ -46,9 +47,9 @@ hexo.extend.console.register(name, desc, options, function (args) { } ``` -### 選項 +### options -控制台的選項，例如： +The description of each option of a console command. For example: ```js { @@ -56,9 +57,9 @@ hexo.extend.console.register(name, desc, options, function (args) { } ``` -### 描述 +### desc -控制台更詳細的說明。 +More detailed information about a console command. ## 範例 diff --git a/source/zh-tw/api/deployer.md b/source/zh-tw/api/deployer.md index ce850aa16d..14ccc6e63c 100644 --- a/source/zh-tw/api/deployer.md +++ b/source/zh-tw/api/deployer.md @@ -10,6 +10,7 @@ title: 佈署器（Deployer） hexo.extend.deployer.register(name, function (args) { // ... }); +}); ``` -在函數中會傳入 `args` 參數，此參數包含了 `_config.yml` 中的 `deploy` 設定，及使用者在終端機所傳入的參數。 +An argument `args` will be passed into the function. 在函數中會傳入 `args` 參數，此參數包含了 `_config.yml` 中的 `deploy` 設定，及使用者在終端機所傳入的參數。 diff --git a/source/zh-tw/api/events.md b/source/zh-tw/api/events.md index 0a9c50d7d4..aee804e9a6 100644 --- a/source/zh-tw/api/events.md +++ b/source/zh-tw/api/events.md @@ -2,31 +2,31 @@ 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 -在 Hexo 結束前發佈。 +Emitted before Hexo exits. ### generateBefore -在產生靜態檔案前發佈。 +Emitted before generation begins. ### generateAfter -在靜態檔案產生完成後發佈。 +Emitted after generation finishes. ### new -在文章檔案建立完成後發佈。此事件會回傳資料參數。 +Emitted after a new post has been created. This event returns the post data: ```js hexo.on("new", function (post) { @@ -34,21 +34,21 @@ hexo.on("new", function (post) { }); ``` -| 資料 | 描述 | -| -------------- | ------------------ | -| `post.path` | 文章檔案的完整路徑 | -| `post.content` | 文章檔案的內容 | +| 資料 | 描述 | +| -------------- | ------------------------ | +| `post.path` | 文章檔案的完整路徑 | +| `post.content` | Content of the post file | ### processBefore -在處理原始檔案前發佈。此事件會回傳一個路徑，代表箱子（Box）的根目錄。 +Emitted before processing begins. 此事件會回傳一個路徑，代表箱子（Box）的根目錄。 ### processAfter -在原始檔案處理完成後發佈。此事件會回傳一個路徑，代表箱子（Box）的根目錄。 +Emitted after processing finishes. 此事件會回傳一個路徑，代表箱子（Box）的根目錄。 ### ready -在初始化完成後發佈。 +Emitted after initialization finishes. [EventEmitter]: https://nodejs.org/dist/latest/docs/api/events.html diff --git a/source/zh-tw/api/filter.md b/source/zh-tw/api/filter.md index 19c63ca92b..dccffac023 100644 --- a/source/zh-tw/api/filter.md +++ b/source/zh-tw/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。 +You can define the `priority`. Lower `priority` means that it will be executed first. 您可指定過濾器的優先度 `priority`，`priority` 值越低的過濾器會越先執行，預設的 `priority` 是 10。 We recommend using user-configurable priority value that user can specify in the config, e.g. `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` | Arguments. This must be an array. | -`data` 會作為第一個參數傳入每個過濾器，而您可在過濾器中透過回傳值改變下一個過濾器中的 `data`，如果什麼都沒回傳的話則會保持原本的 `data`。您還可使用 `args` 指定過濾器的其他參數。舉例來說： +The first argument passed into each filter is `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,9 +100,9 @@ hexo.extend.filter.unregister("example", require("path/to/filter")); ### before_post_render -在文章開始渲染前執行。您可參考 [文章渲染](posts.html#渲染) 以瞭解執行順序。 +在文章開始渲染前執行。 您可參考 [文章渲染](posts.html#渲染) 以瞭解執行順序。 -舉例來說，把標題轉為小寫： +For example, to transform the title to lower case: ```js hexo.extend.filter.register("before_post_render", function (data) { @@ -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,35 +180,48 @@ hexo.extend.filter.register("template_locals", function (locals) { hexo.extend.filter.register("after_init", function () { // ... }); +}); ``` ### new_post_path -用來決定新建文章的路徑，在建立文章時執行。 +Executed when creating a post to determine the path of new posts. ```js 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-tw/api/generator.md b/source/zh-tw/api/generator.md index 1b3d0b6411..77aa1e3026 100644 --- a/source/zh-tw/api/generator.md +++ b/source/zh-tw/api/generator.md @@ -2,7 +2,7 @@ title: 產生器（Generator） --- -產生器根據處理後的原始檔案建立路由。 +A generator builds routes based on processed files. ## 概要 @@ -10,9 +10,10 @@ title: 產生器（Generator） hexo.extend.generator.register(name, function (locals) { // ... }); +}); ``` -在函數中會傳入一個 `locals` 參數，等同於 [網站變數](../docs/variables.html#網站變數)，請盡量利用此參數取得網站資料，避免直接存取資料庫。 +A `locals` argument will get passed into the function, containing the [site variables](../docs/variables.html#Site-Variables). You should use this argument to get the website data, thereby avoiding having to access the database directly. ## 更新路由 @@ -32,21 +33,21 @@ hexo.extend.generator.register("test", function (locals) { }); ``` -| 屬性 | 描述 | -| -------- | --------------------------------------------------------------------------------- | -| `path` | 路徑。不可包含開頭的 `/`。 | -| `data` | 資料 | -| `layout` | 佈局。指定用於渲染的模板，可為字串或陣列，如果省略此屬性的話則會直接輸出 `data`。 | +| 屬性 | 描述 | +| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `path` | 路徑。 不可包含開頭的 `/`。 | +| `data` | 資料 | +| `layout` | 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.** ## 範例 -### 彙整頁面 +### Archive Page -在 `archives/index.html` 建立一彙整頁面，把所有文章當作資料傳入模板內，這個資料也就等同於模板中的 `page` 變數。 +在 `archives/index.html` 建立一彙整頁面，把所有文章當作資料傳入模板內，這個資料也就等同於模板中的 `page` 變數。 We pass all posts as data to the templates. This data is equivalent to the `page` variable in templates. -然後，設定 `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,9 +59,9 @@ hexo.extend.generator.register("archive", function (locals) { }); ``` -### 有分頁的彙整頁面 +### Archive Page with Pagination -您可透過 [hexo-pagination] 這個方便的官方工具程式來輕鬆建立分頁彙整。 +您可透過 [hexo-pagination][] 這個方便的官方工具程式來輕鬆建立分頁彙整。 ```js var pagination = require("hexo-pagination"); @@ -74,7 +75,7 @@ hexo.extend.generator.register("archive", function (locals) { }); ``` -### 產生所有文章 +### Generate All Posts 遍歷 `locals.posts` 中的所有文章並產生所有文章的路由。 diff --git a/source/zh-tw/api/helper.md b/source/zh-tw/api/helper.md index 2c09cd9b11..e1fddcf439 100644 --- a/source/zh-tw/api/helper.md +++ b/source/zh-tw/api/helper.md @@ -1,8 +1,10 @@ --- -title: 輔助函數（Helper） +title: Helper --- -輔助函數幫助您在模板中快速插入內容，建議您把複雜的程式碼放在輔助函數而非模板中。 +A helper makes it easy to quickly add snippets to your templates. We recommend using helpers instead of templates when you're dealing with more complicated code. + +Helpers can not be accessed from `source` files. ## 概要 @@ -10,6 +12,7 @@ title: 輔助函數（Helper） hexo.extend.helper.register(name, function () { // ... }); +}); ``` ## 範例 @@ -25,7 +28,7 @@ hexo.extend.helper.register("js", function (path) { // <script src="script.js"></script> ``` -## 常見問題 +## FAQ ### 定制 helper 應該放在哪裡？ @@ -33,7 +36,7 @@ hexo.extend.helper.register("js", function (path) { ### 如何在我的定制 helper 中使用另外一個已經註冊的 helper？ -All helpers are executed in the same context. For example, to use [`url_for()`](/docs/helpers#url-for) inside a custom helper: +All helpers are executed in the same context. All helpers are executed in the same context. For example, to use [`url_for()`](/docs/helpers#url-for) inside a custom helper: ```js hexo.extend.helper.register("lorem", function (path) { diff --git a/source/zh-tw/api/index.md b/source/zh-tw/api/index.md index 6f9637dc40..446674f63a 100644 --- a/source/zh-tw/api/index.md +++ b/source/zh-tw/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. A new instance takes two arguments: the root directory of the website, `base_dir`, and an object containing the initialization options. Next, we initialize this instance by calling the `init` method on it, which will then cause Hexo to load its configuration and plugins. ```js var Hexo = require("hexo"); @@ -17,22 +17,26 @@ var hexo = new Hexo(process.cwd(), {}); hexo.init().then(function () { // ... }); +}); ``` -| 選項 | 描述 | 預設值 | -| -------- | --------------------------------------------------------------------------- | ------------- | -| `debug` | 開啟除錯模式。在終端機中顯示除錯訊息，並在根目錄中儲存 `debug.log` 記錄檔。 | `false` | -| `safe` | 開啟安全模式。不要載入任何外掛。 | `false` | -| `silent` | 開啟安靜模式。不要在終端機中顯示任何訊息。 | `false` | -| `config` | 指定配置檔案的路徑。 | `_config.yml` | +| 選項 | 描述 | Default | +| ------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------- | +| `debug` | 開啟除錯模式。 在終端機中顯示除錯訊息，並在根目錄中儲存 `debug.log` 記錄檔。 | `false` | +| `safe` | 開啟安全模式。 不要載入任何外掛。 | `false` | +| `silent` | 開啟安靜模式。 不要在終端機中顯示任何訊息。 | `false` | +| `config` | 指定配置檔案的路徑。 | `_config.yml` | +| `draft` / `drafts` | Enable to add drafts to the posts list.<br> example: when you use `hexo.locals.get('posts')` | `render_drafts` of \_config.yml | ## 載入檔案 -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 () { // ... }); @@ -40,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 -當指令完畢後，請執行 `exit` 方法讓 Hexo 完成結束前的準備工作（如儲存資料庫）。 +You should call the `exit` method upon successful or unsuccessful completion of a console command. This allows Hexo to exit gracefully and finish up important things such as saving the database. ```js hexo diff --git a/source/zh-tw/api/injector.md b/source/zh-tw/api/injector.md index a1200bf9d7..cafca5131c 100644 --- a/source/zh-tw/api/injector.md +++ b/source/zh-tw/api/injector.md @@ -2,7 +2,7 @@ title: Injector --- -An injector is used to add static code snippet to the `<head>` or/and `<body>` of generated HTML files. Hexo run injector **before** `after_render:html` filter is executed. +An injector is used to add static code snippet to the `<head>` or/and `<body>` of generated HTML files. An injector is used to add static code snippet to the `<head>` or/and `<body>` of generated HTML files. Hexo run injector **before** `after_render:html` filter is executed. ## Synopsis @@ -71,7 +71,7 @@ hexo.extend.injector.register("body_end", () => { }); ``` -Above setup will inject `APlayer.min.css` (`<link>` tag) to the `</head>` of any page which layout is `music`, and `APlayer.min.js` (`<script>` tag) to the `</body>` of those pages. Also, `jquery.js` (`<script>` tag) will be injected to `</body>` of every page generated. +Above setup will inject `APlayer.min.css` (`<link>` tag) to the `</head>` of any page which layout is `music`, and `APlayer.min.js` (`<script>` tag) to the `</body>` of those pages. Also, `jquery.js` (`<script>` tag) will be injected to `</body>` of every page generated. Also, `jquery.js` (`<script>` tag) will be injected to `</body>` of every page generated. ## Accessing user configuration diff --git a/source/zh-tw/api/locals.md b/source/zh-tw/api/locals.md index fe40009c2e..92b483933c 100644 --- a/source/zh-tw/api/locals.md +++ b/source/zh-tw/api/locals.md @@ -1,13 +1,13 @@ --- -title: 區域變數 +title: Local Variables --- -區域變數用於模版渲染，也就是模版中的 `site` 變數。 +Local variables are used for template rendering, which is the `site` variable in templates. -## 預設變數 +## Default Variables -| 變數 | 描述 | -| ------------ | -------- | +| 變數 | 描述 | +| ------------ | ---- | | `posts` | 所有文章 | | `pages` | 所有分頁 | | `categories` | 所有分類 | @@ -25,6 +25,7 @@ hexo.locals.get("posts"); hexo.locals.set('posts', function(){ return ... }); +}); ``` ## 移除變數 @@ -39,7 +40,7 @@ hexo.locals.remove("posts"); hexo.locals.toObject(); ``` -## 清除快取 +## Invalidate the cache ```js hexo.locals.invalidate(); diff --git a/source/zh-tw/api/migrator.md b/source/zh-tw/api/migrator.md index 6197fc519d..52c91df9e7 100644 --- a/source/zh-tw/api/migrator.md +++ b/source/zh-tw/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` 參數，此參數包含了使用者在終端機所傳入的參數。 +An argument `args` will be passed into the function. This argument will contain the user's input into the terminal. diff --git a/source/zh-tw/api/posts.md b/source/zh-tw/api/posts.md index 555e13474f..eaf952ff90 100644 --- a/source/zh-tw/api/posts.md +++ b/source/zh-tw/api/posts.md @@ -8,38 +8,38 @@ title: 文章 hexo.post.create(data, replace); ``` -| 參數 | 描述 | -| --------- | ------------ | -| `data` | 資料 | +| Argument | 描述 | +| --------- | ------ | +| `data` | 資料 | | `replace` | 取代現有檔案 | -您可在資料中指定文章的屬性，除了以下的屬性之外，其他屬性也會被加到 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` | 日期。預設為目前時間。 | +| 資料 | 描述 | +| -------- | ----------------------------------- | +| `title` | 標題 | +| `slug` | 網址 | +| `layout` | 佈局。 預設為 `default_layout` 設定。 | +| `path` | 路徑。 預設會根據 `new_post_path` 設定建構文章路徑。 | +| `date` | 日期。 預設為目前時間。 | -## 發佈草稿 +## Publish a Draft ```js hexo.post.publish(data, replace); ``` -| 參數 | 描述 | -| --------- | ------------ | -| `data` | 資料 | +| Argument | 描述 | +| --------- | ------ | +| `data` | 資料 | | `replace` | 取代現有檔案 | -您可在資料中指定文章的屬性，除了以下的屬性之外，其他屬性也會被加到 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. -| 資料 | 描述 | -| -------- | ------------------------------------ | +| 資料 | 描述 | +| -------- | ---------------------------- | | `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` 屬性，如果沒有的話，會試著讀取原始檔案。此函數的執行順序為： +The data must contain the `content` attribute. If not, Hexo will try to read the original file. The execution steps of this function are as follows: - 執行 `before_post_render` 過濾器 - 使用 Markdown 或其他渲染器渲染（根據副檔名而定） -- 使用 [Nunjucks] 渲染 +- 使用 [Nunjucks][] 渲染 - 執行 `after_post_render` 過濾器 [Nunjucks]: https://mozilla.github.io/nunjucks/ diff --git a/source/zh-tw/api/processor.md b/source/zh-tw/api/processor.md index 5e6fa53501..4b336eb5fc 100644 --- a/source/zh-tw/api/processor.md +++ b/source/zh-tw/api/processor.md @@ -10,6 +10,7 @@ title: 處理器（Processor） hexo.extend.processor.register(rule, function (file) { // ... }); +}); ``` 完整說明請參照 [箱子](box.html)。 diff --git a/source/zh-tw/api/renderer.md b/source/zh-tw/api/renderer.md index e5ef1cf1df..a73d287feb 100644 --- a/source/zh-tw/api/renderer.md +++ b/source/zh-tw/api/renderer.md @@ -1,8 +1,8 @@ --- -title: 渲染引擎（Renderer） +title: Renderer --- -渲染引擎用於渲染內容。 +A renderer is used to render content. ## 概要 @@ -14,21 +14,25 @@ hexo.extend.renderer.register( // ... }, sync, +); + }, + sync, ); ``` -| 參數 | 描述 | -| -------- | ------------------------------------ | +| Argument | 描述 | +| -------- | -------------------- | | `name` | 輸入的副檔名（小寫，不含開頭的 `.`） | | `output` | 輸出的副檔名（小寫，不含開頭的 `.`） | -| `sync` | 同步模式 | +| `sync` | 同步模式 | -渲染函數中會傳入兩個參數： +Three arguments will be passed into the render function: -| 參數 | 描述 | -| -------- | -------------------------------------------------------------------- | -| `data` | 包含兩個屬性：檔案路徑 `path` 和檔案內容 `text`。`path` 不一定存在。 | -| `option` | 選項 | +| Argument | 描述 | +| ---------- | --------------------------------------------------- | +| `data` | 包含兩個屬性：檔案路徑 `path` 和檔案內容 `text`。 `path` 不一定存在。 | +| `option` | 選項 | +| `callback` | Callback function of two parameters `err`, `value`. | ## 範例 diff --git a/source/zh-tw/api/rendering.md b/source/zh-tw/api/rendering.md index 49165ba81d..4ac643296b 100644 --- a/source/zh-tw/api/rendering.md +++ b/source/zh-tw/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,16 +52,16 @@ 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 hexo.render.isRenderable("image.png"); // false ``` -## 取得檔案的輸出副檔名 +## Get the Output Extension -您可透過 `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-tw/api/router.md b/source/zh-tw/api/router.md index d0e899c8da..2db41e5313 100644 --- a/source/zh-tw/api/router.md +++ b/source/zh-tw/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-tw/api/scaffolds.md b/source/zh-tw/api/scaffolds.md index ab9fd20335..be5512cf1c 100644 --- a/source/zh-tw/api/scaffolds.md +++ b/source/zh-tw/api/scaffolds.md @@ -1,8 +1,8 @@ --- -title: 鷹架（Scaffold） +title: Scaffolds --- -## 取得鷹架 +## Get a Scaffold ```js hexo.scaffold.get(name); diff --git a/source/zh-tw/api/tag.md b/source/zh-tw/api/tag.md index 129f5f11c6..9267999bd1 100644 --- a/source/zh-tw/api/tag.md +++ b/source/zh-tw/api/tag.md @@ -1,8 +1,8 @@ --- -title: 標籤外掛（Tag） +title: Tag --- -標籤外掛幫助使用者在文章中快速插入內容。 +A tag allows users to quickly and easily insert snippets into their posts. ## 概要 @@ -13,14 +13,17 @@ hexo.extend.tag.register( // ... }, options, +); + }, + options, ); ``` -標籤函數會傳入兩個參數：`args` 和 `content`，前者代表使用者在使用標籤外掛時傳入的參數，而後者則是標籤外掛所包覆的內容。 +Two arguments will be passed into the tag function: `args` and `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][]. -## 移除標籤外掛 +## Unregister Tags Use `unregister()` to replace existing [tag plugins](/docs/tag-plugins) with custom functions. @@ -46,15 +49,15 @@ hexo.extend.tag.register("youtube", tagFn); ### ends -使用結尾標籤，此選項預設為 `false`。 +Use end tags. This option is `false` by default. ### async -開啟非同步模式，此選項預設為 `false`。 +Enable async mode. This option is `false` by default. ## 範例 -### 沒有結尾標籤 +### Without End Tags 插入 Youtube 影片。 @@ -69,7 +72,7 @@ hexo.extend.tag.register("youtube", function (args) { }); ``` -### 有結尾標籤 +### With End Tags 插入 pull quote。 @@ -139,6 +142,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. @@ -163,6 +176,12 @@ module.exports = hexo => { return 'foo'; }; }; + + const { title, _content, content } = this; + + return 'foo'; + }; +}; ``` [Nunjucks]: https://mozilla.github.io/nunjucks/ diff --git a/source/zh-tw/api/themes.md b/source/zh-tw/api/themes.md index aaf3e9c375..01aa260848 100644 --- a/source/zh-tw/api/themes.md +++ b/source/zh-tw/api/themes.md @@ -4,27 +4,27 @@ title: 主題 `hexo.theme` 除了繼承 [盒子](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` 舉例。 +Views have two methods: `render` and `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)，渲染完成後，會試著尋找佈局（layout）是否存在，當 `layout` 設為 `false` 或不存在時則會直接回傳渲染結果。 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-tw/docs/asset-folders.md b/source/zh-tw/docs/asset-folders.md index 5259cb8bad..a768bc8b86 100644 --- a/source/zh-tw/docs/asset-folders.md +++ b/source/zh-tw/docs/asset-folders.md @@ -2,17 +2,25 @@ title: 資產資料夾 --- -資產（Asset）代表 `source` 資料夾中除了文章以外的所有檔案，例如圖片、CSS、JS 檔案等。Hexo 提供了一種更方便管理 Asset 的設定：`post_asset_folder`。 +## Global Asset Folder -```yaml +資產（Asset）代表 `source` 資料夾中除了文章以外的所有檔案，例如圖片、CSS、JS 檔案等。 For instance, If you are only going to have a few images in the Hexo project, then the easiest way is to keep them in a `source/images` directory. Then, you can access them using something like `![](/images/image.jpg)`. + +## Post Asset Folder + +{% youtube feIDVQ2tz0o %} + +For users who expect to regularly serve images and/or other assets, and for those who prefer to separate their assets on a post-per-post basis, Hexo also provides a more organized way to manage assets. This slightly more involved, but very convenient approach to asset management can be turned on by setting the `post_asset_folder` setting in `_config.yml` to true. + +```yaml _config.yml post_asset_folder: true ``` -當您開啟 `post_asset_folder` 設定後，在建立檔案時，Hexo 會自動建立一個與文章同名的資料夾，您可以把與該文章相關的所有資產都放到那個資料夾，如此一來，您便可以更方便的使用資產。 +Hexo 提供了一種更方便管理 Asset 的設定：`post_asset_folder`。 This asset folder will have the same name as the markdown file associated with the post. Place all assets related to your post into the associated folder, and you will be able to reference them using a relative path, making for an easier and more convenient workflow. -## 標籤外掛 +## Tag Plugins For Relative Path Referencing -Hexo 3 新增了幾個[外掛](/docs/tag-plugins#Include-Assets)，讓您更方便的在文章內引用資產。 +Referencing images or other assets using normal markdown syntax and relative paths may lead to incorrect display on archive or index pages. Plugins have been created by the community to address this issue in Hexo 2. Hexo 3 新增了幾個[外掛](/docs/tag-plugins#Include-Assets)，讓您更方便的在文章內引用資產。 These enable you to reference your assets more easily in posts: ``` {% asset_path slug %} @@ -20,6 +28,17 @@ Hexo 3 新增了幾個[外掛](/docs/tag-plugins#Include-Assets)，讓您更方 {% asset_link slug [title] %} ``` +For example, with post asset folders enabled, if you place an image `example.jpg` into your asset folder, it will _not_ appear on the index page if you reference it using a relative path with regular `![](example.jpg)` markdown syntax (however, it will work as expected in the post itself). + +The correct way to reference the image will thus be using tag plugin syntax rather than markdown: + +``` +{% asset_img example.jpg This is an example image %} +{% asset_img "spaced asset.jpg" "spaced title" %} +``` + +This way, the image will appear both inside the post and on index and archive pages. + ## 使用 markdown 嵌入一張圖片 [hexo-renderer-marked](https://github.com/hexojs/hexo-renderer-marked) 3.1.0 推出了一個新的選項，讓您可以在 markdown 中嵌入一張圖片且無須使用 `asset_img` 外掛。 @@ -33,4 +52,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-tw/docs/commands.md b/source/zh-tw/docs/commands.md index c86e3470a5..f91556af74 100644 --- a/source/zh-tw/docs/commands.md +++ b/source/zh-tw/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-TW/) 或是 [npm](https://docs.npmjs.com/cli/install) 安裝任何一個都可以；若有安裝一個以上的套件管理器， 其優先順序如上列所示。npm 預設與 [Node.js](/zh-tw/docs/#Install-Node-js) 捆綁在一起。 +2. 使用套件管理器安裝依賴關係： [Yarn 1](https://classic.yarnpkg.com/lang/en/)、[pnpm](https://pnpm.io/zh-TW/) 或是 [npm](https://docs.npmjs.com/cli/install) 安裝任何一個都可以；若有安裝一個以上的套件管理器， 其優先順序如上列所示。 npm 預設與 [Node.js](/zh-tw/docs/#Install-Node-js) 捆綁在一起。 ## new @@ -23,7 +21,29 @@ $ hexo init [folder] $ hexo new [layout] <title> ``` -建立一篇新的文章。如果沒有設定 `layout` 的話，則會使用 [\_config.yml](configuration.html) 中的 `default_layout` 設定代替。如果標題包含空格的話，請使用引號括起來。 +建立一篇新的文章。 如果沒有設定 `layout` 的話，則會使用 [\_config.yml](configuration.html) 中的 `default_layout` 設定代替。 Use the layout `draft` to create a draft. If the `title` contains spaces, surround it with quotation marks. + +| 選項 | 描述 | +| ----------------- | ------------------------------------------ | +| `-p`, `--path` | Post path. Customize the path of the post. | +| `-r`, `--replace` | Replace the current post if existed. | +| `-s`, `--slug` | Post slug. Customize the URL of the post. | + +By default, Hexo will use the title to define the path of the file. For pages, it will create a directory of that name and an `index.md` file in it. Use the `--path` option to override that behaviour and define the file path: + +```bash +hexo new page --path about/me "About me" +``` + +will create `source/about/me.md` file with the title "About me" set in the front matter. + +Please note that the title is mandatory. For example, this will not result in the behaviour you might expect: + +```bash +hexo new page --path about/me +``` + +will create the post `source/_posts/about/me.md` with the title "page" in the front matter. This is because there is only one argument (`page`) and the default layout is `post`. ## generate @@ -31,12 +51,15 @@ $ hexo new [layout] <title> $ hexo generate ``` -產生靜態檔案。 +Generates static files. -| 選項 | 描述 | -| ---------------- | ------------------ | -| `-d`, `--deploy` | 產生完成即部署網站 | -| `-w`, `--watch` | 監看檔案變更 | +| 選項 | 描述 | +| --------------------- | ------------------------------------------------------------------------ | +| `-d`, `--deploy` | Deploy after generation finishes | +| `-w`, `--watch` | Watch file changes | +| `-b`, `--bail` | Raise an error if any unhandled exception is thrown during generation | +| `-f`, `--force` | Force regenerate | +| `-c`, `--concurrency` | Maximum number of files to be generated in parallel. Default is infinity | ## publish @@ -52,13 +75,13 @@ $ hexo publish [layout] <filename> $ hexo server ``` -啟動伺服器，預設是 `http://localhost:4000/`。 +Starts a local server. By default, this is at `http://localhost:4000/`. -| 選項 | 描述 | -| ---------------- | -------------------------- | -| `-p`, `--port` | 覆蓋連接埠設定 | -| `-s`, `--static` | 只使用靜態檔案 | -| `-l`, `--log` | 啟動記錄器，或覆蓋記錄格式 | +| 選項 | 描述 | +| ---------------- | -------------------------------------- | +| `-p`, `--port` | Override default port | +| `-s`, `--static` | 只使用靜態檔案 | +| `-l`, `--log` | Enable logger. Override logger format. | ## deploy @@ -66,11 +89,11 @@ $ hexo server $ hexo deploy ``` -部署網站。 +Deploys your website. -| 選項 | 描述 | -| ------------------ | ------------------------ | -| `-g`, `--generate` | 部署網站前先產生靜態檔案 | +| 選項 | 描述 | +| ------------------ | -------------------------- | +| `-g`, `--generate` | Generate before deployment | ## render @@ -80,9 +103,9 @@ $ hexo render <file> [file2] ... 渲染檔案。 -| 選項 | 描述 | -| ---------------- | -------- | -| `-o`, `--output` | 輸出位置 | +| 輸出位置 | Description | +| ---------------- | ------------------ | +| `-o`, `--output` | Output destination | ## migrate @@ -106,7 +129,7 @@ $ hexo clean $ hexo list <type> ``` -列出網站資料。 +Lists all routes. ## version @@ -116,6 +139,14 @@ $ hexo version 顯示版本資訊。 +## config + +```bash +$ hexo config [key] [value] +``` + +Lists the configuration (`_config.yml`). If `key` is specified, only the value of the corresponding `key` in the configuration is shown; if both `key` and `value` are specified, the value of the corresponding `key` in the configuration is changed to `value`. + ## 選項 ### 安全模式 @@ -124,7 +155,7 @@ $ hexo version $ hexo --safe ``` -在安全模式下，不會載入外掛和腳本。當您在安裝新外掛後遭遇問題時，可以嘗試以安全模式重新執行。 +Disables loading plugins and scripts. Try this if you encounter problems after installing a new plugin. ### 除錯模式 @@ -132,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)。 ### 安靜模式 @@ -140,7 +171,7 @@ $ hexo --debug $ hexo --silent ``` -隱藏終端機的訊息。 +Silences output to the terminal. ### 自訂配置檔的路徑 @@ -148,7 +179,7 @@ $ hexo --silent $ hexo --config custom.yml ``` -自訂配置檔的路徑而不是使用 `_config.yml`。此參數也接受以逗號分隔的 JSON 或 YAML 檔列表字串 (不得含有空格)，它們將會被合併產生一個 `_multiconfig.yml`。 +自訂配置檔的路徑而不是使用 `_config.yml`。 此參數也接受以逗號分隔的 JSON 或 YAML 檔列表字串 (不得含有空格)，它們將會被合併產生一個 `_multiconfig.yml`。 ```bash $ hexo --config custom.yml,custom2.json diff --git a/source/zh-tw/docs/configuration.md b/source/zh-tw/docs/configuration.md index 71999f3108..862681587d 100644 --- a/source/zh-tw/docs/configuration.md +++ b/source/zh-tw/docs/configuration.md @@ -4,124 +4,172 @@ title: 配置 您可以在 `_config.yml` 或 [替代配置檔](#使用替代配置檔) 中修改網站配置。 -{% youtube A0Enyn70jKU %} - ### 網站 -| 設定 | 描述 | -| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `title` | 網站標題 | -| `subtitle` | 網站副標題 | -| `description` | 網站描述 | -| `keywords` | 網站的關鍵詞。支援多個關鍵詞。 | -| `author` | 您的名字 | -| `language` | 網站使用的語言，參考 [2-lettter ISO-639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)，預設為 `en` | -| `timezone` | 網站時區，Hexo 預設使用您電腦的時區，您可以在 [時區列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 尋找適當的時區，例如 `America/New_York` 、 `Japan` 與 `UTC` | +| 設定 | 描述 | +| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `title` | The title of your website | +| `subtitle` | The subtitle of your website | +| `description` | 網站描述 | +| `keywords` | The keywords of your website. Supports multiple values. | +| `author` | 您的名字 | +| `language` | The language of your website. 網站使用的語言，參考 [2-lettter ISO-639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)，預設為 `en` Default is `en`. | +| `timezone` | The timezone of your website. Hexo uses the setting on your computer by default. 網站時區，Hexo 預設使用您電腦的時區，您可以在 [時區列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 尋找適當的時區，例如 `America/New_York` 、 `Japan` 與 `UTC` Some examples are `America/New_York`, `Japan`, and `UTC`. | ### 網址 -| 設定 | 描述 | 預設值 | -| ---------------------------- | --------------------------------------------------------------------------------------- | --------------------------- | -| `url` | 網站的網址，must starts with `http://` or `https://` | -| `root` | 網站的根目錄 | `url's pathname` | -| `permalink` | 文章 [永久連結](permalinks.html) 的格式 | `:year/:month/:day/:title/` | -| `permalink_defaults` | `permalink` 中各區段的預設值 | -| `pretty_urls` | 改寫 [`permalink`](variables.html) 的值來美化 URL | -| `pretty_urls.trailing_index` | 是否在永久鏈接中保留尾部的 `index.html`，設置為 `false` 時去除 | `true` | +| 設定 | 描述 | Default | +| ---------------------------- | -------------------------------------------------------------- | --------------------------- | +| `url` | 網站的網址，must starts with `http://` or `https://` | | +| `root` | The root directory of your website | `url's pathname` | +| `permalink` | 文章 [永久連結](permalinks.html) 的格式 | `:year/:month/:day/:title/` | +| `permalink_defaults` | Default values of each segment in permalink | | +| `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 網站存放在子目錄 %} 如果您的網站存放在子目錄中，例如 `http://example.org/blog`，請將您的 `url` 設為 `http://example.org/blog` 並把 `root` 設為 `/blog/`。 {% endnote %} +範例: + +```yaml +# e.g. page.permalink is http://example.com/foo/bar/index.html +pretty_urls: + trailing_index: false +# becomes http://example.com/foo/bar/ +``` + ### 目錄 -| 設定 | 描述 | 預設值 | -| -------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------- | -| `source_dir` | 原始檔案資料夾，這個資料夾用於存放您的內容 | `source` | -| `public_dir` | 靜態檔案資料夾，這個資料夾用於存放建立完畢的檔案 | public | -| `tag_dir` | 標籤資料夾 | `tags` | -| `archive_dir` | 彙整資料夾 | `archives` | -| `category_dir` | 分類資料夾 | `categories` | -| `code_dir` | Include code 資料夾 | `downloads/code` | -| `i18n_dir` | 國際化（i18n）資料夾 | `:lang` | -| `skip_render` | 跳過指定檔案的渲染，您可使用 [glob 表達式](https://github.com/micromatch/micromatch#extended-globbing) 來配對路徑 | +| 設定 | 描述 | Default | +| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | +| `source_dir` | Source folder. Where your content is stored | `source` | +| `public_dir` | Public folder. Where the static site will be generated | `public` | +| `tag_dir` | Tag directory | `tags` | +| `archive_dir` | Archive directory | `archives` | +| `category_dir` | 分類資料夾 | `categories` | +| `code_dir` | Include code 資料夾 | `downloads/code` | +| `i18n_dir` | i18n directory | `:lang` | +| `skip_render` | Paths that will be copied to `public` raw, without being rendered. 跳過指定檔案的渲染，您可使用 [glob 表達式](https://github.com/micromatch/micromatch#extended-globbing) 來配對路徑 | | + +預設值 + +```yaml +skip_render: "mypage/**/*" +# will output `source/mypage/index.html` and `source/mypage/code.js` without altering them. + +## 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 資料夾](asset-folders.html) | `false` | -| `relative_link` | 把連結改為與根目錄的相對位址 | `false` | -| `future` | 顯示未來的文章 | `true` | -| `syntax_highlighter` | 程式碼區塊語法強調 (highlight) 設定，請見使用方式指南的[語法強調](/zh-tw/docs/syntax-highlight)區塊 | `highlight.js` | -| `highlight` | 程式碼區塊語法強調設定，請見使用方式指南的 [Highlight.js](/zh-tw/docs/syntax-highlight#Highlight-js) 區塊 | -| `prismjs` | 程式碼區塊的設定，請見使用方式指南的 [PrismJS](/zh-tw/docs/syntax-highlight#PrismJS) 區塊 | +| 設定 | 描述 | Default | +| ----------------------- | ---------------------------------------------------------------------------------- | -------------- | +| `new_post_name` | The filename format for new posts | `:title.md` | +| `default_layout` | Default layout | `post` | +| `titlecase` | 把標題轉換為 title case | `false` | +| `external_link` | Open external links in a new tab? | | +| `external_link.enable` | Open external links in a new tab? | `true` | +| `external_link.field` | 應用至整個 `site` 或僅只於 `post` | `site` | +| `external_link.exclude` | 主機名稱除外。 適用於特指子網域，包含 `www` | `[]` | +| `filename_case` | 把檔案名稱轉換為: `1` 小寫或 `2` 大寫 | `0` | +| `render_drafts` | 顯示草稿 | `false` | +| `post_asset_folder` | 啟動 [Asset 資料夾](asset-folders.html) | `false` | +| `relative_link` | 把連結改為與根目錄的相對位址 | `false` | +| `future` | 顯示未來的文章 | `true` | +| `syntax_highlighter` | 程式碼區塊語法強調 (highlight) 設定，請見使用方式指南的[語法強調](/zh-tw/docs/syntax-highlight)區塊 | `highlight.js` | +| `highlight` | 程式碼區塊語法強調設定，請見使用方式指南的 [Highlight.js](/zh-tw/docs/syntax-highlight#Highlight-js) 區塊 | | +| `prismjs` | 程式碼區塊的設定，請見使用方式指南的 [PrismJS](/zh-tw/docs/syntax-highlight#PrismJS) 區塊 | | + +### Home page setting + +| 設定 | 描述 | Default | +| -------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------- | +| `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` | ### 分類 & 標籤 -| 設定 | 描述 | 預設值 | -| ------------------ | -------- | --------------- | -| `default_category` | 預設分類 | `uncategorized` | -| `category_map` | 分類別名 | -| `tag_map` | 標籤別名 | +| 設定 | 描述 | Default | +| ------------------ | ------------------ | --------------- | +| `default_category` | 分類別名 | `uncategorized` | +| `category_map` | 預設分類 | | +| `tag_map` | Override tag slugs | | + +預設值 + +```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` | +| 設定 | 描述 | Default | +| ---------------- | ------------------------------------------------------------------- | ------------ | +| `date_format` | 日期格式 | `YYYY-MM-DD` | +| `time_format` | 時間格式 | `HH:mm:ss` | | `updated_option` | 當 front-matter 沒有提供 [`updated`](/zh-tw/docs/variables#頁面變數) 的值則使用此值 | `mtime` | {% note info updated_option %} 當 front-matter 沒有提供 `updated` 值，則 `updated_option` 控制此值： -- `mtime`: 使用檔案修改日期作為 `updated`。Hexo 自從 3.0.0 版本開始有這個預設行為。 +- `mtime`: 使用檔案修改日期作為 `updated`。 Hexo 自從 3.0.0 版本開始有這個預設行為。 - `date`: 使用 `date` 作為 `updated`。 通常與 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` | +| 設定 | 描述 | Default | +| ---------------- | --------------------------------------------------------------- | ------- | +| `per_page` | Number of posts displayed on each page. 一頁顯示的文章量 (`0` = 關閉分頁功能) | `10` | +| `pagination_dir` | URL format | `page` | + +範例: + +```yaml +pagination_dir: 'page' +# http://example.com/page/2 + +pagination_dir: 'awesome-page' +# http://example.com/awesome-page/2 +``` ### 擴充套件 -| 設定 | 描述 | -| -------- | ------------------------------------------- | -| `theme` | 使用主題名稱, 設為 `false` 表示關閉主題功能 | -| `deploy` | 佈署設定 | +| 設定 | 描述 | +| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `theme` | Theme name. `false` disables theming | +| `使用主題名稱, 設為 <code>false` 表示關閉主題功能</code> | Theme configuration. Include any custom theme settings under this key to override theme defaults. | +| `deploy` | 佈署設定 | +| `meta_generator` | [Meta generator](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#Attributes) tag. `false` disables injection of the tag. | ### 包含/排除 檔案或資料夾 -Hexo 會根據配置檔中 `include` / `exlude` 欄位設定，了解要 處理/忽略 哪些特定的檔案或資料夾。 +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 預設會忽略隱藏檔案與隱藏資料夾，但列在這個欄位中的檔案，Hexo 仍然會去處理 | -| `exclude` | 列在這裡的檔案將會被 Hexo 忽略 | -| `ignore` | 忽略檔案以及資料夾 | +| 預設值 | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------- | +| `include` | Include hidden files (including files/folders with a name that starts with an underscore, with an exception\*) | +| `exclude` | 原始檔案資料夾，這個資料夾用於存放您的內容 | +| `ignore` | 忽略檔案以及資料夾 | -範例: +分頁目錄 ```yaml # 包含/排除 檔案或資料夾 @@ -130,6 +178,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/**/*" @@ -145,27 +197,38 @@ 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: # 忽略任何名稱為 'foo' 的資料夾。 - "**/foo" # 只忽略 'themes/' 中的 'foo' 資料夾。 - "**/themes/*/foo" - # 與上一個相同，但應用至每個 'themes/' 的子資料夾。 + # Same as above, but applies to every subfolders of 'themes/'. - "**/themes/**/foo" ``` -列表中的每一項都必須用單引號或雙引號包裹起來。 +Each value in the list must be enclosed with single/double quotes. -`include` 和 `exclude` 並不適用於 `themes/` 目錄下的檔案。如果需要忽略 `themes/` 目錄下的部分檔案或資料夾，可以使用 `ignore` 或在檔案名之前添加下劃線 `_`。 +`include` 和 `exclude` 並不適用於 `themes/` 目錄下的檔案。 如果需要忽略 `themes/` 目錄下的部分檔案或資料夾，可以使用 `ignore` 或在檔案名之前添加下劃線 `_`。 -### 使用替代配置檔 +\* Notable exception is the `source/_posts` folder, but any file or folder with a name that starts with an underscore under that folder would still be ignored. Using `include:` rule in that folder is not recommended. -使用 `hexo` 指令時，只要在指令後面加上 `--config` 參數與自訂配置檔 (需為 JSON 或 YAML 檔) 路徑即可指定此次想要搭配使用的配置檔。該參數也可以是以逗號分隔的檔案列表 (注意中間不得有空格) 來滿足一次使用多個配置檔的需求。 +### 使用替代配置檔 -範例: +使用 `hexo` 指令時，只要在指令後面加上 `--config` 參數與自訂配置檔 (需為 JSON 或 YAML 檔) 路徑即可指定此次想要搭配使用的配置檔。 該參數也可以是以逗號分隔的檔案列表 (注意中間不得有空格) 來滿足一次使用多個配置檔的需求。 ```bash # 使用自訂的 'custom.yml' 取代預設的 '_config.yml' @@ -175,7 +238,7 @@ $ hexo server --config custom.yml $ hexo server --config custom.yml,custom2.json ``` -使用多個配置檔會合併產生一個 `_multiconfig.yml`。當合併遇到衝突時，列在愈後面的檔案，有愈高的優先權。可以使用任意數量帶有任意層級物件的 JSON 或 YAML 檔。注意**檔案列表字串中不得有空白**。 +使用多個配置檔會合併產生一個 `_multiconfig.yml`。 當合併遇到衝突時，列在愈後面的檔案，有愈高的優先權。 可以使用任意數量帶有任意層級物件的 JSON 或 YAML 檔。 注意**檔案列表字串中不得有空白**。 以前述的多個配置檔範例來說明，若 `custom.yml` 中有 `foo: bar`，且 `custom2.json` 中有 `"foo": "dinosaur"`，最終在 `_multiconfig.yml` 裡的將會是 `foo: dinosaur`。 @@ -183,7 +246,7 @@ $ hexo server --config custom.yml,custom2.json Hexo 主題是獨立的專案，具有個別的 `_config.yml` 檔案。 -除了複製一個主題並維護一個由您設定的自創分支，您也在任何地方為它進行設定。 +Instead of forking a theme, and maintaining a custom version with your settings, you can configure it from somewhere else: **頁面中的主要設定檔案的 `theme_config`** @@ -223,7 +286,7 @@ logo: "a-cool-image.png" > 從 Hexo 5.0.0 後開始支援 -檔案應該要被放在 site 資料夾中，`yml` 和 `json` 兩種格式都支援。在 `_config.yml` 中的 `theme` 必須進行設定，讓 Hexo 可以讀取 `_config.[theme].yml` +檔案應該要被放在 site 資料夾中，`yml` 和 `json` 兩種格式都支援。 在 `_config.yml` 中的 `theme` 必須進行設定，讓 Hexo 可以讀取 `_config.[theme].yml` ```yml # _config.yml @@ -259,5 +322,5 @@ logo: "a-cool-image.png" ``` {% note %} -我們強烈建議您將主題設定只存放在一個地方。但如果你有將主題設定存放在不同地方，下列的資訊是有些重要的：在頁面主要設定檔案中的 `theme_config` 在合併的時候具有最高優先權，而在專用的主題設定檔案中，主題資料夾中的 `_config.yml` 檔案則是最低優先權。 +我們強烈建議您將主題設定只存放在一個地方。 但如果你有將主題設定存放在不同地方，下列的資訊是有些重要的：在頁面主要設定檔案中的 `theme_config` 在合併的時候具有最高優先權，而在專用的主題設定檔案中，主題資料夾中的 `_config.yml` 檔案則是最低優先權。 The `_config.yml` file under the theme directory has the lowest priority. {% endnote %} diff --git a/source/zh-tw/docs/contributing.md b/source/zh-tw/docs/contributing.md index 477e257b54..8f65067613 100644 --- a/source/zh-tw/docs/contributing.md +++ b/source/zh-tw/docs/contributing.md @@ -2,17 +2,17 @@ title: 貢獻 --- -我們歡迎你加入 Hexo 的開發。🤗 +我們歡迎你加入 Hexo 的開發。 🤗 ## 開發 -我們非常歡迎您加入 Hexo 的開發，這份文件將幫助您了解開發流程。 +我們非常歡迎您加入 Hexo 的開發，這份文件將幫助您了解開發流程。 This document will help you through the process. ### 開始之前 請先閱讀 [Contributor Covenant Code of Conduct](https://github.com/hexojs/hexo/blob/master/CODE_OF_CONDUCT.md)。 -請遵守以下準則： +Please follow the coding style: - 遵守 [Google JavaScript 代碼風格](https://google.github.io/styleguide/jsguide.html)。 - 使用 2 個空格縮排。 @@ -22,8 +22,8 @@ title: 貢獻 ### 工作流程 -1. Fork [hexojs/hexo] -2. 把檔案庫（repository）複製到電腦上，並安裝相依套件。 +1. Fork [hexojs/hexo][] +2. Clone the repository to your computer and install dependencies. ```bash $ git clone https://github.com/<username>/hexo.git @@ -32,25 +32,25 @@ $ 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 ``` -6. 建立一個新的合併申請（pull request）並描述變更。 +6. Create a pull request and describe the change. ### 注意事項 - 不要修改 `package.json` 的版本號。 -- 只有在測試通過的情況下您的合併申請才會被核准，在提交前別忘了進行測試。 +- 只有在測試通過的情況下您的合併申請才會被核准，在提交前別忘了進行測試。 Don't forget to run tests before submission. ```bash $ npm test @@ -62,12 +62,12 @@ $ npm test ## 更新文件 -Hexo 文件開放原始碼，您可以在 [hexojs/site] 找到原始碼。 +Hexo 文件開放原始碼，您可以在 [hexojs/site][] 找到原始碼。 ### 工作流程 -1. Fork [hexojs/site] -2. 把檔案庫（repository）複製到電腦上，並安裝相依套件。 +1. Fork [hexojs/site][] +2. Clone the repository to your computer and install dependencies. ```bash $ npm install hexo-cli -g # If you don't have hexo-cli installed @@ -76,25 +76,25 @@ $ cd site $ npm install ``` -3. 開始編輯文件，您可透過伺服器預覽變更。 +3. Start editing the documentation. You can start the server for live previewing. ```bash $ hexo server ``` 4. 推送（push）分支。 -5. 建立一個新的合併申請（pull request）並描述變更。 +5. Create a pull request and describe the change. ### 翻譯 -1. 在 `source` 資料夾中建立一個新的語言資料夾（全小寫）。 +1. 在 `source` 資料夾中建立一個新的語言資料夾（全小寫）。 (All lower case) 2. 把 `source` 資料夾中相關的檔案（Markdown 和模板檔案）複製到新的語言資料夾中。 3. 在 `source/_data/language.yml` 中新增語言。 4. 在 `themes/navy/languages` 複製 `en.yml` 並命名為語言名稱（全小寫）。 ## 回報問題 -當您使用 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 時，請按照問題模板中的步驟提供除錯資訊和版本資訊。 diff --git a/source/zh-tw/docs/data-files.md b/source/zh-tw/docs/data-files.md index f25c5f0870..9af6613fac 100644 --- a/source/zh-tw/docs/data-files.md +++ b/source/zh-tw/docs/data-files.md @@ -2,7 +2,9 @@ title: 資料檔案 --- -有時您可能需要在主題中使用某些資料，而這些資料並不在文章內，或是想要重複使用，那麼您可以考慮使用 Hexo 3 新增的「資料檔案」功能。此功能會載入 `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-tw/docs/front-matter.md b/source/zh-tw/docs/front-matter.md index 3168e23966..7a257c775b 100644 --- a/source/zh-tw/docs/front-matter.md +++ b/source/zh-tw/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** -| 設定 | 描述 | 預設值 | -| ----------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -| `layout` | 佈局 | [`config.default_layout`](/zh-tw/docs/configuration#寫作) | -| `title` | 標題 | 文章的檔案名 | -| `date` | 建立日期 | 檔案建立日期 | -| `updated` | 更新日期 | 檔案更新日期 | -| `comments` | 開啟文章的留言功能 | `true` | -| `tags` | 標籤（不適用於分頁） | -| `categories` | 分類（不適用於分頁） | -| `permalink` | 覆蓋文章網址 | -| `excerpt` | 純文字的頁面摘要。使用[這個外掛](/zh-tw/docs/tag-plugins#文章摘要)進行文字格式化。 | -| `disableNunjucks` | 當啟用時，禁止 Nunjucks 標籤 `{{ }}`/`{% %}` 以及[標籤外掛](/zh-tw/docs/tag-plugins)的渲染功能 | -| `lang` | 設定語言並寫[自動偵測](/zh-tw/docs/internationalization#路徑) | 繼承自 `_config.yml` | -| `published` | 文章是否發布 | 在 `_posts` 中的文章為 `true`；而在 `_draft` 中的文章則為 `false` | +```json +"title": "Hello World", +"date": "2013/7/13 20:46:25" +;;; +``` + +### Settings & Their Default Values -### 佈局 +| 設定 | 描述 | Default | +| ----------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------ | +| `layout` | Layout | [`config.default_layout`](/docs/configuration#Writing) | +| `title` | 標題 | 文章的檔案名 | +| `date` | 建立日期 | 檔案建立日期 | +| `updated` | 更新日期 | 檔案更新日期 | +| `comments` | 開啟文章的留言功能 | `true` | +| `tags` | 標籤（不適用於分頁） | | +| `categories` | 分類（不適用於分頁） | | +| `permalink` | Overrides the default permalink of the post. Permalink should end with `/` or `.html` | `null` | +| `excerpt` | 純文字的頁面摘要。 使用[這個外掛](/zh-tw/docs/tag-plugins#文章摘要)進行文字格式化。 | | +| `disableNunjucks` | 當啟用時，禁止 Nunjucks 標籤 `{{ }}`/`{% %}` 以及[標籤外掛](/zh-tw/docs/tag-plugins)的渲染功能 | false | +| `lang` | 設定語言並寫[自動偵測](/zh-tw/docs/internationalization#路徑) | 繼承自 `_config.yml` | +| `published` | Whether the post should be published | 在 `_posts` 中的文章為 `true`；而在 `_draft` 中的文章則為 `false` | -依照 `_config.yml` 中所設定的 [`default_layout`](/zh-tw/docs/configuration#寫作) 值，預設的佈局為 `post`。當在文章中取消佈局 (`layout: false`)，則不會為它套用主題。然而，這依然會在任意的渲染引擎 (renderer) 中渲染，若一個文章是用 Markdown 編寫且已經安裝了 Markdown 算圖引擎（如預設的[hexo-renderer-marked](https://github.com/hexojs/hexo-renderer-marked)），則會被渲染為 HTML。 +#### Layout + +依照 `_config.yml` 中所設定的 [`default_layout`](/zh-tw/docs/configuration#寫作) 值，預設的佈局為 `post`。 當在文章中取消佈局 (`layout: false`)，則不會為它套用主題。 然而，這依然會在任意的渲染引擎 (renderer) 中渲染，若一個文章是用 Markdown 編寫且已經安裝了 Markdown 算圖引擎（如預設的[hexo-renderer-marked](https://github.com/hexojs/hexo-renderer-marked)），則會被渲染為 HTML。 無論任何佈局，[標籤外掛](/zh-tw/docs/tag-plugins)一定會進行處理，除非禁止 `disableNunjucks` 的設定或是[渲染引擎](/zh-tw/api/renderer#Disable-Nunjucks-tags). -### 分類和標籤 +#### 分類和標籤 + +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,7 +60,9 @@ tags: - Games ``` -此外我們可以透過 list 來對一篇文章同時定義多個分類。 +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. + +**Example** ```yaml categories: @@ -56,13 +70,3 @@ categories: - [Diary, Games] - [Life] ``` - -### JSON Front-matter - -除了 YAML 外，你也可利用 JSON 來撰寫 Front-matter，只要將 `---` 代換成 `;;;` 即可。 - -```json -"title": "Hello World", -"date": "2013/7/13 20:46:25" -;;; -``` diff --git a/source/zh-tw/docs/generating.md b/source/zh-tw/docs/generating.md index 48de162c65..4cb27dd5bf 100644 --- a/source/zh-tw/docs/generating.md +++ b/source/zh-tw/docs/generating.md @@ -1,5 +1,5 @@ --- -title: 產生檔案 +title: Generating --- 使用 Hexo 產生靜態檔案非常快速而且簡單。 @@ -8,17 +8,19 @@ 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 ``` -### 完成後佈署 +### Deploy After Generating -您可執行下列的其中一個指令，讓 Hexo 在建立完畢後自動佈署網站，兩個指令的作用是相同的。 +To deploy after generating, you can run one of the following commands. There is no difference between the two. ```bash $ hexo generate --deploy diff --git a/source/zh-tw/docs/github-pages.md b/source/zh-tw/docs/github-pages.md old mode 100755 new mode 100644 index aa7db8be85..92e9388d0f --- a/source/zh-tw/docs/github-pages.md +++ b/source/zh-tw/docs/github-pages.md @@ -2,10 +2,10 @@ title: 在 GitHub Pages 上部署 Hexo --- -本文將使用 [GitHub Actions](https://docs.github.com/en/actions) 部屬至 GitHub Pages，此方法適用於公開或私人儲存庫。若你不希望將整個資料夾推上 GitHub，請參閱 [一鍵部屬](#一鍵部屬)。 +本文將使用 [GitHub Actions](https://docs.github.com/en/actions) 部屬至 GitHub Pages，此方法適用於公開或私人儲存庫。 It works in both public and private repositories. 若你不希望將整個資料夾推上 GitHub，請參閱 [一鍵部屬](#一鍵部屬)。 -1. 建立名為 `<你的 GitHub 使用者名稱>.github.io` 的儲存庫，username 是你在 GitHub 上的使用者名稱，若之前已將 Hexo 上傳至其他儲存庫，將該儲存庫重命名即可。 -2. 將 Hexo 檔案 push 到儲存庫的預設分支，預設分支通常名為 **main**，舊一點的儲存庫可能名為 **master**。 +1. 建立名為 `<你的 GitHub 使用者名稱>.github.io` 的儲存庫，username 是你在 GitHub 上的使用者名稱，若之前已將 Hexo 上傳至其他儲存庫，將該儲存庫重命名即可。 If you have already uploaded to another repo, rename the repo instead. +2. Push the files of your Hexo folder to the default branch of your repository. 將 Hexo 檔案 push 到儲存庫的預設分支，預設分支通常名為 **main**，舊一點的儲存庫可能名為 **master**。 - 將 `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,28 +72,26 @@ 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/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site) -{% endnote %} +若你使用 `CNAME` 自訂域名，你需要在 `source/` 資料夾中新增 `CNAME` 檔案。 [更多資訊](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site) -## 專案頁面 +## Project page 如果你希望網站部署在 `<你的 GitHub 使用者名稱>.github.io` 的子目錄中： -1. 建立名為 `<repository 的名字>` 的儲存庫，這樣你的部落格網址為 `<你的 GitHub 使用者名稱>.github.io/<repository 的名字>`，repository 的名字可以任意，例如 blog 或 hexo。 +1. 部署完成後，前往 `https://<你的 GitHub 使用者名稱>.github.io/<repository 的名字>` 檢視網站。 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`。 -4. Commit 並 push 到預設分支上。 -5. 部署完成後，前往 `https://<你的 GitHub 使用者名稱>.github.io/<repository 的名字>` 檢視網站。 +3. In your GitHub repo's setting, navigate to **Settings** > **Pages** > **Source**. Change the source to **GitHub Actions** and save. +4. Commit and push to the default branch. +5. Once the deployment is finished, check the webpage at _username_.github.io/_repository_. -## 一鍵部屬 +## One-command deployment 以下教學改編自 [一鍵部署](/docs/one-command-deployment) . 1. 安裝 [hexo-deployer-git](https://github.com/hexojs/hexo-deployer-git). -2. 清空 `_config.yml` 的現有資料，並新增以下組態: +2. Add the following configurations to **\_config.yml**, (remove existing lines if any). ```yml deploy: @@ -104,15 +102,10 @@ deploy: ``` 3. 執行 `hexo clean && hexo deploy` 。 -4. 瀏覽 `<GitHub 用戶名>.github.io` 檢查你的網站能否運作。 +4. Check the webpage at _username_.github.io. -{% note info Windows 用戶 %} -[Awesome Hexo](https://github.com/hexojs/awesome-hexo) 中收錄了更多有關在 GitHub Pages 上部署 Hexo ，你也可透過搜尋引擎了解更多。 -歡迎更多有誌之士前來改善 Hexo 文檔，不勝感激。 -{% endnote %} +## Useful links -## 參考連結 - -- [GitHub Pages 使用文檔](https://help.github.com/categories/github-pages-basics/) -- [使用自定义 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-tw/docs/gitlab-pages.md b/source/zh-tw/docs/gitlab-pages.md index d0b6bf5408..0b3198ca70 100644 --- a/source/zh-tw/docs/gitlab-pages.md +++ b/source/zh-tw/docs/gitlab-pages.md @@ -1,11 +1,12 @@ --- -title: 在 GitLab Pages 上部署 Hexo +title: GitLab Pages --- 1. 新增名為 `<GitLab 用戶名>.gitlab.io` 的儲存庫。 如果你之前上載了 Hexo 到其他資料庫，那麼只需將該資料庫重新命名為 `<GitLab 用戶名>.gitlab.io` 。 -2. 在 GitLab 中的 `Settings -> CI / CD` 啟用 `Shared Runners` 。 -3. 將 Hexo 檔案資料夾推播到資料庫中。預設情況下 `public/` 是不會被上載到資料庫，請確保 `.gitignore` 已經包含 `public/` 一行。你的 Hexo 資料庫大致上應該與[這裡](https://gitlab.com/pages/hexo)相同。 -4. 於儲存庫目錄中新增 `.gitlab-ci.yml`: +2. Enable Shared Runners via **Settings** > **CI/CD** > **Runners** > **Enable shared runners for this project**. +3. 將 Hexo 檔案資料夾推播到資料庫中。 預設情況下 `public/` 是不會被上載到資料庫，請確保 `.gitignore` 已經包含 `public/` 一行。 你的 Hexo 資料庫大致上應該與[這裡](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 @@ -27,18 +28,18 @@ pages: - master ``` -5. GitLab CI 完成部署後，你應該能瀏覽 `<GitLab 用戶名>.gitlab.io` 頁面。 -6. (可選部分) 若要檢驗你的 site assets (html、 css、 js 等)，你可[點選這裡](https://docs.gitlab.com/ee/user/project/pipelines/job_artifacts.html) 了解。 +6. GitLab CI 完成部署後，你應該能瀏覽 `<GitLab 用戶名>.gitlab.io` 頁面。 +7. (可選部分) 若要檢驗你的 site assets (html、 css、 js 等)，你可[點選這裡](https://docs.gitlab.com/ee/user/project/pipelines/job_artifacts.html) 了解。 -## 專案頁面 +## Project page 下文將講解如何在 GitLab 上設立專案頁面: -1. 前往 Hexo資料庫的 `Settings -> General -> Advanced -> Change path`。 更改成 `<GitLab 用戶名>.gitlab.io/<任何名稱>` （請將`<任何名稱>`替換成你會用到的名字） +1. Go to **Settings** > **General** > **Advanced** > **Change path**. 更改成 `<GitLab 用戶名>.gitlab.io/<任何名稱>` （請將`<任何名稱>`替換成你會用到的名字） It can be any name, like _blog_ or _hexo_. 2. 修改 **\_config.yml**, 把 `root:` 的 `""` 改成 `"name"`. -3. 確定並推播。 +3. Commit and push. -## 參考鏈接 +## Useful links -- [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/index.html) +- [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/) - [GitLab CI Docs](https://docs.gitlab.com/ee/ci/yaml/) diff --git a/source/zh-tw/docs/helpers.md b/source/zh-tw/docs/helpers.md index d8da09d506..5d1ff4e738 100644 --- a/source/zh-tw/docs/helpers.md +++ b/source/zh-tw/docs/helpers.md @@ -1,19 +1,58 @@ --- -title: 輔助函數（Helpers） +title: Helpers --- -輔助函數幫助您在模版中快速插入內容。 +Helpers are used in templates to help you insert snippets quickly. Helpers cannot be used in source files. + +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`。 +Returns a URL with the root path prefixed. Output is encoded automatically. ```js <%- url_for(path) %> ``` +| Option | Description | Default | +| ---------- | -------------------- | ------------------------------- | +| `relative` | Output relative link | Value of `config.relative_link` | + +**Examples:** + +```yml +_config.yml +root: /blog/ # example +``` + +```js +<%- url_for('/a/path') %> +// /blog/a/path +``` + +Relative link, follows `relative_link` option by default e.g. post/page path is '/foo/bar/index.html' + +```yml +_config.yml +relative_link: true +``` + +```js +<%- url_for('/css/style.css') %> +// ../../css/style.css + +/* Override option + * you could also disable it to output a non-relative link, + * even when `relative_link` is enabled and vice versa. + */ +<%- url_for('/css/style.css', {relative: false}) %> +// /css/style.css +``` + ### relative_url 取得與 `from` 相對的 `to` 路徑。 @@ -22,15 +61,53 @@ title: 輔助函數（Helpers） <%- relative_url(from, to) %> ``` +**Examples:** + +```js +<%- relative_url('foo/bar/', 'css/style.css') %> +// ../../css/style.css +``` + +### full_url_for + +Returns a URL with the `config.url` prefixed. Output is encoded automatically. + +```js +<%- full_url_for(path) %> +``` + +**Examples:** + +```yml +_config.yml +url: https://example.com/blog # example +``` + +```js +<%- full_url_for('/a/path') %> +// https://example.com/blog/a/path +``` + ### gravatar -插入 Gravatar 圖片。 +Returns the gravatar image URL from an email. + +If you don't specify the [options] parameter, the default options will apply. Otherwise, you can set it to a number which will then be passed on as the size parameter to Gravatar. Finally, if you set it to an object, it will be converted into a query string of parameters for Gravatar. ```js <%- gravatar(email, [size]) %> ``` -**範例：** +| Option | Description | Default | +| ------ | ----------------- | ------- | +| `s` | Output image size | 40 | +| `d` | Default image | | +| `f` | Force default | | +| `r` | Rating | | + +More info: [Gravatar](https://en.gravatar.com/site/implement/images/) + +**Examples:** ```js <%- gravatar('a@abc.com') %> @@ -47,13 +124,13 @@ title: 輔助函數（Helpers） ### css -載入 CSS 檔案。`path` 可以是陣列或字串，如果 `path` 開頭不是 `/` 或任何協議，則會自動加上根路徑；如果後面沒有加上 `.css` 副檔名的話，也會自動加上。Use object type for custom attributes. +載入 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` 副檔名的話，也會自動加上。 Use object type for custom attributes. ```js <%- css(path, ...) %> ``` -**範例：** +**Examples:** ```js <%- css('style.css') %> @@ -73,13 +150,13 @@ title: 輔助函數（Helpers） ### js -載入 JavaScript 檔案。`path` 可以是陣列或字串，如果 `path` 開頭不是 `/` 或任何協議，則會自動加上根路徑；如果後面沒有加上 `.js` 副檔名的話，也會自動加上。Use object type for custom attributes. +載入 JavaScript 檔案。 `path` can be a string, an array, an object or an array of objects. `path` 可以是陣列或字串，如果 `path` 開頭不是 `/` 或任何協議，則會自動加上根路徑；如果後面沒有加上 `.js` 副檔名的話，也會自動加上。 Use object type for custom attributes. ```js <%- js(path, ...) %> ``` -**範例：** +**Examples:** ```js <%- js('script.js') %> @@ -105,13 +182,13 @@ title: 輔助函數（Helpers） <%- link_to(path, [text], [options]) %> ``` -| 選項 | 描述 | 預設值 | -| ---------- | ---------------- | ------ | -| `external` | 在新視窗開啟連結 | false | -| `class` | Class 名稱 | -| `id` | ID | +| Option | Description | Default | +| ---------- | ----------- | ------- | +| `external` | 在新視窗開啟連結 | false | +| `class` | Class 名稱 | | +| `id` | ID | | -**範例：** +**Examples:** ```js <%- link_to('http://www.google.com') %> @@ -132,16 +209,16 @@ title: 輔助函數（Helpers） <%- mail_to(path, [text], [options]) %> ``` -| 選項 | 描述 | -| --------- | --------------- | -| `class` | Class 名稱 | -| `id` | ID | -| `subject` | 郵件主旨 | -| `cc` | 副本（CC） | -| `bcc` | 密件副本（BCC） | -| `body` | 郵件內容 | +| Option | Description | +| --------- | ------------ | +| `class` | Class 名稱 | +| `id` | ID | +| `subject` | 郵件主旨 | +| `cc` | 副本（CC） | +| `bcc` | 密件副本（BCC） | +| `body` | Mail content | -**範例：** +**Examples:** ```js <%- mail_to('a@abc.com') %> @@ -159,13 +236,13 @@ title: 輔助函數（Helpers） <%- image_tag(path, [options]) %> ``` -| 選項 | 描述 | -| -------- | -------------- | -| `alt` | 圖片的替代文字 | -| `class` | Class 名稱 | -| `id` | ID | -| `width` | 圖片寬度 | -| `height` | 圖片高度 | +| Option | Description | +| -------- | ----------- | +| `alt` | 圖片的替代文字 | +| `class` | Class 名稱 | +| `id` | ID | +| `width` | 圖片寬度 | +| `height` | 圖片高度 | ### favicon_tag @@ -183,12 +260,12 @@ title: 輔助函數（Helpers） <%- feed_tag(path, [options]) %> ``` -| 選項 | 描述 | 預設值 | -| ------- | --------- | -------------- | -| `title` | Feed 標題 | `config.title` | -| `type` | Feed 類型 | +| Option | Description | Default | +| ------- | ----------- | -------------- | +| `title` | Feed 標題 | `config.title` | +| `type` | Feed 類型 | | -**範例：** +**Examples:** ```js <%- feed_tag('atom.xml') %> @@ -202,11 +279,11 @@ title: 輔助函數（Helpers） // <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]) %> @@ -220,17 +297,34 @@ title: 輔助函數（Helpers） <%- is_home() %> ``` +### is_home_first_page (+6.3.0) + +Check whether the current page is the first of home page. + +```js +<%- is_home_first_page() %> +``` + ### is_post -檢查目前是否為文章。 +Check whether the current page is a post. ```js <%- is_post() %> ``` +### is_page + +Check whether the current page is a page. + +```js +<%- strip_html('It\'s not <b>important</b> anymore!') %> +// It's not important anymore! +``` + ### is_archive -檢查目前是否為彙整頁面。 +Check whether the current page is an archive page. ```js <%- is_archive() %> @@ -238,7 +332,7 @@ title: 輔助函數（Helpers） ### is_year -檢查目前是否為年度彙整頁面。 +Check whether the current page is a yearly archive page. ```js <%- is_year() %> @@ -246,7 +340,7 @@ title: 輔助函數（Helpers） ### is_month -檢查目前是否為每月彙整頁面。 +Check whether the current page is a monthly archive page. ```js <%- is_month() %> @@ -254,7 +348,7 @@ title: 輔助函數（Helpers） ### is_category -檢查目前是否為分類彙整頁面。 +Check whether the current page is a category page. If a string is given as parameter, check whether the current page match the given category. ```js <%- is_category() %> @@ -262,13 +356,13 @@ title: 輔助函數（Helpers） ### is_tag -檢查目前是否為標籤彙整頁面。 +Check whether the current page is a tag page. If a string is given as parameter, check whether the current page match the given tag. ```js <%- is_tag() %> ``` -## 字串處理 +## String Manipulation ### trim @@ -286,7 +380,7 @@ title: 輔助函數（Helpers） <%- strip_html(string) %> ``` -**範例：** +**Examples:** ```js <%- strip_html('It\'s not <b>important</b> anymore!') %> @@ -301,7 +395,7 @@ title: 輔助函數（Helpers） <%- titlecase(string) %> ``` -**範例：** +**Examples:** ```js <%- titlecase('this is an apple') %> @@ -316,7 +410,7 @@ title: 輔助函數（Helpers） <%- markdown(str) %> ``` -**範例：** +**Examples:** ```js <%- markdown('make me **strong**') %> @@ -342,13 +436,13 @@ See [Rendering](https://hexo.io/zh-twapi/rendering) for more details. ### word_wrap -使每行的字串長度不超過 `length`。`length` 預設為 80。 +使每行的字串長度不超過 `length`。 `length` 預設為 80。 ```js <%- word_wrap(str, [length]) %> ``` -**範例：** +**Examples:** ```js <%- word_wrap('Once upon a time', 8) %> @@ -357,17 +451,23 @@ See [Rendering](https://hexo.io/zh-twapi/rendering) for more details. ### truncate -移除超過 `length` 的字串。 +Truncates text after certain `length`. Default is 30 characters. ```js <%- truncate(text, length) %> ``` -**範例：** +**Examples:** ```js <%- truncate('Once upon a time in a world far far away', 16) %> // Once upon a time + +<%- 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) ``` ### escape_html @@ -389,26 +489,26 @@ Escapes HTML entities in a string. ### 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 | Description | Default | +| ------- | --------------------------------- | ------- | +| `cache` | 儲存快取（使用 Fragment cache） | `false` | +| `only` | 限制區域變數。 在模板中只能使用 `locals` 中設定的變數。 | `false` | ### fragment_cache -儲存局部快取。它儲存局部內容，下次使用時就能直接使用快取。 +Caches the contents in a fragment. It saves the contents within a fragment and serves the cache when the next request comes in. ```js <%- fragment_cache(id, fn); ``` -**範例：** +**Examples:** ```js <%- fragment_cache('header', function(){ @@ -420,13 +520,13 @@ Escapes HTML entities in a string. ### date -插入格式化的日期。`date` 可以是 UNIX 時間、ISO 字串、Date 物件或 [Moment.js] 物件。`format` 預設為 `date_format` 設定。 +插入格式化的日期。 `date` 可以是 UNIX 時間、ISO 字串、Date 物件或 [Moment.js][] 物件。 `format` 預設為 `date_format` 設定。 ```js <%- date(date, [format]) %> ``` -**範例：** +**Examples:** ```js <%- date(Date.now()) %> @@ -438,13 +538,13 @@ Escapes HTML entities in a string. ### date_xml -插入 XML 格式的日期。`date` 可以是 UNIX 時間、ISO 字串、Date 物件或 [Moment.js] 物件。 +插入 XML 格式的日期。 `date` 可以是 UNIX 時間、ISO 字串、Date 物件或 [Moment.js][] 物件。 ```js <%- date_xml(date) %> ``` -**範例：** +**Examples:** ```js <%- date_xml(Date.now()) %> @@ -453,13 +553,13 @@ Escapes HTML entities in a string. ### time -插入格式化的時間。`date` 可以是 UNIX 時間、ISO 字串、Date 物件或 [Moment.js] 物件。`format` 預設為 `time_format` 設定。 +插入格式化的時間。 `date` 可以是 UNIX 時間、ISO 字串、Date 物件或 [Moment.js][] 物件。 `format` 預設為 `time_format` 設定。 ```js <%- time(date, [format]) %> ``` -**範例：** +**Examples:** ```js <%- time(Date.now()) %> @@ -471,13 +571,13 @@ Escapes HTML entities in a string. ### 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]) %> ``` -**範例：** +**Examples:** ```js <%- full_date(new Date()) %> @@ -489,7 +589,7 @@ Escapes HTML entities in a string. ### relative_date -Inserts relative time from now. `date` can be unix time, ISO string, date object, or [Moment.js] object. +Inserts relative time from now. `date` can be unix time, ISO string, date object, or [Moment.js][] object. ```js <%- relative_date(date) %> @@ -507,7 +607,7 @@ Inserts relative time from now. `date` can be unix time, ISO string, date object ### time_tag -Inserts time tag. `date` can be unix time, ISO string, date object, or [Moment.js] object. `format` is `date_format` setting by default. +Inserts time tag. Inserts relative time from now. `date` can be unix time, ISO string, date object, or [Moment.js][] object. Inserts time tag. `date` can be unix time, ISO string, date object, or [Moment.js][] object. `format` is `date_format` setting by default. ```js <%- time_tag(date, [format]) %> @@ -525,58 +625,65 @@ Inserts time tag. `date` can be unix time, ISO string, date object, or [Moment.j ### moment -[Moment.js] 函式庫。 +[Moment.js][] 函式庫。 ## 列表 ### list_categories -插入分類列表。 +插入彙整列表。 ```js <%- list_categories([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` | 改變分類名稱顯示方法的函數 | +| Option | Description | Default | +| ------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `orderby` | 標籤排列方式 | name | +| `order` | 排列順序。 `1`, `asc` 升冪；`-1`, `desc` 降冪。 | 1 | +| `show_count` | Display the number of posts for each category | 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` | The function that changes the display of category name. | | +| `suffix` | Add a suffix to link. | None | + +**Examples:** + +```js +檢查目前是否為分類彙整頁面。 +``` ### list_tags -插入標籤列表。 +Inserts a list of all tags. ```js <%- list_tags([tags], [options]) %> ``` -| 選項 | 描述 | 預設值 | -| ------------ | ---------------------------------------------------------------------------------- | ------ | -| `orderby` | 標籤排列方式 | name | -| `order` | 標籤排列順序。`1`, `asc` 升冪；`-1`, `desc` 降冪。 | 1 | -| `show_count` | 顯示每個標籤的文章總數 | true | -| `style` | 標籤列表的顯示方式。使用 `list` 以無序列表（unordered list）方式顯示。 | list | -| `separator` | 標籤間的分隔符號。只有在 `style` 不是 `list` 時有用。 | , | -| `class` | Class name of tag list (string) or customize each tag's class (object, see below). | tag | -| `transform` | 改變標籤名稱顯示方法的函數 | -| `amount` | 要顯示的標籤數量（0 = 無限制） | 0 | -| `suffix` | Add a suffix to link. | None | +| Option | Description | Default | +| ------------ | ----------------------------------------------------------------------------------------------------------------- | ------- | +| `orderby` | 分類排列方式 | name | +| `order` | 分類排列順序。 `1`, `asc` 升冪；`-1`, `desc` 降冪。 | 1 | +| `show_count` | Display the number of posts for each tag | 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` | Class name of tag list (string) or customize each tag's class (object, see below). | tag | +| `transform` | The function that changes the display of tag name. See examples in [list_categories](#list-categories). | | +| `amount` | 要顯示的標籤數量（0 = 無限制） | 0 | +| `suffix` | Add a suffix to link. | None | Class advanced customization: -| Option | Description | Default | -| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -| `class.ul` | `<ul>` class name (only for style `list`) | `tag-list` (list style) | -| `class.li` | `<li>` class name (only for style `list`) | `tag-list-item` (list style) | -| `class.a` | `<a>` class name | `tag-list-link` (list style) `tag-link` (normal style) | +| Option | Description | Default | +| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| `class.ul` | `<ul>` class name (only for style `list`) | `tag-list` (list style) | +| `class.li` | `<li>` class name (only for style `list`) | `tag-list-item` (list style) | +| `class.a` | `<a>` class name | `tag-list-link` (list style) `tag-link` (normal style) | | `class.label` | `<span>` class name where the tag label is stored (only for normal style, when `class.label` is set the label is put in a `<span>`) | `tag-label` (normal style) | -| `class.count` | `<span>` class name where the tag counter is stored (only when `show_count` is `true`) | `tag-list-count` (list style) `tag-count` (normal style) | +| `class.count` | `<span>` class name where the tag counter is stored (only when `show_count` is `true`) | `tag-list-count` (list style) `tag-count` (normal style) | Examples: @@ -589,22 +696,22 @@ Examples: ### list_archives -插入彙整列表。 +插入標籤列表。 ```js <%- 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` | 改變彙整名稱顯示方法的函數 | +| Option | Description | Default | +| ------------ | --------------------------------------------------------------------------------------------------------------------- | --------- | +| `type` | 類型。 此設定可為 `yearly` 或 `monthly`。 | monthly | +| `order` | 文章排列順序。 `1`, `asc` 升冪；`-1`, `desc` 降冪。 | 1 | +| `show_count` | Display the number of posts for each archive | 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` | The function that changes the display of archive name. See examples in [list_categories](#list-categories). | | ### list_posts @@ -614,15 +721,15 @@ Examples: <%- 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` | 改變文章名稱顯示方法的函數 | +| Option | Description | Default | +| ----------- | -------------------------------------------------------------------------------------------------------- | ------- | +| `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` | 插入分類列表。 | post | +| `amount` | 要顯示的文章數量（0 = 無限制） | 6 | +| `transform` | The function that changes the display of post name. See examples in [list_categories](#list-categories). | | ### tagcloud @@ -632,44 +739,62 @@ Examples: <%- 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 prefix of tags | -| `level` | 不同 class name 的總數。此選項僅在 `class` 設定時才有用。 | 10 | +| Option | Description | Default | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------- | +| `min_font` | 最小字體尺寸 | 10 | +| `max_font` | 最大字體尺寸 | 20 | +| `unit` | 字體尺寸的單位 | px | +| `amount` | Total amount of tags | unlimited | +| `orderby` | Order of tags | name | +| `order` | 標籤排列順序。 `1`, `sac` 升冪；`-1`, `desc` 降冪 | 1 | +| `color` | Colorizes the tag cloud | 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 prefix of tags | | +| `level` | 不同 class name 的總數。 此選項僅在 `class` 設定時才有用。 | 10 | +| `show_count` (+6.3.0) | Display the number of posts for each tag | false | +| `count_class` (+6.3.0) | 改變標籤名稱顯示方法的函數 | count | + +**Examples:** + +```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` | 空白文字 | &hellp; | -| `prev_next` | 顯示上一頁和下一頁的連結 | true | -| `end_size` | 顯示於兩側的頁數 | 1 | -| `mid_size` | 顯示於中間的頁數 | 2 | -| `show_all` | 顯示所有頁數。如果開啟此設定的話，`end_size` 和 `mid_size` 就沒用了。 | false | -| `escape` | Escape HTML tags | true | +| Option | Description | Default | +| -------------------------- | ---------------------------------------------------------------------------------- | ------------- | +| `base` | 基礎網址 | / | +| `format` | 網址格式 | page/%d/ | +| `total` | 顯示於中間的頁數 | 1 | +| `current` | 目前頁數 | 0 | +| `prev_text` | 上一頁連結的文字。 僅在 `prev_next` 設定開啟時才有用。 | Prev | +| `next_text` | 下一頁連結的文字。 僅在 `prev_next` 設定開啟時才有用。 | Next | +| `space` | 空白文字 | &hellp; | +| `prev_next` | 顯示上一頁和下一頁的連結 | true | +| `end_size` | The number of pages displayed on the start and the end side | 1 | +| `mid_size` | The number of pages displayed between current page, but not including current page | 2 | +| `show_all` | 顯示所有頁數。 如果開啟此設定的話，`end_size` 和 `mid_size` 就沒用了。 | false | +| `escape` | Escape HTML tags | true | +| 移除超過 `length` 的字串。 | 選項 | `分頁總數` | +| `current_class` (+6.3.0) | 文章排列方式 | `current` | +| `space_class` (+6.3.0) | 千位數分隔符號 | `space` | +| `prev_class` (+6.3.0) | 選項 | `extend prev` | +| `next_class` (+6.3.0) | 顯示於兩側的頁數 | `extend next` | +| `force_prev_next` (+6.3.0) | 顯示每個分類的文章總數 | false | **Examples:** @@ -714,11 +839,11 @@ Examples: <%- search_form(options) %> ``` -| 選項 | 描述 | 預設值 | -| -------- | ----------------------------------------------------------------------------------------- | ----------- | -| `class` | 表單的 class name | search-form | -| `text` | 搜尋提示文字 | Search | -| `button` | 顯示搜尋按鈕。此設定可為布林值（boolean）或字串，當設定是字串的時候，即為搜尋按鈕的文字。 | false | +| Option | Description | Default | +| -------- | ---------------------------------------------------------------------------------------------------------- | ----------- | +| `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 @@ -728,13 +853,13 @@ Examples: <%- number_format(number, [options]) %> ``` -| 選項 | 描述 | 預設值 | -| ----------- | ------------------------------------------- | ------ | -| `precision` | 數字精確度。此選項可為 `false` 或非負整數。 | false | -| `delimiter` | 千位數分隔符號 | , | -| `separator` | 整數和小數之間的分隔符號 | . | +| Option | Description | Default | +| ----------- | -------------------------------------------------------- | ------- | +| `precision` | 數字精確度。 此選項可為 `false` 或非負整數。 | false | +| `delimiter` | The thousands delimiter | , | +| `separator` | The separator between the fractional and integer digits. | . | -**範例：** +**Examples:** ```js <%- number_format(12345.67, {precision: 1}) %> @@ -770,48 +895,54 @@ Inserts [generator tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Elemen ### open_graph -插入 [Open Graph] 資料。 +插入 [Open Graph][] 資料。 ```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` | Article author (`og:article:author`) | `config.author` | -| `date` | Article published time (`og:article:published_time`) | Page published time | -| `updated` | Article modified time (`og:article:modified_time`) | Page modified time | +| Option | Description | Default | +| --------------- | ---------------------------------------------------- | ------------------------------------------------------- | +| `title` | 頁面標題 (`og:title`) | `page.title` | +| `type` | 頁面類型 (`og:type`) | article(post page)<br>website(non-post page) | +| `url` | 頁面網址 (`og:url`) | `url` | +| `image` | 頁面圖片 (`og:image`) | All images in the content | +| `author` | Article author (`og:article:author`) | `config.author` | +| `date` | Article published time (`og:article:published_time`) | Page published time | +| `updated` | Article modified time (`og:article:modified_time`) | Page modified time | | `language` | Article 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 | +| `site_name` | 網站名稱 (`og:site_name`) | `config.title` | +| `description` | 頁面描述 (`og:description`) | Page excerpt or first 200 characters of the content | +| `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 -解析內容中的標題標籤 (h1~h6) 並插入目錄。 +Parses all heading tags (h1~h6) in the content and inserts a table of contents. ```js <%- toc(str, [options]) %> ``` -| 選項 | 描述 | 預設值 | -| ------------- | ------------------- | ------ | -| `class` | Class 名稱 | toc | -| `list_number` | 顯示編號 | true | -| `max_depth` | 生成 TOC 的最大深度 | 6 | -| `min_depth` | 生成 TOC 的最小深度 | 1 | +| Option | Description | Default | +| ----------------------- | -------------------- | ----------------- | +| `class` | Class 名稱 | `toc` | +| `class_item` (+6.3.0) | 文章列表的 class 名稱。 | `${class}-item` | +| `class_link` (+6.3.0) | 插入分頁連結。 | `${class}-link` | +| `class_text` (+6.3.0) | 改變文章名稱顯示方法的函數 | `${class}-text` | +| `class_child` (+6.3.0) | 改變彙整名稱顯示方法的函數 | `${class}-child` | +| `class_number` (+6.3.0) | 顯示編號 | `${class}-number` | +| `class_level` (+6.3.0) | 改變分類名稱顯示方法的函數 | `${class}-level` | +| `list_number` | Displays list number | true | +| `max_depth` | 生成 TOC 的最大深度 | 6 | +| `min_depth` | 生成 TOC 的最小深度 | 1 | -**範例：** +**Examples:** ```js <%- toc(page.content) %> @@ -821,7 +952,7 @@ Inserts [generator tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Elemen Headings with attribute `data-toc-unnumbered="true"` will be marked as unnumbered (list number will not be display). -{% note warn "Warning!" %} +{% note warn "Warning!" %} %} For using `data-toc-unnumbered="true"`, the renderer must have the option to add CSS classes. Please see below PRs. diff --git a/source/zh-tw/docs/index.md b/source/zh-tw/docs/index.md index 27d0582a6b..c7e10ca9f0 100644 --- a/source/zh-tw/docs/index.md +++ b/source/zh-tw/docs/index.md @@ -2,17 +2,17 @@ title: 文件 --- -歡迎使用 Hexo，此文件將幫助您快速開始使用。如果您在使用途中遇到任何問題，您可以在 [解決問題](troubleshooting.html) 中找到解答，或者也可以在 [GitHub](https://github.com/hexojs/hexo/issues) 或 [Google Group](https://groups.google.com/group/hexo) 上詢問。 - -{% youtube PsXWbI2Mqu0 %} +歡迎使用 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/)（或其他標記語言）解析您的文章，並在幾秒鐘內，透過漂亮的主題產生靜態檔案。 +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 %} ### 安裝需求 @@ -21,17 +21,9 @@ Hexo 是一個快速、簡單且強大的網誌框架。Hexo 使用 [Markdown](h - [Node.js](http://nodejs.org/) (Node.js 版本需不低於8.10，建議使用 Node.js 10.0 及以上版本) - [Git](http://git-scm.com/) -若您的電腦已經安裝上述的必備軟體，那麼恭喜您！只需要透過 npm 即可完成 Hexo 的安裝。 +若您的電腦已經安裝上述的必備軟體，那麼恭喜您！ 只需要透過 npm 即可完成 Hexo 的安裝。 -```bash -$ npm install -g hexo-cli -``` - -如果您的電腦尚未安裝必備軟體的話，請根據下列的安裝指示來完成安裝。 - -{% note warn Mac 使用者 %} -您在編譯時可能會碰到問題，請先至 App Store 安裝 Xcode，一旦 Xcode 安裝完成後，開啟它並前往 **Preferences -> Download -> Command Line Tools -> Install** 安裝命令列工具。 -{% endnote %} +If not, please follow the following instructions to install all the requirements. ### 安裝 Git @@ -40,16 +32,20 @@ $ npm install -g hexo-cli - Linux (Ubuntu, Debian)：`sudo apt-get install git-core` - Linux (Fedora, Red Hat, CentOS)：`sudo yum install git-core` +{% note warn Mac 使用者 %} +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/en/download/)。對於中國大陸地區用戶，可以前往 [淘寶 Node.js 鏡像](https://npmmirror.com/mirrors/node/) 下載。 +Node.js 為大多數平台提供了官方的 [安裝程序](https://nodejs.org/en/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，以避免可能會出現的權限問題。 @@ -58,7 +54,7 @@ Node.js 為大多數平台提供了官方的 [安裝程序](https://nodejs.org/e {% endnote %} {% note warn For Mac / Linux 用戶 %} -如果在嘗試安裝Hexo 的過程中出現`EACCES` 權限錯誤，請遵循[由npmjs 發布的指導](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) 修復該問題。強烈建議 **不要** 使用 root、sudo 等方法覆蓋權限 +如果在嘗試安裝Hexo 的過程中出現`EACCES` 權限錯誤，請遵循[由npmjs 發布的指導](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) 修復該問題。 {% endnote %} {% note info Linux 用戶 %} @@ -73,6 +69,25 @@ Node.js 為大多數平台提供了官方的 [安裝程序](https://nodejs.org/e $ npm install -g hexo-cli ``` +### Advanced installation and usage + +Advanced users may prefer to install and use `hexo` package instead. + +```bash +讓 Hexo 準備就緒僅需幾分鐘，若您在安裝時遭遇問題而且找不到任何解決方式，請 <a href="https://github.com/hexojs/hexo/issues">回報問題</a>，我會試著解決您的問題。 +``` + +Once installed, you can run Hexo in two ways: + +1. `npx hexo <command>` +2. Linux users can set relative path of `node_modules/` folder: + +```bash +echo 'PATH="$PATH:./node_modules/.bin"' >> ~/.profile +``` + +then run Hexo using `hexo <command>` + ### 必要的 Node.js 版本 如果您堅持使用較舊版本的 Node.js，你可以考慮安裝過往版本的 Hexo。 @@ -81,15 +96,15 @@ $ npm install -g hexo-cli 有可能的話，我們強烈建議總是安裝[最新版本](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 | unknown | -| 3.0 - 3.1 | 0.10 or iojs | unknown | -| 0.0.1 - 2.8 | 0.10 | unknown | +| 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 | unknown | +| 3.0 - 3.1 | 0.10 or iojs | unknown | +| 0.0.1 - 2.8 | 0.10 | unknown | diff --git a/source/zh-tw/docs/internationalization.md b/source/zh-tw/docs/internationalization.md index eeac1fdd33..5d816f20dc 100644 --- a/source/zh-tw/docs/internationalization.md +++ b/source/zh-tw/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-tw/docs/migration.md b/source/zh-tw/docs/migration.md index 8bac624201..fd10c85d31 100644 --- a/source/zh-tw/docs/migration.md +++ b/source/zh-tw/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,7 +46,7 @@ $ npm install hexo-migrator-wordpress --save 由 WordPress 儀表板的 "工具" → "匯出" → "WordPress" 匯出網站資料 (詳情請參見 [WordPress 支援頁](http://en.support.wordpress.com/export/))。 -接著執行： +Now run: ```bash $ hexo migrate wordpress <source> @@ -60,7 +64,7 @@ $ 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 文章。 -接著執行： +Now run: ```bash $ hexo migrate joomla <source> diff --git a/source/zh-tw/docs/one-command-deployment.md b/source/zh-tw/docs/one-command-deployment.md index 5d4c22c822..6721152107 100644 --- a/source/zh-tw/docs/one-command-deployment.md +++ b/source/zh-tw/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 會依照順序執行每個佈署器。 +You can use multiple deployers. Hexo will execute each deployer in order. ```yaml deploy: @@ -27,17 +27,17 @@ deploy: repo: ``` -更多佈署外掛，請參照[外掛](https://hexo.io/plugins/)清單。 +Refer to the [Plugins](https://hexo.io/plugins/) list for more deployment plugins. ## Git -1. 安裝 [hexo-deployer-git]。 +1. 安裝 [hexo-deployer-git][]。 ```bash $ npm install hexo-deployer-git --save ``` -2. 修改\_config.yml設定(下面的註解顯示了參數的範例)。 +2. Edit **\_config.yml** (with example values shown below as comments): ```yaml deploy: @@ -47,23 +47,23 @@ deploy: message: [message] ``` -| 選項 | 描述 | 預設 | -| --------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -| `repo` | 儲存庫（Repository）網址 | -| `branch` | 分支名稱。 | `gh-pages` (GitHub)<br>`coding-pages` (Coding.net)<br>`master` (其他) | -| `message` | 自訂提交訊息 | `Site updated: {% raw %}{{ now('YYYY-MM-DD HH:mm:ss') }}{% endraw %}`) | -| `token` | 選填的 token 值用來儲存庫存取身份認證。以 `$` 作為前綴從環境變數中讀取 token | +| 選項 | 描述 | Default | +| --------- | ------------------------------------------------ | -------------------------------------------------------------------------------------- | +| `repo` | URL of the target repository | | +| `branch` | 分支名稱。 | `gh-pages` (GitHub)<br>`coding-pages` (Coding.net)<br>`master` (其他) | +| `message` | Customize commit message. | `<code>Site updated: {% raw %}{{ now('YYYY-MM-DD HH:mm:ss') }}{% endraw %}`)</code> | +| `token` | 選填的 token 值用來儲存庫存取身份認證。 以 `$` 作為前綴從環境變數中讀取 token | | -3. 上傳你的網站。執行 `hexo clean && hexo deploy`。 +3. 上傳你的網站。 執行 `hexo clean && hexo deploy`。 - 你將會被提示提供目標儲存庫的使用者名稱及密碼，除非你用 token 或是 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) 來暫時儲存它們。 -4. 在 Github / BitBucket / Gitlab 前往你的儲存庫設定，並將你的主要分支從 `master` 設為 `gh-pages`（或者任何你在 \_config.yml 中設定的名字)。現在你的網站就是你的帳號首頁。 +4. 在 Github / BitBucket / Gitlab 前往你的儲存庫設定，並將你的主要分支從 `master` 設為 `gh-pages`（或者任何你在 \_config.yml 中設定的名字)。 The deployed site should be live on the link shown on the "Pages" setting. ## Heroku -安裝 [hexo-deployer-heroku]。 +安裝 [hexo-deployer-heroku][]。 ```bash $ npm install hexo-deployer-heroku --save @@ -78,14 +78,24 @@ deploy: message: [message] ``` -| 選項 | 描述 | -| --------- | ------------------------------------------------------------------------------------------- | -| `repo` | Heroku 儲存庫網址 | -| `message` | 自訂提交訊息 (預設是 `Site updated: {% raw %}{{ now('YYYY-MM-DD HH:mm:ss') }}{% endraw %}`) | +| 選項 | 描述 | +| -------------------- | ---------------------------------------------------------------------------------- | +| `repo`, `repository` | Heroku 儲存庫網址 | +| `message` | 自訂提交訊息 (預設是 `Site updated: {% raw %}{{ now('YYYY-MM-DD HH:mm:ss') }}{% endraw %}`) | + +## 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. + +There are two different ways to deploy your sites on Netlify. The most common way is to use the web UI. Go to the [create a new site page](https://app.netlify.com/start), select your project repo from GitHub, GitLab, or Bitbucket, and follow the prompts. + +Alternatively, you can use Netlify's [Node based CLI](https://www.netlify.com/docs/cli/) tool to manage and deploy sites on Netlify without leaving your terminal. + +You can also add a [Deploy to Netlify Button](https://www.netlify.com/docs/deploy-button/) in your README.file to allow others to create a copy of your repository and be deployed to Netlify via one click. ## Rsync -安裝 [hexo-deployer-rsync]。 +安裝 [hexo-deployer-rsync][]。 ```bash $ npm install hexo-deployer-rsync --save @@ -105,15 +115,15 @@ deploy: ignore_errors: [true|false] ``` -| 選項 | 描述 | 預設值 | -| --------------- | ---------------------- | ------ | -| `host` | 遠端主機的位址 | -| `user` | 使用者名稱 | -| `root` | 遠端主機的根目錄 | -| `port` | 連接埠 | 22 | -| `delete` | 刪除遠端主機上的舊檔案 | true | -| `verbose` | 顯示除錯訊息 | true | -| `ignore_errors` | 忽略錯誤 | false | +| 選項 | 描述 | Default | +| --------------- | ------------------------ | ------- | +| `host` | 遠端主機的位址 | | +| `user` | 使用者名稱 | | +| `root` | 遠端主機的根目錄 | | +| `port` | Port | 22 | +| `delete` | 刪除遠端主機上的舊檔案 | true | +| `verbose` | Display verbose messages | true | +| `ignore_errors` | 忽略錯誤 | false | ## OpenShift @@ -121,7 +131,7 @@ deploy: `hexo-deployer-openshift` 在 2022 時已被棄用。 {% endnote %} -安裝 [hexo-deployer-openshift]。 +安裝 [hexo-deployer-openshift][]。 ```bash $ npm install hexo-deployer-openshift --save @@ -136,14 +146,14 @@ deploy: message: [message] ``` -| 選項 | 描述 | -| --------- | ------------------------------------------------------------------------------------------- | -| `repo` | OpenShift 儲存庫網址 | +| 選項 | 描述 | +| --------- | ---------------------------------------------------------------------------------- | +| `repo` | OpenShift 儲存庫網址 | | `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 @@ -163,19 +173,55 @@ deploy: verbose: [true|false] ``` -| 選項 | 描述 | 預設值 | -| --------- | ---------------------------------------- | ------ | -| `host` | 遠端主機位址 | -| `user` | 使用者名稱 | -| `pass` | 密碼 | -| `remote` | 遠端主機的根目錄 | `/` | -| `port` | 連接埠 | 21 | -| `clear` | 在上傳之前，移除遠端目錄中所有檔案及目錄 | false | -| `verbose` | 顯示除錯訊息 | false | +| 選項 | 描述 | Default | +| --------- | ------------------------ | ------- | +| `host` | 遠端主機位址 | | +| `user` | 使用者名稱 | | +| `pass` | 密碼 | | +| `remote` | 遠端主機的根目錄 | `/` | +| `port` | Port | 21 | +| `clear` | 在上傳之前，移除遠端目錄中所有檔案及目錄 | false | +| `verbose` | Display verbose messages | false | + +## SFTP + +Install [hexo-deployer-sftp][]. Deploys the site via SFTP, allowing for passwordless connections using ssh-agent. + +```bash +$ npm install hexo-deployer-sftp --save +``` + +預設值 + +```yaml +deploy: + type: sftp + host: <host> + user: <user> + pass: <password> + remotePath: [remote path] + port: [port] + privateKey: [path/to/privateKey] + passphrase: [passphrase] + agent: [path/to/agent/socket] +``` + +| Option | 描述 | Default | +| ------------- | ----------------------------------------------- | ---------------- | +| `host` | Address of remote host | | +| `port` | Port | 22 | +| `user` | Username | | +| `pass` | Password | | +| `privateKey` | Path to a ssh private key | | +| `passphrase` | Optional passphrase for the private key | | +| `agent` | Path to the ssh-agent socket | `$SSH_AUTH_SOCK` | +| `remotePath` | Root directory of remote host | `/` | +| `forceUpload` | Override existing files | false | +| `concurrency` | Max number of SFTP tasks processed concurrently | 100 | ## Vercel -[Vercel](https://vercel.com) 是一個雲端平台讓開發者可以架設 Jamstack 網站以及網路服務，且可以快速佈署、自動調整大小 (auto scaling)，且不須監督、無須設定。他們提供全球邊緣網路、SSL 加密、資產壓縮、快取無效化等服務。 +[Vercel](https://vercel.com) 是一個雲端平台讓開發者可以架設 Jamstack 網站以及網路服務，且可以快速佈署、自動調整大小 (auto scaling)，且不須監督、無須設定。 他們提供全球邊緣網路、SSL 加密、資產壓縮、快取無效化等服務。 第一步：新增一個建構腳本至到你的 `package.json` 檔案： @@ -191,19 +237,19 @@ deploy: 為了使用 [Vercel for Git Integration](https://vercel.com/docs/git-integrations) 佈署你的 Hexo 應用程式，請確認它已推送到 Git 儲存庫中。 -使用 [Import Flow](https://vercel.com/import/git) 輸入專案到 Vercel 中。在輸入期間，你可以找到所有有關的選項已預先為你進行設定；然而，你可以選擇更改任何選項，你可以在[這裡](https://vercel.com/docs/build-step#build-&-development-settings)找到選項清單。 +使用 [Import Flow](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)。 -或者，你可以點擊下方的佈署按鈕來建立一個新專案： +Follow the prompts, where you'll be asked which domain you'd like to deploy to. Bip will detect that you're using Hexo, and set project settings like the source file directory automatically. [![Deploy Vercel](https://vercel.com/button)](https://vercel.com/new/hexo) ## Bip -[Bip](https://bip.sh) 是一個商業架設服務並提供不斷線佈署，專為靜態網頁提供全球 CDN、SSL、無限頻寬等服務。提供實支實付 (pay as you go) 的方案，以一個網域為單位。 +[Bip](https://bip.sh) 是一個商業架設服務並提供不斷線佈署，專為靜態網頁提供全球 CDN、SSL、無限頻寬等服務。 提供實支實付 (pay as you go) 的方案，以一個網域為單位。 -Getting started is quick and easy, as Bip provides out the box support for Hexo. This guide assumes you already have [a Bip domain and Bip CLI installed](https://bip.sh/getstarted). +Getting started is quick and easy, as Bip provides out the box support for Hexo. This guide assumes you already have [a Bip domain and Bip CLI installed](https://bip.sh/getstarted). This guide assumes you already have [a Bip domain and Bip CLI installed](https://bip.sh/getstarted). 1: Initialise your project directory @@ -229,7 +275,7 @@ After a few moments, your website will be deployed. [RSS3](https://rss3.io) 是一個為 Web 3.0 時代的內容和社交網路設計的開放協議。 -1. 安裝 [hexo-deployer-rss3] +1. 安裝 [hexo-deployer-rss3][] 2. 修改配置。 @@ -246,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 網關相關的驗證內容 | +| 參數 | Description | +| ----------------- | --------------- | +| `endpoint` | 一個 RSS3 Hub 的鏈接 | +| `privateKey` | 您的私鑰， 64 字節 | +| `ipfs/deploy` | 是否部署到 IPFS 上 | +| `ipfs/gateway` | IPFS API 網關 | +| `ipfs/api/key` | IPFS 網關相關的驗證內容 | +| `ipfs/api/secret` | IPFS 網關相關的驗證內容 | 3. 生成靜態文件 @@ -261,13 +307,40 @@ deploy: # 所有部署器的根配置塊 關於具體部署相關的註意事項，您可以參閱 [我們的文檔](https://github.com/NaturalSelectionLabs/hexo-deployer-rss3/tree/develop/docs/zh_TW/start.md) 。 +## Edgio (formerly Layer0) + +[Edgio (formerly Layer0)](https://docs.edg.io) is an Internet-scale platform that makes it easy for teams to build, release, protect, and accelerate their web apps and APIs. + +1. In your hexo project directory, install the Edgio CLI: + +```bash +npm i -g @edgio/cli +``` + +2. Install Hexo connector by Edgio: + +```bash +edgio init --connector=@edgio/hexo +``` + +3. 預設 + +```bash +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` 資料夾，您可以將它們拷貝到您喜歡的地方。 +All generated files are saved in the `public` folder. 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 [hexo-deployer-rsync]: https://github.com/hexojs/hexo-deployer-rsync [hexo-deployer-openshift]: https://github.com/hexojs/hexo-deployer-openshift [hexo-deployer-ftpsync]: https://github.com/hexojs/hexo-deployer-ftpsync +[hexo-deployer-sftp]: https://github.com/lucascaro/hexo-deployer-sftp [hexo-deployer-rss3]: https://github.com/NaturalSelectionLabs/hexo-deployer-rss3 diff --git a/source/zh-tw/docs/permalinks.md b/source/zh-tw/docs/permalinks.md index c04fba78a6..3f80cd0dd5 100644 --- a/source/zh-tw/docs/permalinks.md +++ b/source/zh-tw/docs/permalinks.md @@ -1,29 +1,29 @@ --- -title: 永久連結（Permalinks） +title: Permalinks --- -您可以在設定中調整網站的永久連結。 +You can specify the permalinks for your site in `_config.yml` or in the front-matter for each post. ### 變數 除了下列變數外，您還可使用除了 `:path` 和 `:permalink` 之外 Front-matter 中的所有屬性。 -| 變數 | 描述 | -| ------------- | --------------------------------------------------------------------------- | -| `:year` | 文章的發表年份（4 位數） | -| `:month` | 文章的發表月份（2 位數） | -| `:i_month` | 文章的發表月份（去掉開頭的零） | -| `:day` | 文章的發表日期 (2 位數) | -| `:i_day` | 文章的發表日期（去掉開頭的零） | -| `:hour` | 文章發表時的小時 (2 位數) | -| `:minute` | 文章發表時的分鐘 (2 位數) | -| `:second` | 文章發表時的秒鐘 (2 位數) | +| 變數 | 描述 | +| ------------- | ------------------------------------------------------------------------- | +| `:year` | 文章的發表年份（4 位數） | +| `:month` | Published month of posts (2-digit) | +| `:i_month` | 文章的發表月份（去掉開頭的零） | +| `:day` | Published day of posts (2-digit) | +| `:i_day` | Published day of posts (Without leading zeros) | +| `:hour` | Published hour of posts (2-digit) | +| `:minute` | Published minute of posts (2-digit) | +| `:second` | Published second of posts (2-digit) | | `:title` | 檔案名稱 (relative to "source/\_posts/" folder) | -| `:name` | 檔案名稱 | -| `:post_title` | 文章標題 | +| `:name` | 檔案名稱 | +| `:post_title` | 文章標題 | | `:id` | 文章 ID (_not persistent across [cache reset](/zh-tw/docs/commands#clean)_) | -| `:category` | 分類。如果文章沒有分類，則是 `default_category` 設定。 | -| `:hash` | SHA1 hash of filename (same as `:title`) and date (12-hexadecimal) | +| `:category` | 分類。 如果文章沒有分類，則是 `default_category` 設定。 | +| `:hash` | SHA1 hash of filename (same as `:title`) and date (12-hexadecimal) | 您可在 `permalink_defaults` 設定中調整永久連結中各變數的預設值： @@ -42,7 +42,7 @@ categories: - bar ``` -| 設定 | 結果 | +| 設定 | 結果 | | ------------------------------- | --------------------------- | | `: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 ``` -| 設定 | 結果 | +| 設定 | 結果 | | --------------------------- | ----------------------------- | | `:year/:month/:day/:title/` | 2013/07/14/lorem/hello-world/ | | `:year/:month/:day/:name/` | 2013/07/14/hello-world/ | diff --git a/source/zh-tw/docs/plugins.md b/source/zh-tw/docs/plugins.md index a74da4b92e..d6f52903a3 100644 --- a/source/zh-tw/docs/plugins.md +++ b/source/zh-tw/docs/plugins.md @@ -1,26 +1,27 @@ --- -title: 外掛 +title: Plugins --- -Hexo 有強大的外掛系統，使您能輕鬆擴展功能而不用修改核心模組的原始碼。在 Hexo 中有兩種形式的外掛： +Hexo 有強大的外掛系統，使您能輕鬆擴展功能而不用修改核心模組的原始碼。 在 Hexo 中有兩種形式的外掛： ### 腳本（Scripts） -如果您的程式碼很簡單，建議您撰寫腳本，您只需要把 JavaScript 檔案放到 `scripts` 資料夾，在啟動時就會自動載入一次。 +If your plugin is relatively simple, it's recommended to use a script. 首先，在 `node_modules` 資料夾中建立資料夾，資料夾名稱開頭必須為 `hexo-`，如此一來 Hexo 才會在啟動時載入。 -### 套件（Packages） +### Plugin -如果您的程式碼較複雜，或是您想要發佈到 NPM 上，建議您撰寫套件。首先，在 `node_modules` 資料夾中建立資料夾，資料夾名稱開頭必須為 `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` 屬性，例如： +`package.json` 中至少要包含 `name`, `version`, `main` 屬性，例如： For example: ```json package.json { @@ -30,40 +31,44 @@ 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][]：產生分頁資料 -### 發佈 +### Publishing -當您完成外掛後，可以考慮將它發佈到 [外掛列表](/plugins)，讓更多人能夠使用您的外掛。發佈外掛的步驟和 [更新文件](contributing.html#更新文件) 非常類似。 +當您完成外掛後，可以考慮將它發佈到 [外掛列表](/plugins)，讓更多人能夠使用您的外掛。 發佈外掛的步驟和 [更新文件](contributing.html#更新文件) 非常類似。 -1. Fork [hexojs/site] -2. 把檔案庫（repository）複製到電腦上，並安裝相依套件。 +1. Fork [hexojs/site][] +2. Clone the repository to your computer and install dependencies. - {% code %} - $ git clone https://github.com/<username>/site.git - $ cd site - $ npm install - {% endcode %} + ```shell + /site.git +$ cd site +$ npm install + ``` 3. 編輯 `source/_data/plugins.yml`，在檔案中新增您的外掛，例如： - {% code %} +4. Edit `source/_data/plugins/<your-plugin-name>.yml` and add your plugin. For example: - - name: hexo-server - description: Server module for Hexo. - link: https://github.com/hexojs/hexo-server - tags: - official - server - console - {% endcode %} + ```yaml + description: Server module for Hexo. + name: hexo-server +description: Server module for Hexo. +link: https://github.com/hexojs/hexo-server +tags: - official - server - console + ``` -4. 推送（push）分支。 -5. 建立一個新的合併申請（pull request）。 +5. 推送（push）分支。 +6. Create a pull request and describe the change. [hexo-fs]: https://github.com/hexojs/hexo-fs [hexo-util]: https://github.com/hexojs/hexo-util diff --git a/source/zh-tw/docs/server.md b/source/zh-tw/docs/server.md index 987801331a..159111f4df 100644 --- a/source/zh-tw/docs/server.md +++ b/source/zh-tw/docs/server.md @@ -2,15 +2,15 @@ title: Server --- -## [hexo-server] +## [hexo-server][] -Hexo 3 把伺服器獨立成個別模組，您必須先安裝 [hexo-server] 才能使用。 +With the release of Hexo 3, the server has been separated from the main module. Hexo 3 把伺服器獨立成個別模組，您必須先安裝 [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. Your website will run at `http://localhost:4000` by default. When the server is running, Hexo will watch for file changes and update automatically so it's not necessary to manually restart the server. ```bash $ hexo server @@ -24,7 +24,7 @@ $ hexo server -p 5000 ### 靜態模式 -在靜態模式下，伺服器只會處理 `public` 資料夾內的檔案，而且不會處理檔案變動，在執行時，您應該先自行執行 `hexo generate`，此模式通常用於生產環境（production）下。 +In static mode, only files in the `public` folder will be served and file watching is disabled. 在靜態模式下，伺服器只會處理 `public` 資料夾內的檔案，而且不會處理檔案變動，在執行時，您應該先自行執行 `hexo generate`，此模式通常用於生產環境（production）下。 Usually used in production. ```bash $ hexo server -s @@ -32,7 +32,7 @@ $ hexo server -s ### 自定 IP -伺服器預設運作在 `0.0.0.0`，您可以覆蓋預設的 IP 設定。 +Hexo runs the server at `0.0.0.0` by default. You can override the default IP setting. ```bash $ hexo server -i 192.168.1.1 diff --git a/source/zh-tw/docs/setup.md b/source/zh-tw/docs/setup.md index 228d386bb7..9b89a69e40 100644 --- a/source/zh-tw/docs/setup.md +++ b/source/zh-tw/docs/setup.md @@ -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/) renderer 已預設安裝，您可以稍後移除。 +Application data. [EJS](https://ejs.co/), [Stylus](http://learnboost.github.io/stylus/) 和 [Markdown](http://daringfireball.net/projects/markdown/) renderer 已預設安裝，您可以稍後移除。 If you want, you can uninstall them later. ```json package.json { @@ -58,12 +59,12 @@ $ npm install ### scaffolds -[鷹架](writing.html#鷹架（Scaffold）) 資料夾。當您建立新文章時，Hexo 會根據 scaffold 來建立檔案。 +[鷹架](writing.html#鷹架（Scaffold）) 資料夾。 當您建立新文章時，Hexo 會根據 scaffold 來建立檔案。 ### source -原始檔案資料夾是放置內容的地方。檔案 / 資料夾名稱開頭為 `_` (底線) 和隱藏檔案會被忽略，除了 `_posts` 資料夾以外。Markdown 和 HTML 檔案會被處理並放到 `public` 資料夾，而其他檔案會被拷貝過去。 +Source folder. 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-tw/docs/syntax-highlight.md b/source/zh-tw/docs/syntax-highlight.md index 65df3fdf7b..ca294fe919 100644 --- a/source/zh-tw/docs/syntax-highlight.md +++ b/source/zh-tw/docs/syntax-highlight.md @@ -2,7 +2,7 @@ title: Syntax Highlighting --- -Hexo has two built-in syntax highlight libraries, [highlight.js](https://github.com/highlightjs/highlight.js) and [prismjs](https://github.com/PrismJS/prism). This tutorial shows you how to integrate Hexo's built-in syntax highlight into your template. +Hexo has two built-in syntax highlight libraries, [highlight.js](https://github.com/highlightjs/highlight.js) and [prismjs](https://github.com/PrismJS/prism). This tutorial shows you how to integrate Hexo's built-in syntax highlight into your template. This tutorial shows you how to integrate Hexo's built-in syntax highlight into your template. ## How to use code block in posts @@ -21,12 +21,10 @@ code snippet code snippet ``` ```` - -The third syntax is a Markdown's fenced code block syntax and Hexo extends it to support more features. Check out [Tag Plugin Docs](tag-plugins#Code-Block) to find out options available. - -> Tip: Hexo support posts written in any format, so long the corresponding renderer plugin is installed. 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. - +The third syntax is Markdown's fenced code block syntax, and Hexo extends it to support more features. The third syntax is a Markdown's fenced code block syntax and Hexo extends it to support more features. Check out [Tag Plugin Docs](tag-plugins#Code-Block) to find out options available. +> Tip: Hexo support posts written in any format, so long the corresponding renderer plugin is installed. 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. 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. ## Configuration +below v7.0.0: ```yaml # _config.yml @@ -49,10 +47,33 @@ prismjs: tab_replace: '' ``` +v7.0.0+: + +```yaml +# _config.yml +syntax_highlighter: highlight.js +highlight: + auto_detect: false + line_number: true + line_threshold: 0 + tab_replace: "" + exclude_languages: + - example + wrap: true + hljs: false +prismjs: + preprocess: true + line_number: true + line_threshold: 0 + tab_replace: "" +``` + The YAML above is Hexo's default configuration. ## Disabled +below v7.0.0: + ```yaml # _config.yml highlight: @@ -61,7 +82,14 @@ prismjs: enable: false ``` -When both `highlight.enable` and `prismjs.enable` are `false`, the output HTML of the code block is controlled by the corresponding renderer. For example, [`marked.js`](https://github.com/markedjs/marked) (used by [`hexo-renderer-marked`](https://github.com/hexojs/hexo-renderer-marked), the default markdown renderer of Hexo) will add the language code to the `class` of `<code>`: +v7.0.0+: + +```yaml +# _config.yml +syntax_highlighter: # empty +``` + +When both `highlight.enable` and `prismjs.enable` are `false`, the output HTML of the code block is controlled by the corresponding renderer. For example, [`marked.js`](https://github.com/markedjs/marked) (used by [`hexo-renderer-marked`](https://github.com/hexojs/hexo-renderer-marked), the default markdown renderer of Hexo) will add the language code to the `class` of `<code>`: For example, [`marked.js`](https://github.com/markedjs/marked) (used by [`hexo-renderer-marked`](https://github.com/hexojs/hexo-renderer-marked), the default markdown renderer of Hexo) will add the language code to the `class` of `<code>`: ````markdown ```yaml @@ -79,6 +107,8 @@ When no built-in syntax highlight is enabled, you can either install third-party ## Highlight.js +below v7.0.0: + ```yaml # _config.yml highlight: @@ -95,6 +125,22 @@ prismjs: enable: false ``` +v7.0.0+: + +```yaml +# _config.yml +syntax_highlighter: highlight.js +highlight: + auto_detect: false + line_number: true + line_threshold: 0 + tab_replace: " " + exclude_languages: + - example + wrap: true + hljs: false +``` + `highlight.js` is enabled by default and used as server-side highlighting in Hexo; it needs to be disabled if you prefer to run `highlight.js` on browser-side. > Server-side means, the syntax highlight is generated during `hexo generate` or `hexo server`. @@ -105,8 +151,8 @@ prismjs: > Tip: When you want to use "sublanguage highlight", enable `auto_detect` and don't mark language when writing code block. -{% note warn "Warning!" %} -`auto_detect` is very resource-intensive. Do not enable it unless you really need "sublanguage highlight" or prefer not to mark language when writing code block. +{% note warn "Warning!" %} %} +`auto_detect` is very resource-intensive. `auto_detect` is very resource-intensive. Do not enable it unless you really need "sublanguage highlight" or prefer not to mark language when writing code block. {% endnote %} ### line_number @@ -138,11 +184,11 @@ You might also notice that all `class` has no `hljs-` prefixed, we will revisit ### line_threshold (+6.1.0) -Accepts an optional threshold to only show line numbers as long as the numbers of lines of the code block exceed such threshold. Default is `0`. +Accepts an optional threshold to only show line numbers as long as the numbers of lines of the code block exceed such threshold. Default is `0`. Default is `0`. ### tab_replace -Replace tabs inside code block with given string. By default it is 2 spaces. +Replace tabs inside code block with given string. By default it is 2 spaces. By default it is 2 spaces. ### exclude_languages (+6.1.0) @@ -150,7 +196,7 @@ Only wrap with `<pre><code class="lang"></code></pre>` and will not render all t ### wrap -Hexo _wraps_ the output inside `<figure>` and `<table>` to support line number. You need to disable **both** `line_number` and `wrap` to revert to `highlight.js`'s behavior: +Hexo _wraps_ the output inside `<figure>` and `<table>` to support line number. You need to disable **both** `line_number` and `wrap` to revert to `highlight.js`'s behavior: You need to disable **both** `line_number` and `wrap` to revert to `highlight.js`'s behavior: ```html <pre><code class="yaml"> @@ -159,7 +205,7 @@ Hexo _wraps_ the output inside `<figure>` and `<table>` to support line number. </code></pre> ``` -{% note warn "Warning!" %} +{% note warn "Warning!" %} %} 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 %} @@ -178,6 +224,8 @@ When `hljs` is set to `true`, all the HTML output will have `class` prefixed wit ## PrismJS +below v7.0.0: + ```yaml # _config.yml highlight: @@ -190,37 +238,45 @@ prismjs: tab_replace: "" ``` -Prismjs is disabled by default. You should set `highlight.enable` to `false` before enabling prismjs. +v7.0.0+: + +```yaml +Prismjs is disabled by default. You should set <code>highlight.enable</code> to <code>false</code> before enabling prismjs. +``` + to false before enabling prismjs. +</code> + +Prismjs is disabled by default. You should set `highlight.enable` to `false` (below v7.0.0) or set `syntax_highlighter` to `prismjs` (v7.0.0+) before enabling prismjs. ### preprocess Hexo's built-in prismjs supports both browser-side (`preprocess` set to `false`) and server-side (`preprocess` set to `true`). -When use server-side mode (set `preprocess` to `true`), you only need to include prismjs theme (css stylesheet) in your website. When use browser-side (set `preprocess` to `false`), you have to include the javascript library as well. +When use server-side mode (set `preprocess` to `true`), you only need to include prismjs theme (css stylesheet) in your website. When use browser-side (set `preprocess` to `false`), you have to include the javascript library as well. When use browser-side (set `preprocess` to `false`), you have to include the javascript library as well. Prismjs is designed to be used in browser, thus under `preprocess` mode only limited prismjs plugin is supported: -- [Line Numbers](https://prismjs.com/plugins/line-numbers/): Only `prism-line-numbers.css` is required, No need to include `prism-line-numbers.js` in your website. Hexo will generate required HTML mark up mark up for you. +- [Line Numbers](https://prismjs.com/plugins/line-numbers/): Only `prism-line-numbers.css` is required, No need to include `prism-line-numbers.js` in your website. Hexo will generate required HTML mark up mark up for you. Hexo will generate required HTML mark up mark up for you. - [Show Languages](https://prismjs.com/plugins/show-language/): Hexo will always have `data-language` attribute added as long as language is given for the code block. - Any other prism plugins that don't need special HTML markup are supported as well, but you will have to include JavaScript required by those plugins. -All prism plugins are supported if `preprocess` is set to `false`. Here are a few things you should still pay attention to: +All prism plugins are supported if `preprocess` is set to `false`. Here are a few things you should still pay attention to: Here are a few things you should still pay attention to: -- [Line Numbers](https://prismjs.com/plugins/line-numbers/): Hexo won't generate required HTML mark up when `preprocess` is set to `false`. Requires both `prism-line-numbers.css` and `prism-line-numbers.js`. +- [Line Numbers](https://prismjs.com/plugins/line-numbers/): Hexo won't generate required HTML mark up when `preprocess` is set to `false`. Requires both `prism-line-numbers.css` and `prism-line-numbers.js`. Requires both `prism-line-numbers.css` and `prism-line-numbers.js`. - [Show Languages](https://prismjs.com/plugins/show-language/): Hexo will always have `data-language` attribute added as long as language is given for the code block. -- [Line Highlight](https://prismjs.com/plugins/line-highlight/): Both Hexo [Tag Plugin - Code Block](tag-plugins#Code-Block) and [Tag Plugin - Backtick Code Block](https://hexo.io/docs/tag-plugins#Backtick-Code-Block) supports Line Highlight syntax (`mark` option). When `mark` option is given, Hexo will generate the corresponding HTML markup. +- [Line Highlight](https://prismjs.com/plugins/line-highlight/): Both Hexo [Tag Plugin - Code Block](tag-plugins#Code-Block) and [Tag Plugin - Backtick Code Block](https://hexo.io/docs/tag-plugins#Backtick-Code-Block) supports Line Highlight syntax (`mark` option). When `mark` option is given, Hexo will generate the corresponding HTML markup. When `mark` option is given, Hexo will generate the corresponding HTML markup. ### line_number -With both `preprocess` and `line_number` set to `true`, you just need to include `prism-line-numbers.css` to make line-numbering work. If you set both `preprocess` and `line_number` to false, you will need both `prism-line-numbers.css` and `prism-line-numbers.js`. +With both `preprocess` and `line_number` set to `true`, you just need to include `prism-line-numbers.css` to make line-numbering work. With both `preprocess` and `line_number` set to `true`, you just need to include `prism-line-numbers.css` to make line-numbering work. If you set both `preprocess` and `line_number` to false, you will need both `prism-line-numbers.css` and `prism-line-numbers.js`. ### line_threshold (+6.1.0) -Accepts an optional threshold to only show line numbers as long as the numbers of lines of the code block exceed such threshold. Default is `0`. +Accepts an optional threshold to only show line numbers as long as the numbers of lines of the code block exceed such threshold. Default is `0`. Default is `0`. ### tab_replace -Replace `\t` inside code block with given string. By default it is 2 spaces. +Replace `\t` inside code block with given string. By default it is 2 spaces. By default it is 2 spaces. ## Other useful information diff --git a/source/zh-tw/docs/tag-plugins.md b/source/zh-tw/docs/tag-plugins.md index 04023475f2..527e9546b4 100644 --- a/source/zh-tw/docs/tag-plugins.md +++ b/source/zh-tw/docs/tag-plugins.md @@ -2,15 +2,17 @@ title: 標籤外掛（Tag Plugins） --- -標籤外掛和 Front-matter 中的標籤不同，它們是用於在文章中快速插入特定內容的外掛。 +Tag plugins are different from post tags. They are ported from Octopress and provide a useful way for you to quickly add specific content to your posts. -雖然你可以以任何格式寫你的文章，但標籤外掛會永遠可用，且語法都會相同。 +Although you can write your posts in any format, the tag plugins will always be available and syntax remains the same. + +禁止 YouTube cookie _標籤外掛不應該被包裝在 Markdown 語法當中，例如： `[]({% post_path lorem-ipsum %})` 是不支援的。_ ## 引用區塊 (Block Quote) -在文章中插入引言，可包含作者、來源和標題。 +Perfect for adding quotes to your post, with optional author, source and title information. **捷徑：** quote @@ -20,7 +22,9 @@ content {% endblockquote %} ``` -**沒有提供參數，僅輸出普通的引用區塊** +### 範例 + +**No arguments. Plain blockquote.** ``` {% blockquote %} @@ -37,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** @@ -49,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 %} **引用網路上的文章** @@ -62,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 %} @@ -70,7 +77,7 @@ Every interaction is both precious and an opportunity to delight. ## 程式碼區塊 (Code Block) -在文章中插入程式碼。 +A useful feature for adding code snippets to your post. **捷徑：** code @@ -82,16 +89,18 @@ code snippet 以 `option:value` 格式設定額外的選項，例如：`line_number:false first_line:5`。 -| 額外選項 | 說明 | 預設值 | -| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------ | -| `line_number` | 顯示行號 | `true` | -| `line_threshold` | 當程式碼區塊的行數超過臨界值時，才顯示行號。 | `0` | -| `highlight` | 啟用程式碼強調 | `true` | -| `first_line` | 設定起始的程式碼行號 | `1` | -| `mark` | 強調特定的程式碼行號，每個值會以逗點區分。特定的程式碼區間則使用破折號 (dash)<br>範例：`mark:1,4-7,10` 會標示行號 1、 4 到 7 以及 10。 | -| `wrap` | 將程式碼區塊包裝在 [`<table>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table) 中 | `true` | +| 額外選項 | 文章摘要 | Default | +| ---------------- | ----------------------------------------------------------------------------------------------- | ------- | +| `line_number` | 顯示行號 | `true` | +| `line_threshold` | Only show line numbers as long as the numbers of lines of the code block exceed such threshold. | `0` | +| `highlight` | 啟用程式碼強調 | `true` | +| `first_line` | Specify the first line number | `1` | +| `mark` | 強調特定的程式碼行號，每個值會以逗點區分。 特定的程式碼區間則使用破折號 (dash)<br>範例：`mark:1,4-7,10` 會標示行號 1、 4 到 7 以及 10。 | | +| `wrap` | 將程式碼區塊包裝在 [`<table>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table) 中 | `true` | -**普通的程式碼區塊** +### 說明 + +**A plain code block** ``` {% codeblock %} @@ -115,7 +124,7 @@ alert('Hello World!'); [rectangle setX: 10 y: 10 width: 20 height: 20]; {% endcodeblock %} -**加上說明** +**Adding a caption to the code block** ``` {% codeblock Array.map %} @@ -137,13 +146,12 @@ _.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 %} -## 反引號 (Backtick) 程式碼區塊 +## Backtick Code Block -另一種形式的程式碼區塊。 +This is identical to using a code block, but instead uses three backticks to delimit the block. {% raw %} ``[language] [title] [url] [link text] @@ -151,9 +159,9 @@ code snippet `` {% endraw %} -## 抬升式引用區塊 (Pull Quote) +## Pull Quote -在文章中插入抬升式引用區塊。 +To add pull quotes to your posts: ``` {% pullquote [class] %} @@ -164,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。 @@ -179,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] %} @@ -211,12 +219,44 @@ content ## 插入程式碼 -插入 `source/downloads/code` 資料夾內的程式檔，資料夾取決於你在設定文件中 `code_dir` 的設定。 +插入 `source/downloads/code` 資料夾內的程式檔，資料夾取決於你在設定文件中 `code_dir` 的設定。 The folder location can be specified through the `code_dir` option in the config. ``` {% include_code [title] [lang:language] path/to/file %} ``` +### 影片 + +**Embed the whole content of test.js** + +``` +{% include_code lang:javascript test.js %} +``` + +**Embed line 3 only** + +``` +{% include_code lang:javascript from:3 to:3 test.js %} +``` + +**Embed line 5 to 8** + +``` +{% include_code lang:javascript from:5 to:8 test.js %} +``` + +**Embed line 5 to the end of file** + +``` +{% include_code lang:javascript from:5 test.js %} +``` + +**Embed line 1 to 8** + +``` +{% include_code lang:javascript to:8 test.js %} +``` + ## Youtube (`v7.0.0` 中刪除) {% note warn %} @@ -229,9 +269,9 @@ content {% youtube video_id [type] [cookie] %} ``` -### 範例 +### 引用文章 -**影片** +**Embed a video** ``` {% youtube lJIrF4YjHfQ %} @@ -245,7 +285,7 @@ content **隱私模式** -禁止 YouTube cookie +YouTube's cookie is not used in this mode. ``` {% youtube lJIrF4YjHfQ false %} @@ -258,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 %} @@ -281,28 +321,27 @@ content 你可以自定義要顯示的文字，取代顯示文章的標題。 -文章標題及自定義文字預設會逸出 (escape)。你可以使用選項 `escape` 將逸出關閉。 +文章標題及自定義文字預設會逸出 (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 'Link to a post' %}{% endraw %}` {% post_link hexo-3-8-released 'Link to a post' %} -**逸出標題。** +**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' %} **不要逸出標題。** @@ -313,9 +352,9 @@ content {% post_link hexo-4-released '<b>bold</b> custom title' false %} -## 引用資產 +## Include Assets -引用文章的資產。 +Include post assets, to be used in conjunction with [`post_asset_folder`](/docs/asset-folders). ``` {% asset_path filename %} @@ -329,7 +368,7 @@ _hexo-renderer-marked 3.1.0+ 可以（可選的）自動解析文章內的圖片 "foo.jpg" 位於 `http://example.com/2020/01/02/hello/foo.jpg`。 -**預設（沒有選項）** +**Default (no option)** `{% asset_img foo.jpg %}` @@ -353,7 +392,7 @@ _hexo-renderer-marked 3.1.0+ 可以（可選的）自動解析文章內的圖片 <img src="/2020/01/02/hello/foo.jpg" width="500" height="400" /> ``` -**標題及替代文字** +**Title & Alt** `{% asset_img logo.svg "lorem ipsum'dolor'" %}` @@ -365,7 +404,7 @@ _hexo-renderer-marked 3.1.0+ 可以（可選的）自動解析文章內的圖片 ### url_for (7.0.0+) -回傳一個具有前綴根路徑 URL。輸出將會自動編碼。 +回傳一個具有前綴根路徑 URL。 輸出將會自動編碼。 ``` {% url_for text path [relative] %} @@ -386,8 +425,7 @@ root: /blog/ # 範例 <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 @@ -414,7 +452,7 @@ relative_link: true ### full_url_for (7.0.0+) -回傳一個 `config.url` 前綴的 URL。輸出將會自動編碼。 +回傳一個 `config.url` 前綴的 URL。 輸出將會自動編碼。 ``` {% full_url_for text path %} @@ -437,7 +475,7 @@ url: https://example.com/blog # 範例 ## Raw -如果您要在文章中插入 Swig 標籤，可以試著使用 Raw 標籤，以免發生解析異常。 +If certain content is causing processing issues in your posts, wrap it with the `raw` tag to avoid rendering errors. ``` {% raw %} @@ -445,9 +483,9 @@ content {% endraw %} ``` -## 文章摘要 +## Post Excerpt -使用在 `<!-- more -->` 標籤之前的文字作為為這篇文章的摘要。[front-matter](/docs/front-matter#Settings-amp-Their-Default-Values) 中的 `excerpt:` 值如果被特指的話，將會將其優先使用。 +使用在 `<!-- more -->` 標籤之前的文字作為為這篇文章的摘要。 [front-matter](/docs/front-matter#Settings-amp-Their-Default-Values) 中的 `excerpt:` 值如果被特指的話，將會將其優先使用。 **範例：** @@ -455,4 +493,6 @@ content 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. +<!-- 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. ``` diff --git a/source/zh-tw/docs/templates.md b/source/zh-tw/docs/templates.md index 44bbb9c1fa..c9a8d3bb6c 100644 --- a/source/zh-tw/docs/templates.md +++ b/source/zh-tw/docs/templates.md @@ -2,20 +2,22 @@ title: 模版 --- -模板決定了網站內容的呈現方式，每個主題至少都應包含一個 `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` 模板，以下是各頁面相對應的模板名稱： -| 模板 | 用途 | Fallback | -| ---------- | -------- | --------- | -| `index` | 首頁 | -| `post` | 文章 | `index` | -| `page` | 分頁 | `index` | -| `archive` | 彙整 | `index` | -| `category` | 分類彙整 | `archive` | -| `tag` | 標籤彙整 | `archive` | +{% youtube mb65bQ4iUc4 %} + +| 模板 | Page | Fallback | +| ---------- | ----------------- | --------- | +| `index` | 首頁 | | +| `post` | 文章 | `index` | +| `page` | 分頁 | `index` | +| `archive` | Archives | `index` | +| `category` | Category archives | `archive` | +| `tag` | Tag archives | `archive` | ## 佈局（Layout） -如果頁面結構類似，例如兩個模板都有頁首（Header）和頁尾（Footer），您可考慮透過「佈局」讓兩個模板共享相同的結構。一個佈局檔案必須要能顯示 `body` 變數的內容，如此一來模板的內容才會被顯示，舉例來說： +如果頁面結構類似，例如兩個模板都有頁首（Header）和頁尾（Footer），您可考慮透過「佈局」讓兩個模板共享相同的結構。 Every layout file should contain a `body` variable to display the contents of the template in question. 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. You can specify additional layouts in the front-matter or set it to `false` to disable it. 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> ``` -### 區域變數 +## Local Variables 您可以在模板中指定區域變數，就能在其他模板中使用。 @@ -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(){ @@ -97,13 +99,12 @@ index }); ``` -如果您使用局部模板的話，可以更簡單： +Though it may be easier to use partials: ```js <%- partial('header', {}, {cache: true}); ``` {% note warn %} -`fragment_cache()` will cache the rendered result and output the cached result to other pages. This should only be used on partials that are expected **not** to change across different pages. Otherwise, it should **not** be enabled. -For example, it should be disabled when `relative_link` is enabled in the config. This is because relative links may appear differently across pages. +`fragment_cache()` will cache the rendered result and output the cached result to other pages. This should only be used on partials that are expected **not** to change across different pages. Otherwise, it should **not** be enabled. For example, it should be disabled when `relative_link` is enabled in the config. This is because relative links may appear differently across pages. This should only be used on partials that are expected **not** to change across different pages. Otherwise, it should **not** be enabled. For example, it should be disabled when `relative_link` is enabled in the config. This is because relative links may appear differently across pages. {% endnote %} diff --git a/source/zh-tw/docs/themes.md b/source/zh-tw/docs/themes.md index 1d8f249fc7..f27b7d7074 100644 --- a/source/zh-tw/docs/themes.md +++ b/source/zh-tw/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,60 +18,62 @@ title: 主題 ### \_config.yml -主題的配置檔案。Unlike the site's primary configuration file, 主題的配置檔案修改時會自動更新，無需重啟 Hexo 伺服器。 +主題的配置檔案。 Unlike the site's primary configuration file, 主題的配置檔案修改時會自動更新，無需重啟 Hexo 伺服器。 ### 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 -EJS: layout.ejs -Swig: layout.swig +layout.ejs - uses EJS +layout.njk - uses Nunjucks ``` 您可參考 [模板](templates.html) 以獲得更多資訊。 ### scripts -腳本資料夾。在啟動時，Hexo 會載入此資料夾內的 JavaScript 檔案，請參見 [外掛](plugins.html) 以獲得更多資訊。 +Script folder. Hexo will automatically load all JavaScript files in this folder during initialization. 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. -### 發佈 +### Publishing -當您完成主題後，可以考慮將它發佈到 [主題列表](/themes)，讓更多人能夠使用您的主題，在發佈前建議先進行 [主題單元測試](https://github.com/hexojs/hexo-theme-unit-test)，確保每一項功能都能正常運作。發佈主題的步驟和 [更新文件](contributing.html#更新文件) 非常類似。 +When you have finished building your theme, you can publish it to the [theme list](/themes). 當您完成主題後，可以考慮將它發佈到 [主題列表](/themes)，讓更多人能夠使用您的主題，在發佈前建議先進行 [主題單元測試](https://github.com/hexojs/hexo-theme-unit-test)，確保每一項功能都能正常運作。 發佈主題的步驟和 [更新文件](contributing.html#更新文件) 非常類似。 -1. Fork [hexojs/site] -2. 把檔案庫（repository）複製到電腦上，並安裝相依套件。 +1. Fork [hexojs/site][] +2. Clone the repository to your computer and install dependencies. - {% code %} - $ git clone https://github.com/<username>/site.git - $ cd site - $ npm install - {% endcode %} + ```shell + /site.git +$ cd site +$ npm install + ``` 3. 編輯 `source/_data/themes.yml`，在檔案中新增您的主題，例如： - {% code %} +4. Edit `source/_data/themes/<your-theme-name>.yml` and add your theme. For example: - - name: landscape - description: A brand new default theme for Hexo. - link: https://github.com/hexojs/hexo-theme-landscape - preview: http://hexo.io/hexo-theme-landscape - tags: - official - responsive - widget - two_column - one_column - {% endcode %} + ```yaml + description: A brand new default theme for Hexo. + name: landscape +description: A brand new default theme for Hexo. +link: https://github.com/hexojs/hexo-theme-landscape +preview: http://hexo.io/hexo-theme-landscape +tags: - official - responsive - widget - two_column - one_column + ``` -4. 在 `source/themes/screenshots` 新增同名的截圖檔案，圖片必須為 800x500 的 PNG 檔案。 -5. 推送（push）分支。 -6. 建立一個新的合併申請（pull request）。 +5. 在 `source/themes/screenshots` 新增同名的截圖檔案，圖片必須為 800x500 的 PNG 檔案。 It must be a 800\*500px PNG. +6. 推送（push）分支。 +7. Create a pull request and describe the change. [EJS]: https://github.com/hexojs/hexo-renderer-ejs [Pug]: https://github.com/hexojs/hexo-renderer-pug diff --git a/source/zh-tw/docs/troubleshooting.md b/source/zh-tw/docs/troubleshooting.md index e3877c0b20..23500ad800 100644 --- a/source/zh-tw/docs/troubleshooting.md +++ b/source/zh-tw/docs/troubleshooting.md @@ -2,7 +2,7 @@ title: 解決問題 --- -在使用 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,7 +28,7 @@ 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 @@ -55,13 +55,13 @@ To override the limit: # '*' applies to all users and '-' set both soft and hard limits ``` -- The above setting may not apply in some cases, ensure "/etc/pam.d/login" and "/etc/pam.d/lightdm" have the following line. (Ignore this step if those files do not exist) +- The above setting may not apply in some cases, ensure "/etc/pam.d/login" and "/etc/pam.d/lightdm" have the following line. (Ignore this step if those files do not exist) (Ignore this step if those files do not exist) ``` session required pam_limits.so ``` -2. If you are on a [systemd-based](https://en.wikipedia.org/wiki/Systemd#Adoption) distribution, systemd may override "limits.conf". To set the limit in systemd, add the following line in "/etc/systemd/system.conf" and "/etc/systemd/user.conf": +2. If you are on a [systemd-based](https://en.wikipedia.org/wiki/Systemd#Adoption) distribution, systemd may override "limits.conf". If you are on a [systemd-based](https://en.wikipedia.org/wiki/Systemd#Adoption) distribution, systemd may override "limits.conf". To set the limit in systemd, add the following line in "/etc/systemd/system.conf" and "/etc/systemd/user.conf": ``` DefaultLimitNOFILE=10000 @@ -69,37 +69,88 @@ DefaultLimitNOFILE=10000 3. Reboot +## Process Out of Memory + +When you encounter this error during generation: + +``` +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 + ```plain fatal: 'username.github.io' does not appear to be a git repository ``` 請確認您已經在電腦上 [設定 git](https://help.github.com/articles/set-up-git)，或改用 HTTPS 儲存庫（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` + ## 伺服器問題 ```plain Error: listen EADDRINUSE ``` -您可能同時開啟兩個 Hexo 伺服器，或者有其他應用程式正在佔用相同的連接埠，請試著修改 `port` 設定，或是在啟動 Hexo 伺服器時加上 `-p` 選項。 +You may have started two Hexo servers at the same time or there might be another application using the same port. Try to modify the `port` setting or start the Hexo server with the `-p` flag. ```bash $ hexo server -p 5000 ``` -## 外掛安裝問題 +## Plugin Installation Problems ```plain npm ERR! node-waf configure build ``` -當您試著安裝以 C/C++ 或其他非 JavaScript 語言所撰寫的外掛時，可能會遭遇此問題，請確認您已經在電腦上安裝相對應的編譯器。 +This error may occur when trying to install a plugin written in C, C++ or other non-JavaScript languages. Make sure you have installed the right compiler on your computer. + +## Error with DTrace (Mac OS X) + +```plain +{ [Error: Cannot find module './build/Release/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' } +{ [Error: Cannot find module './build/default/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' } +{ [Error: Cannot find module './build/Debug/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' } +``` + +DTrace install may have issue, use this: + +```sh +您可能同時開啟兩個 Hexo 伺服器，或者有其他應用程式正在佔用相同的連接埠，請試著修改 <code>port</code> 設定，或是在啟動 Hexo 伺服器時加上 <code>-p</code> 選項。 +``` + 設定，或是在啟動 Hexo 伺服器時加上 -p 選項。 +</code> + +See [#1326](https://github.com/hexojs/hexo/issues/1326#issuecomment-113871796) ## 在 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() %} @@ -108,16 +159,27 @@ 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 ``` -## 脫逸（Escape）內容 +## No command is executed + +When you can't get any command except `help`, `init` and `version` to work and you keep getting content of `hexo help`, it could be caused by a missing `hexo` in `package.json`: + +```json +{ + "hexo": { + "version": "3.2.2" + } +} +``` + +## Escape Contents -Hexo 使用 [Nunjucks] 來解析文章（舊版本使用 [Swig]，兩者語法類似），內容若包含 `{{ }}` 或 `{% %}` 可能導致解析錯誤，您可以用 [`raw`](/docs/tag-plugins#Raw) 標籤包裹，single backtick `` `{{ }}` `` 或 triple backtick 來避免潛在問題發生。 -Alternatively, Nunjucks tags can be disabled through the renderer's option (if supported), [API](/api/renderer#Disable-Nunjucks-tags) or [front-matter](/docs/front-matter). +Hexo 使用 [Nunjucks][] 來解析文章（舊版本使用 [Swig][]，兩者語法類似），內容若包含 `{{ }}` 或 `{% %}` 可能導致解析錯誤，您可以用 [`raw`](/docs/tag-plugins#Raw) 標籤包裹，single backtick `` `{{ }}` `` 或 triple backtick 來避免潛在問題發生。 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. Alternatively, Nunjucks tags can be disabled through the renderer's option (if supported), [API](/api/renderer#Disable-Nunjucks-tags) or [front-matter](/docs/front-matter). ``` {% raw %} @@ -155,25 +217,77 @@ When running `$ hexo server` in a BashOnWindows environment, it returns the foll Error: watch /path/to/hexo/theme/ EMPERM ``` -Unfortunately, WSL does not currently support filesystem watchers. Therefore, the live updating feature of hexo's server is currently unavailable. You can still run the server from a WSL environment by first generating the files and then running it as a static server: +Unfortunately, WSL does not currently support filesystem watchers. Therefore, the live updating feature of hexo's server is currently unavailable. You can still run the server from a WSL environment by first generating the files and then running it as a static server: Therefore, the live updating feature of hexo's server is currently unavailable. You can still run the server from a WSL environment by first generating the files and then running it as a static server: ```sh $ hexo generate $ hexo server -s ``` -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). +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. 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). ## Template render error Sometimes when running the command `$ hexo generate` it returns an error: ``` -FATAL Something's wrong. Maybe you can find the solution here: http://hexo.io/docs/troubleshooting.html +FATAL Something's wrong. FATAL Something's wrong. Maybe you can find the solution here: http://hexo.io/docs/troubleshooting.html Template render error: (unknown path) ``` -One possible reason is that there are some unrecognizable words in your file, e.g. invisible zero width characters. +Possible cause: + +- One possible reason is that there are some unrecognizable words in your file, e.g. invisible zero width characters. +- 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)) + +Upgrading to `hexo^6.1.0` from an older version may cause the following error when running `$ hexo generate`: + +``` +YAMLException: Specified list of YAML types (or a single Type object) contains a non-Type object. + at ... +``` + +This may be caused by an incorrect dependency(i.e. `js-yaml`) setting that can't be solved automatically by the package manager, and you may have to update it manually running: + +```sh +npm ERR! node-waf configure build +``` + +or + +```sh +$ yarn add js-yaml@latest +``` + +if you use `yarn`. [Warehouse]: https://github.com/hexojs/warehouse [Swig]: https://node-swig.github.io/swig-templates/ diff --git a/source/zh-tw/docs/variables.md b/source/zh-tw/docs/variables.md index 0ec6de7e72..6b4ce739bb 100644 --- a/source/zh-tw/docs/variables.md +++ b/source/zh-tw/docs/variables.md @@ -2,90 +2,100 @@ title: 變數 --- -### 全局變數 - -| 變數 | 描述 | -| -------- | ------------------------------------------------ | -| `site` | [網站變數](#網站變數) | -| `page` | 針對該頁面的資訊以及 front-matter 所設定的變數。 | -| `config` | 網站配置 | -| `theme` | 主題配置。繼承自網站配置。 | -| `path` | 目前頁面的路徑（不含根路徑） | -| `url` | 目前頁面的完整網址 | -| `env` | 環境變數 | +{% youtube T9oAax-IRw0 %} + +### Global Variables + +| 變數 | 描述 | Type | +| -------- | ------------------------------- | --------------------------------------- | +| `site` | Sitewide information. | `object`; see [Site Variables][] | +| `page` | 針對該頁面的資訊以及 front-matter 所設定的變數。 | `object`; see [Page Variables][] | +| `config` | 網站配置 | `object` (your site's \_config file) | +| `theme` | 主題配置。 繼承自網站配置。 | `object` (your theme's \_config file) | +| `path` | 目前頁面的路徑（不含根路徑） | `網站變數` | +| `url` | 目前頁面的完整網址 | `網站變數` | +| `env` | 環境變數 | ??? | {% note warn %} Lodash has been removed from global variables since Hexo 5.0.0. [You-Dont-Need-Lodash-Underscore](https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore) might be helpful for your migration. {% endnote %} -### 網站變數 +### Site Variables -| 變數 | 描述 | -| ----------------- | -------- | -| `site.posts` | 所有文章 | -| `site.pages` | 所有分頁 | -| `site.categories` | 所有分類 | -| `site.tags` | 所有標籤 | +| 變數 | 描述 | Type | +| ----------------- | ---- | ------------------------- | +| `site.posts` | 所有文章 | `array` of `post` objects | +| `site.pages` | 所有分頁 | `array` of `page` objects | +| `site.categories` | 所有分類 | `array` of ??? | +| `site.tags` | 所有標籤 | `array` of ??? | ### 頁面變數 **文章（post, page, ...）** -| 變數 | 描述 | -| ------------------ | ------------------------------------------------------------------- | -| `page.title` | 文章標題 | -| `page.date` | 文章建立日期（[Moment.js] 物件） | -| `page.updated` | 文章更新日期（[Moment.js] 物件） | -| `page.categories` | 文章分類 | -| `page.tags` | 文章標籤 | -| `page.comments` | 留言是否開啟 | -| `page.layout` | 佈局名稱 | -| `page.content` | 文章的完整內容 | -| `page.excerpt` | 文章摘要 | -| `page.more` | 除了文章摘要的其餘內容 | -| `page.source` | 文章原始路徑 | -| `page.full_source` | 文章的完整原始路徑 | -| `page.path` | 文章網址（不含根路徑）。我們通常在主題中使用 `url_for(page.path)`。 | -| `page.permalink` | 文章的完整網址 | -| `page.prev` | 上一篇文章。如果此為第一篇文章則為 `null`。 | -| `page.next` | 下一篇文章。如果此為最後一篇文章則為 `null`。 | -| `page.raw` | 文章的原始內容 | -| `page.photos` | 文章的照片（用於相簿） | -| `page.link` | 文章的外連連結（用於連結文章） | +| 變數 | 描述 | Type | +| ------------------ | --------------------------------------------- | ------------------------ | +| `page.title` | 文章標題 | `tag` | +| `page.date` | Article created date | 文章建立日期（[Moment.js][] 物件） | +| `page.updated` | Article last updated date | 文章更新日期（[Moment.js][] 物件） | +| `page.comments` | Comment enabled or not | `boolean` | +| `page.layout` | Layout name | `category` | +| `page.content` | 文章的完整網址 | `string` | +| `page.excerpt` | 文章的原始內容 | `string` | +| `page.more` | 除了文章摘要的其餘內容 | `總頁數` | +| `page.source` | The path of the source file | `string` | +| `page.full_source` | Full path of the source file | `string` | +| `page.path` | 文章網址（不含根路徑）。 我們通常在主題中使用 `url_for(page.path)`。 | `文章的完整內容` | +| `page.permalink` | 文章的完整原始路徑 | `留言是否開啟` | +| `page.prev` | 如果此為第一篇文章則為 `null`。 | ??? | +| `page.next` | 下一篇文章。 如果此為最後一篇文章則為 `null`。 | ??? | +| `page.raw` | The raw data of the article | ??? | +| `page.photos` | 文章的照片（用於相簿） | array of ??? | +| `page.link` | 文章的外連連結（用於連結文章） | `文章標籤` | + +**彙整 (archive)**：與 `index` 佈局相同，但新增以下變數。 + +| 變數 | 描述 | Type | +| ----------------- | ------------------------------- | -------------- | +| `每頁顯示的文章數量` | True if the post is not a draft | `boolean` | +| `page.categories` | All categories of the post | `array` of ??? | +| `page.tags` | All tags of the post | `array` of ??? | **首頁（index）** -| 變數 | 描述 | -| ------------------ | ------------------------------------------------------------------------- | -| `page.per_page` | 每頁顯示的文章數量 | -| `page.total` | 總頁數 | -| `page.current` | 目前頁數 | -| `page.current_url` | 目前分頁的網址 | -| `page.posts` | 本頁文章 | -| `page.prev` | 上一頁的頁數。如果此頁是第一頁的話則為 `0`。 | -| `page.prev_link` | 上一頁的連結。如果此頁是第一頁的話則為 `''`。 | -| `page.next` | 下一頁的頁數。如果此頁是最後一頁的話則為 `0`。 | -| `page.next_link` | 下一頁的網址。如果此頁是最後一頁的話則為 `''`。 | -| `page.path` | 目前頁面的路徑（不含根目錄）。我們通常在主題中使用 `url_for(page.path)`。 | +| 變數 | 描述 | Type | +| ------------------ | ---------------------------------------------------------------------- | -------------- | +| `page.per_page` | Posts displayed per page | `number` | +| `page.total` | Total number of pages | `number` | +| `page.current` | 目前頁數 | `number` | +| `page.current_url` | 目前分頁的網址 | `#網站變數` | +| `page.posts` | Posts in this page ([Data Model](https://hexojs.github.io/warehouse/)) | `object` | +| `page.prev` | 上一頁的頁數。 如果此頁是第一頁的話則為 `0`。 | `number` | +| `page.prev_link` | 下一頁的網址。 如果此頁是最後一頁的話則為 `''`。 | `彙整月份（不含開頭的零）` | +| `page.next` | 下一頁的頁數。 如果此頁是最後一頁的話則為 `0`。 | `number` | +| `page.next_link` | 上一頁的連結。 如果此頁是第一頁的話則為 `''`。 | `全局變數` | +| `page.path` | 目前頁面的路徑（不含根目錄）。 我們通常在主題中使用 `url_for(page.path)`。 | `string` | -**彙整 (archive)**：與 `index` 佈局相同，但新增以下變數。 +**標籤 (tag)**：與 `index` 佈局相同，但新增以下變數。 -| 變數 | 描述 | -| --------- | ------------------------ | -| `archive` | 等於 `true` | -| `year` | 彙整年份（4 位數） | -| `month` | 彙整月份（不含開頭的零） | +| 變數 | 描述 | Type | +| --------- | --------------------------------------------- | --------- | +| `archive` | 等於 `true` | `boolean` | +| `year` | 彙整年份（4 位數） | `number` | +| `month` | Archive month (2-digit without leading zeros) | `number` | **分類 (category)**：與 `index` 佈局相同，但新增以下變數。 -| 變數 | 描述 | -| ---------- | -------- | -| `category` | 分類名稱 | +| 變數 | 描述 | Type | +| ------ | ---- | -------- | +| `文章分類` | 分類名稱 | `文章原始路徑` | -**標籤 (tag)**：與 `index` 佈局相同，但新增以下變數。 +Lodash has been removed from global variables since Hexo 5.0.0. [You-Dont-Need-Lodash-Underscore](https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore) might be helpful for your migration. -| 變數 | 描述 | -| ----- | -------- | -| `tag` | 標籤名稱 | +| Variable | 文章摘要 | Type | +| -------- | ---- | ------ | +| `本頁文章` | 標籤名稱 | `佈局名稱` | [Moment.js]: http://momentjs.com/ +[Site Variables]: #Site-Variables +[Page Variables]: #Page-Variables diff --git a/source/zh-tw/docs/writing.md b/source/zh-tw/docs/writing.md index 18237f78b9..401b4be2e0 100644 --- a/source/zh-tw/docs/writing.md +++ b/source/zh-tw/docs/writing.md @@ -4,71 +4,71 @@ title: 寫作 {% youtube HLJ9jJy7CMg %} -接下來，我們要在網誌中建立第一篇新文章，您可以直接從現有的範例文章「Hello World」改寫，但我們更建議您學習 `new` 指令。 +To create a new post or a new page, you can run the following command: ```bash $ hexo new [layout] <title> ``` -您可以在指令中指定文章的佈局（layout），預設為 `post`，您可以透過修改 `_config.yml` 中的 `default_layout` 設定來指定預設佈局。 +`post` is the default `layout`, but you can supply your own. You can change the default layout by editing the `default_layout` setting in `_config.yml`. -### 佈局（Layout） +## 佈局 -Hexo 有三種預設佈局：`post`、`page` 和 `draft`，它們分別對應不同的路徑，而您所自定的其他佈局和 `post` 相同，都儲存至 `source/_posts` 資料夾。 +Hexo 有三種預設佈局：`post`、`page` 和 `draft`，它們分別對應不同的路徑，而您所自定的其他佈局和 `post` 相同，都儲存至 `source/_posts` 資料夾。 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 Disabling layout %} -If you don't want an article (post/page) to be processed with a theme, set `layout: false` in its front-matter. Refer to [this section](/zh-tw/docs/front-matter#佈局) for more details. +If you don't want an article (post/page) to be processed with a theme, set `layout: false` in its front-matter. Refer to [this section](/zh-tw/docs/front-matter#佈局) for more details. Refer to [this section](/docs/front-matter#Layout) for more details. {% endnote %} -### 檔案名稱 +## 檔案名稱 -Hexo 預設以標題做為檔案名稱，但您可編輯 `new_post_name` 設定來變更預設的檔案名稱，舉例來說，設為 `:year-:month-:day-:title.md` 可讓您更方便的透過日期來管理文章。 +By default, Hexo uses the post title as its filename. 您可以在指令中指定文章的佈局（layout），預設為 `post`，您可以透過修改 `_config.yml` 中的 `default_layout` 設定來指定預設佈局。 For example, `:year-:month-:day-:title.md` will prefix filenames with the post creation date. You can use the following placeholders: -| 變數 | 描述 | -| ---------- | ------------------------ | -| `:title` | 標題 | -| `:year` | 建立年份（4 位數） | -| `:month` | 建立月份（2 位數） | -| `:i_month` | 建立月份（去掉開頭的零） | -| `:day` | 建立日期（2 位數） | -| `:i_day` | 建立日期（去掉開頭的零） | +| Placeholder | 描述 | +| ----------- | -------------------------------------------------------- | +| `:title` | Post title (lower case, with spaces replaced by hyphens) | +| `:year` | Created year, e.g. `2015` | +| `:month` | Created month (leading zeros), e.g. `04` | +| `:i_month` | Created month (no leading zeros), e.g. `4` | +| `:day` | Created day (leading zeros), e.g. `07` | +| `:i_day` | Created day (no leading zeros), e.g. `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` 選項，或是把 `render_drafts` 設定改為 `true` 來預覽草稿。 +Drafts are not displayed by default. 草稿預設不會顯示於頁面中，您可在執行時加上 `--draft` 選項，或是把 `render_drafts` 設定改為 `true` 來預覽草稿。 -### 鷹架（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` | 佈局（Layout） | +| `title` | 標題 | +| `date` | 檔案建立日期 | -### Supported Formats +## Supported Formats Hexo support posts written in any format, as long as the corresponding renderer plugin is installed. -For example, Hexo has `hexo-renderer-marked` and `hexo-renderer-ejs` installed by default, so you can write your posts in `markdown` or in `ejs`. If you have `hexo-renderer-pug` installed, then you can even write your post in pug template language. +For example, Hexo has `hexo-renderer-marked` and `hexo-renderer-ejs` installed by default, so you can write your posts in `markdown` or in `ejs`. If you have `hexo-renderer-pug` installed, then you can even write your post in pug template language. If you have `hexo-renderer-pug` installed, then you can even write your post in pug template language. You can rename your posts and change to file extension from `.md` to `.ejs`, then Hexo will use `hexo-renderer-ejs` to render that file, so do the other formats. diff --git a/source/zh-tw/index.md b/source/zh-tw/index.md index b7d89618bc..440fb43a60 100644 --- a/source/zh-tw/index.md +++ b/source/zh-tw/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"> @@ -27,15 +27,15 @@ comments: false <div class="intro-feature-icon"> <i class="fa fa-cloud-upload"></i> </div> - <h3 class="intro-feature-title">一鍵部署</h3> + <h3 class="intro-feature-title">One-Command Deployment</h3> <p class="intro-feature-desc">您只需要一個指令就能把網站部署到 GitHub Pages, Heroku 或其他網站。</p> </div></li><li class="intro-feature-wrap"> <div class="intro-feature"> <div class="intro-feature-icon"> <i class="fa fa-cog"></i> </div> - <h3 class="intro-feature-title">豐富的外掛</h3> - <p class="intro-feature-desc">Hexo 有強大的外掛系統，您可安裝外掛讓 Hexo 支援 Jade, CoffeeScript。</p> + <h3 class="intro-feature-title">Plugins</h3> + <p class="intro-feature-desc">Features powerful APIs for limitless extensibility. Various plugins are available to support most template engines (EJS, Pug, Nunjucks, and many others). Easily integrate with existing NPM packages (Babel, PostCSS, Less/Sass, etc).</p> </div> </li> </ul>