From d9d3091d421e21f4dec1246bf1df07c002505afd Mon Sep 17 00:00:00 2001 From: "hexo-crowdin[bot]" <159447924+hexo-crowdin[bot]@users.noreply.github.com> Date: Tue, 16 Jun 2026 03:52:02 +0000 Subject: [PATCH] l10n: New translations from Crowdin --- source/fa/api/box.md | 62 ++ source/fa/api/console.md | 75 ++ source/fa/api/deployer.md | 15 + source/fa/api/events.md | 54 ++ source/fa/api/filter.md | 226 +++++ source/fa/api/generator.md | 111 +++ source/fa/api/helper.md | 52 ++ source/fa/api/index.md | 75 ++ source/fa/api/injector.md | 141 +++ source/fa/api/locals.md | 46 + source/fa/api/migrator.md | 15 + source/fa/api/posts.md | 62 ++ source/fa/api/processor.md | 15 + source/fa/api/renderer.md | 86 ++ source/fa/api/rendering.md | 80 ++ source/fa/api/router.md | 75 ++ source/fa/api/scaffolds.md | 21 + source/fa/api/tag.md | 169 ++++ source/fa/api/themes.md | 37 + source/fa/docs/asset-folders.md | 55 ++ source/fa/docs/commands.md | 202 ++++ source/fa/docs/configuration.md | 312 +++++++ source/fa/docs/contributing.md | 111 +++ source/fa/docs/data-files.md | 31 + source/fa/docs/front-matter.md | 75 ++ source/fa/docs/generating.md | 28 + source/fa/docs/github-pages.md | 111 +++ source/fa/docs/gitlab-pages.md | 45 + source/fa/docs/helpers.md | 981 ++++++++++++++++++++ source/fa/docs/index.md | 111 +++ source/fa/docs/internationalization.md | 57 ++ source/fa/docs/migration.md | 73 ++ source/fa/docs/one-command-deployment.md | 252 +++++ source/fa/docs/permalinks.md | 86 ++ source/fa/docs/plugins.md | 77 ++ source/fa/docs/server.md | 41 + source/fa/docs/setup.md | 69 ++ source/fa/docs/syntax-highlight.md | 294 ++++++ source/fa/docs/tag-plugins.md | 493 ++++++++++ source/fa/docs/templates.md | 110 +++ source/fa/docs/themes.md | 83 ++ source/fa/docs/troubleshooting.md | 294 ++++++ source/fa/docs/variables.md | 103 ++ source/fa/docs/writing.md | 74 ++ source/fa/index.md | 41 + source/tr/api/box.md | 62 ++ source/tr/api/console.md | 75 ++ source/tr/api/deployer.md | 15 + source/tr/api/events.md | 54 ++ source/tr/api/filter.md | 226 +++++ source/tr/api/generator.md | 111 +++ source/tr/api/helper.md | 52 ++ source/tr/api/index.md | 75 ++ source/tr/api/injector.md | 141 +++ source/tr/api/locals.md | 46 + source/tr/api/migrator.md | 15 + source/tr/api/posts.md | 62 ++ source/tr/api/processor.md | 15 + source/tr/api/renderer.md | 86 ++ source/tr/api/rendering.md | 80 ++ source/tr/api/router.md | 75 ++ source/tr/api/scaffolds.md | 21 + source/tr/api/tag.md | 169 ++++ source/tr/api/themes.md | 37 + source/tr/docs/asset-folders.md | 55 ++ source/tr/docs/commands.md | 202 ++++ source/tr/docs/configuration.md | 312 +++++++ source/tr/docs/contributing.md | 111 +++ source/tr/docs/data-files.md | 31 + source/tr/docs/front-matter.md | 75 ++ source/tr/docs/generating.md | 28 + source/tr/docs/github-pages.md | 111 +++ source/tr/docs/gitlab-pages.md | 45 + source/tr/docs/helpers.md | 981 ++++++++++++++++++++ source/tr/docs/index.md | 111 +++ source/tr/docs/internationalization.md | 57 ++ source/tr/docs/migration.md | 73 ++ source/tr/docs/one-command-deployment.md | 252 +++++ source/tr/docs/permalinks.md | 86 ++ source/tr/docs/plugins.md | 77 ++ source/tr/docs/server.md | 41 + source/tr/docs/setup.md | 69 ++ source/tr/docs/syntax-highlight.md | 294 ++++++ source/tr/docs/tag-plugins.md | 493 ++++++++++ source/tr/docs/templates.md | 110 +++ source/tr/docs/themes.md | 83 ++ source/tr/docs/troubleshooting.md | 294 ++++++ source/tr/docs/variables.md | 103 ++ source/tr/docs/writing.md | 74 ++ source/tr/index.md | 41 + source/zh-cn/docs/one-command-deployment.md | 2 +- 91 files changed, 11253 insertions(+), 1 deletion(-) create mode 100644 source/fa/api/box.md create mode 100644 source/fa/api/console.md create mode 100644 source/fa/api/deployer.md create mode 100644 source/fa/api/events.md create mode 100644 source/fa/api/filter.md create mode 100644 source/fa/api/generator.md create mode 100644 source/fa/api/helper.md create mode 100644 source/fa/api/index.md create mode 100644 source/fa/api/injector.md create mode 100644 source/fa/api/locals.md create mode 100644 source/fa/api/migrator.md create mode 100644 source/fa/api/posts.md create mode 100644 source/fa/api/processor.md create mode 100644 source/fa/api/renderer.md create mode 100644 source/fa/api/rendering.md create mode 100644 source/fa/api/router.md create mode 100644 source/fa/api/scaffolds.md create mode 100644 source/fa/api/tag.md create mode 100644 source/fa/api/themes.md create mode 100644 source/fa/docs/asset-folders.md create mode 100644 source/fa/docs/commands.md create mode 100644 source/fa/docs/configuration.md create mode 100644 source/fa/docs/contributing.md create mode 100644 source/fa/docs/data-files.md create mode 100644 source/fa/docs/front-matter.md create mode 100644 source/fa/docs/generating.md create mode 100644 source/fa/docs/github-pages.md create mode 100644 source/fa/docs/gitlab-pages.md create mode 100644 source/fa/docs/helpers.md create mode 100644 source/fa/docs/index.md create mode 100644 source/fa/docs/internationalization.md create mode 100644 source/fa/docs/migration.md create mode 100644 source/fa/docs/one-command-deployment.md create mode 100644 source/fa/docs/permalinks.md create mode 100644 source/fa/docs/plugins.md create mode 100644 source/fa/docs/server.md create mode 100644 source/fa/docs/setup.md create mode 100644 source/fa/docs/syntax-highlight.md create mode 100644 source/fa/docs/tag-plugins.md create mode 100644 source/fa/docs/templates.md create mode 100644 source/fa/docs/themes.md create mode 100644 source/fa/docs/troubleshooting.md create mode 100644 source/fa/docs/variables.md create mode 100644 source/fa/docs/writing.md create mode 100644 source/fa/index.md create mode 100644 source/tr/api/box.md create mode 100644 source/tr/api/console.md create mode 100644 source/tr/api/deployer.md create mode 100644 source/tr/api/events.md create mode 100644 source/tr/api/filter.md create mode 100644 source/tr/api/generator.md create mode 100644 source/tr/api/helper.md create mode 100644 source/tr/api/index.md create mode 100644 source/tr/api/injector.md create mode 100644 source/tr/api/locals.md create mode 100644 source/tr/api/migrator.md create mode 100644 source/tr/api/posts.md create mode 100644 source/tr/api/processor.md create mode 100644 source/tr/api/renderer.md create mode 100644 source/tr/api/rendering.md create mode 100644 source/tr/api/router.md create mode 100644 source/tr/api/scaffolds.md create mode 100644 source/tr/api/tag.md create mode 100644 source/tr/api/themes.md create mode 100644 source/tr/docs/asset-folders.md create mode 100644 source/tr/docs/commands.md create mode 100644 source/tr/docs/configuration.md create mode 100644 source/tr/docs/contributing.md create mode 100644 source/tr/docs/data-files.md create mode 100644 source/tr/docs/front-matter.md create mode 100644 source/tr/docs/generating.md create mode 100644 source/tr/docs/github-pages.md create mode 100644 source/tr/docs/gitlab-pages.md create mode 100644 source/tr/docs/helpers.md create mode 100644 source/tr/docs/index.md create mode 100644 source/tr/docs/internationalization.md create mode 100644 source/tr/docs/migration.md create mode 100644 source/tr/docs/one-command-deployment.md create mode 100644 source/tr/docs/permalinks.md create mode 100644 source/tr/docs/plugins.md create mode 100644 source/tr/docs/server.md create mode 100644 source/tr/docs/setup.md create mode 100644 source/tr/docs/syntax-highlight.md create mode 100644 source/tr/docs/tag-plugins.md create mode 100644 source/tr/docs/templates.md create mode 100644 source/tr/docs/themes.md create mode 100644 source/tr/docs/troubleshooting.md create mode 100644 source/tr/docs/variables.md create mode 100644 source/tr/docs/writing.md create mode 100644 source/tr/index.md diff --git a/source/fa/api/box.md b/source/fa/api/box.md new file mode 100644 index 0000000000..5b14bc6b2f --- /dev/null +++ b/source/fa/api/box.md @@ -0,0 +1,62 @@ +--- +title: Box +--- + +Box is a container used for processing files in a specified folder. Hexo uses two different boxes: `hexo.source` and `hexo.theme`. The former is used to process the `source` folder and the latter to process the `theme` folder. + +## Load Files + +Box provides two methods for loading files: `process` and `watch`. `process` loads all files in the folder. `watch` does the same, but also starts watching for file changes. + +```js +box.process().then(function () { + // ... +}); + +box.watch().then(function () { + // You can call box.unwatch() later to stop watching. +}); +``` + +## Path Matching + +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 +``` + +See [util.Pattern][] for more info. + +## Processors + +A processor is an essential element of Box and is used to process files. You can use path matching as described above to restrict what exactly the processor should process. Register a new processor with the `addProcessor` method. + +```js +box.addProcessor("posts/:id", function (file) { + // +}); +``` + +Box passes the content of matched files to processors. This information can then be read straight from the `file` argument in the callback: + +| Attribute | Description | +| --------- | ----------------------------------------------------------------- | +| `source` | Full path of the file | +| `path` | Relative path to the box of the file | +| `type` | File type. The value can be `create`, `update`, `skip`, `delete`. | +| `params` | The information from path matching. | + +Box also provides some methods so you don't have to do file IO by yourself. + +| Method | Description | +| ------------ | --------------------------------------- | +| `read` | Read a file | +| `readSync` | Read a file synchronously | +| `stat` | Read the status of a file | +| `statSync` | Read the status of a file synchronously | +| `render` | Render a file | +| `renderSync` | Render a file synchronously | + +[util.Pattern]: https://github.com/hexojs/hexo-util#patternrule diff --git a/source/fa/api/console.md b/source/fa/api/console.md new file mode 100644 index 0000000000..5c94dd2458 --- /dev/null +++ b/source/fa/api/console.md @@ -0,0 +1,75 @@ +--- +title: Console +--- + +The console forms the bridge between Hexo and its users. It registers and describes the available console commands. + +## Synopsis + +```js +hexo.extend.console.register(name, desc, options, function (args) { + // ... +}); +``` + +| Argument | Description | +| --------- | ----------- | +| `name` | Name | +| `desc` | Description | +| `options` | Options | + +An argument `args` will be passed into the function. This is the argument that users type into the terminal. It's parsed by [Minimist][]. + +## Options + +### usage + +The usage of a console command. For example: + +```js +{ + usage: "[layout] "; +} +// hexo new [layout] <title> +``` + +### arguments + +The description of each argument of a console command. For example: + +```js +{ + arguments: [ + { name: "layout", desc: "Post layout" }, + { name: "title", desc: "Post title" }, + ]; +} +``` + +### options + +The description of each option of a console command. For example: + +```js +{ + options: [{ name: "-r, --replace", desc: "Replace existing files" }]; +} +``` + +### desc + +More detailed information about a console command. + +## Example + +```js +hexo.extend.console.register( + "config", + "Display configuration", + function (args) { + console.log(hexo.config); + }, +); +``` + +[Minimist]: https://github.com/minimistjs/minimist diff --git a/source/fa/api/deployer.md b/source/fa/api/deployer.md new file mode 100644 index 0000000000..c26df36fdd --- /dev/null +++ b/source/fa/api/deployer.md @@ -0,0 +1,15 @@ +--- +title: Deployer +--- + +A deployer helps users quickly deploy their site to a remote server without complicated commands. + +## Synopsis + +```js +hexo.extend.deployer.register(name, function (args) { + // ... +}); +``` + +An argument `args` will be passed into the function. It contains the `deploy` value set in `_config.yml`, as well as the exact input users typed into their terminal. diff --git a/source/fa/api/events.md b/source/fa/api/events.md new file mode 100644 index 0000000000..06b913a525 --- /dev/null +++ b/source/fa/api/events.md @@ -0,0 +1,54 @@ +--- +title: Events +--- + +Hexo inherits from [EventEmitter][]. 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 + +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) { + // +}); +``` + +| Data | Description | +| -------------- | -------------------------- | +| `post.path` | Full path of the post file | +| `post.content` | Content of the post file | + +### processBefore + +Emitted before processing begins. This event returns a path representing the root directory of the box. + +### processAfter + +Emitted after processing finishes. This event returns a path representing the root directory of the box. + +### ready + +Emitted after initialization finishes. + +[EventEmitter]: https://nodejs.org/dist/latest/docs/api/events.html diff --git a/source/fa/api/filter.md b/source/fa/api/filter.md new file mode 100644 index 0000000000..e7d9f30672 --- /dev/null +++ b/source/fa/api/filter.md @@ -0,0 +1,226 @@ +--- +title: Filter +--- + +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). + +## Synopsis + +```js +hexo.extend.filter.register(type, function() { + // User configuration + const { config } = this; + if (config.external_link.enable) // do something... + + // Theme configuration + const { config: themeCfg } = this.theme; + if (themeCfg.fancybox) // do something... + +}, priority); +``` + +You can define the `priority`. Lower `priority` means that it will be executed first. The default `priority` is 10. We recommend using user-configurable priority value that user can specify in the config, e.g. `hexo.config.your_plugin.priority`. + +## Execute Filters + +```js +hexo.extend.filter.exec(type, data, options); +hexo.extend.filter.execSync(type, data, options); +``` + +| Option | Description | +| --------- | --------------------------------- | +| `context` | Context | +| `args` | Arguments. This must be an array. | + +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. You can even use `args` to specify other arguments in filters. For example: + +```js +hexo.extend.filter.register("test", function (data, arg1, arg2) { + // data === 'some data' + // arg1 === 'foo' + // arg2 === 'bar' + + return "something"; +}); + +hexo.extend.filter.register("test", function (data, arg1, arg2) { + // data === 'something' +}); + +hexo.extend.filter.exec("test", "some data", { + args: ["foo", "bar"], +}); +``` + +You can also use the following methods to execute filters: + +```js +hexo.execFilter(type, data, options); +hexo.execFilterSync(type, data, options); +``` + +## Unregister Filters + +```js +hexo.extend.filter.unregister(type, filter); +``` + +**Example** + +```js +// Unregister a filter which is registered with named function + +const filterFn = (data) => { + data = "something"; + return data; +}; +hexo.extend.filter.register("example", filterFn); + +hexo.extend.filter.unregister("example", filterFn); +``` + +```js +// Unregister a filter which is registered with commonjs module + +hexo.extend.filter.register("example", require("path/to/filter")); + +hexo.extend.filter.unregister("example", require("path/to/filter")); +``` + +## Filter List + +Here is a list of filters used by Hexo. + +### before_post_render + +Executed before a post is rendered. Refer to [post rendering](posts.html#Render) to learn the execution steps. + +For example, to transform the title to lower case: + +```js +hexo.extend.filter.register("before_post_render", function (data) { + data.title = data.title.toLowerCase(); + return data; +}); +``` + +### after_post_render + +Executed after a post is rendered. Refer to [post rendering](posts.html#Render) to learn the execution steps. + +For example, to replace `@username` with a link to a Twitter profile: + +```js +hexo.extend.filter.register("after_post_render", function (data) { + data.content = data.content.replace( + /@(\d+)/, + '<a href="http://twitter.com/$1">#$1</a>', + ); + return data; +}); +``` + +### before_exit + +Executed before Hexo is about to exit -- this will run right after `hexo.exit` is called. + +```js +hexo.extend.filter.register("before_exit", function () { + // ... +}); +``` + +### before_generate + +Executed before generation begins. + +```js +hexo.extend.filter.register("before_generate", function () { + // ... +}); +``` + +### after_generate + +Executed after generation finishes. + +```js +hexo.extend.filter.register("after_generate", function () { + // ... +}); +``` + +### template_locals + +Modify [local variables](../docs/variables.html) in templates. + +For example, to add the current time to the local variables of templates: + +```js +hexo.extend.filter.register("template_locals", function (locals) { + locals.now = Date.now(); + return locals; +}); +``` + +### after_init + +Executed after Hexo is initialized -- this will run right after `hexo.init` completes. + +```js +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 + +Executed after rendering finishes. You can see [rendering](rendering.html#after_render_Filters) for more info. + +### after_clean + +Executed after generated files and cache are removed with `hexo clean` command. + +```js +hexo.extend.filter.register("after_clean", function () { + // remove some other temporary files +}); +``` + +### server_middleware + +Add middleware to the server. `app` is a [Connect][] instance. + +For example, to add `X-Powered-By: Hexo` to the response header: + +```js +hexo.extend.filter.register("server_middleware", function (app) { + app.use(function (req, res, next) { + res.setHeader("X-Powered-By", "Hexo"); + next(); + }); +}); +``` + +[Connect]: https://github.com/senchalabs/connect diff --git a/source/fa/api/generator.md b/source/fa/api/generator.md new file mode 100644 index 0000000000..5f7218cf90 --- /dev/null +++ b/source/fa/api/generator.md @@ -0,0 +1,111 @@ +--- +title: Generator +--- + +A generator builds routes based on processed files. + +## Synopsis + +```js +hexo.extend.generator.register(name, function (locals) { + // ... +}); +``` + +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. + +## Update Routes + +```js +hexo.extend.generator.register("test", function (locals) { + // Object + return { + path: "foo", + data: "foo", + }; + + // Array + return [ + { path: "foo", data: "foo" }, + { path: "bar", data: "bar" }, + ]; +}); +``` + +| Attribute | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `path` | Path not including the prefixing `/`. | +| `data` | 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. | + +When the source files are updated, Hexo will execute all generators and rebuild the routes. **Please return the data and do not access the router directly.** + +## Example + +### Archive Page + +Create an archive page at `archives/index.html`. We pass all posts as data to the templates. This data is equivalent to the `page` variable in templates. + +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) { + return { + path: "archives/index.html", + data: locals, + layout: ["archive", "index"], + }; +}); +``` + +### Archive Page with Pagination + +You can use the convenient official tool [hexo-pagination][] to easily build archive pages with pagination. + +```js +var pagination = require("hexo-pagination"); + +hexo.extend.generator.register("archive", function (locals) { + // hexo-pagination makes an index.html for the /archives route + return pagination("archives", locals.posts, { + perPage: 10, + layout: ["archive", "index"], + data: {}, + }); +}); +``` + +### Generate All Posts + +Iterate over all posts in `locals.posts` and create routes for all the posts. + +```js +hexo.extend.generator.register("post", function (locals) { + return locals.posts.map(function (post) { + return { + path: post.path, + data: post, + layout: "post", + }; + }); +}); +``` + +### Copy Files + +This time we don't return the data explicitly but instead set `data` to a function so the route will build `fs.ReadStream` only when needed. + +```js +var fs = require("hexo-fs"); + +hexo.extend.generator.register("asset", function (locals) { + return { + path: "file.txt", + data: function () { + return fs.createReadStream("path/to/file.txt"); + }, + }; +}); +``` + +[hexo-pagination]: https://github.com/hexojs/hexo-pagination diff --git a/source/fa/api/helper.md b/source/fa/api/helper.md new file mode 100644 index 0000000000..76a72e8bcd --- /dev/null +++ b/source/fa/api/helper.md @@ -0,0 +1,52 @@ +--- +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. + +## Synopsis + +```js +hexo.extend.helper.register(name, function () { + // ... +}); +``` + +## Example + +```js +hexo.extend.helper.register("js", function (path) { + return '<script src="' + path + '"></script>'; +}); +``` + +```js +<%- js('script.js') %> +// <script src="script.js"></script> +``` + +## FAQ + +### Where to place custom helper? + +Place it under `scripts/` or `themes/<yourtheme>/scripts/` folder. + +### How do I use another registered helper in my custom helper? + +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) { + return '<script src="' + this.url_for(path) + '"></script>'; +}); +``` + +### How do I use a registered helper in another extension (e.g. Filter, Injector)? + +`hexo.extend.helper.get` will return the helper function, but it needs to have hexo as its context, so: + +```js +const url_for = hexo.extend.helper.get("url_for").bind(hexo); +``` diff --git a/source/fa/api/index.md b/source/fa/api/index.md new file mode 100644 index 0000000000..acca2eea71 --- /dev/null +++ b/source/fa/api/index.md @@ -0,0 +1,75 @@ +--- +title: API +--- + +This documentation provides more detailed information about the API and will be particularly helpful for people who want to modify the Hexo source code or write new plugins. If you are interested in more basic usage of Hexo, please refer to the [docs](../docs) instead. + +Please note that this documentation is only valid for Hexo 3 and above. + +## Initialize + +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"); +var hexo = new Hexo(process.cwd(), {}); + +hexo.init().then(function () { + // ... +}); +``` + +| Option | Description | Default | +| ------------------ | ----------------------------------------------------------------------------------------------------- | --------------------------------- | +| `debug` | Enable debug mode. Display debug messages in the terminal and save `debug.log` in the root directory. | `false` | +| `safe` | Enable safe mode. Don't load any plugins. | `false` | +| `silent` | Enable silent mode. Don't display any messages in the terminal. | `false` | +| `config` | Specify the path of the configuration file. | `_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 | + +## Load Files + +Hexo provides two methods for loading files: `load` and `watch`. `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. + +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.watch().then(function () { + // You can call hexo.unwatch() later to stop watching. +}); +``` + +## Execute Commands + +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 + +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 + .call("generate") + .then(function () { + return hexo.exit(); + }) + .catch(function (err) { + return hexo.exit(err); + }); +``` diff --git a/source/fa/api/injector.md b/source/fa/api/injector.md new file mode 100644 index 0000000000..a1200bf9d7 --- /dev/null +++ b/source/fa/api/injector.md @@ -0,0 +1,141 @@ +--- +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. + +## Synopsis + +```js +hexo.extend.injector.register(entry, value, to); +``` + +### entry `<string>` + +Where the code will be injected inside the HTML. + +Support those values: + +- `head_begin`: Inject code snippet right after `<head>` (Default). +- `head_end`: Inject code snippet right before `</head>`. +- `body_begin`: Inject code snippet right after `<body>`. +- `body_end`: Inject code snippet right before `</body>`. + +### value `<string> | <Function>` + +> A function that returns string is supported. + +The code snippet to be injected. + +### to `<string>` + +Which page will code snippets being injected. + +- `default`: Inject to every page (Default). +- `home`: Only inject to home page (which has `is_home()` helper being `true`) +- `post`: Only inject to post pages (which has `is_post()` helper being `true`) +- `page`: Only inject to pages (which has `is_page()` helper being `true`) +- `archive`: Only inject to archive pages (which has `is_archive()` helper being `true`) +- `category`: Only inject to category pages (which has `is_category()` helper being `true`) +- `tag`: Only inject to tag pages (which has `is_tag()` helper being `true`) +- Custom layout name could be used as well, see [Writing - Layout](/docs/writing#Layout). + +--- + +There are other internal functions, see [hexojs/hexo#4049](https://github.com/hexojs/hexo/pull/4049) for more details. + +## Example + +```js +const css = hexo.extend.helper.get("css").bind(hexo); +const js = hexo.extend.helper.get("js").bind(hexo); + +hexo.extend.injector.register( + "head_end", + () => { + return css( + "https://cdn.jsdelivr.net/npm/aplayer@1.10.1/dist/APlayer.min.css", + ); + }, + "music", +); + +hexo.extend.injector.register( + "body_end", + '<script src="https://cdn.jsdelivr.net/npm/aplayer@1.10.1/dist/APlayer.min.js">', + "music", +); + +hexo.extend.injector.register("body_end", () => { + return js("/js/jquery.js"); +}); +``` + +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. + +## Accessing user configuration + +Use any of the following options: + +1. + +```js +const css = hexo.extend.helper.get("css").bind(hexo); + +hexo.extend.injector.register("head_end", () => { + const { cssPath } = hexo.config.fooPlugin; + return css(cssPath); +}); +``` + +2. + +```js index.js +/* global hexo */ + +hexo.extend.injector.register("head_end", require("./lib/inject").bind(hexo)); +``` + +```js lib/inject.js +module.exports = function () { + const css = this.extend.helper.get("css"); + const { cssPath } = this.config.fooPlugin; + return css(cssPath); +}; +``` + +```js lib/inject.js +function injectFn() { + const css = this.extend.helper.get("css"); + const { cssPath } = this.config.fooPlugin; + return css(cssPath); +} + +module.exports = injectFn; +``` + +3. + +```js index.js +/* global hexo */ + +hexo.extend.injector.register("head_end", require("./lib/inject")(hexo)); +``` + +```js lib/inject.js +module.exports = (hexo) => () => { + const css = hexo.extend.helper.get("css").bind(hexo); + const { cssPath } = hexo.config.fooPlugin; + return css(cssPath); +}; +``` + +```js lib/inject.js +const injectFn = (hexo) => { + const css = hexo.extend.helper.get("css").bind(hexo); + const { cssPath } = hexo.config.fooPlugin; + return css(cssPath); +}; + +module.exports = (hexo) => injectFn(hexo); +``` diff --git a/source/fa/api/locals.md b/source/fa/api/locals.md new file mode 100644 index 0000000000..2b2e54a848 --- /dev/null +++ b/source/fa/api/locals.md @@ -0,0 +1,46 @@ +--- +title: Local Variables +--- + +Local variables are used for template rendering, which is the `site` variable in templates. + +## Default Variables + +| Variable | Description | +| ------------ | -------------- | +| `posts` | All posts | +| `pages` | All pages | +| `categories` | All categories | +| `tags` | All tags | + +## Get a Variable + +```js +hexo.locals.get("posts"); +``` + +## Set a Variable + +```js +hexo.locals.set('posts', function(){ + return ... +}); +``` + +## Remove a Variable + +```js +hexo.locals.remove("posts"); +``` + +## Get All Variable + +```js +hexo.locals.toObject(); +``` + +## Invalidate the cache + +```js +hexo.locals.invalidate(); +``` diff --git a/source/fa/api/migrator.md b/source/fa/api/migrator.md new file mode 100644 index 0000000000..2f57a842c1 --- /dev/null +++ b/source/fa/api/migrator.md @@ -0,0 +1,15 @@ +--- +title: Migrator +--- + +A migrator helps users migrate from other systems to Hexo. + +## Synopsis + +```js +hexo.extend.migrator.register(name, function (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/fa/api/posts.md b/source/fa/api/posts.md new file mode 100644 index 0000000000..055988f4ae --- /dev/null +++ b/source/fa/api/posts.md @@ -0,0 +1,62 @@ +--- +title: Posts +--- + +## Create a Post + +```js +hexo.post.create(data, replace); +``` + +| Argument | Description | +| --------- | ---------------------- | +| `data` | Data | +| `replace` | Replace existing files | + +The attributes of a post can be defined in `data`. The table below is not exhaustive. Additional attributes may be appended to the front-matter. + +| Data | Description | +| -------- | -------------------------------------------------------------------------------- | +| `title` | Title | +| `slug` | URL | +| `layout` | Layout. Defaults to the `default_layout` setting. | +| `path` | Path. Hexo builds the post path based on the `new_post_path` setting by default. | +| `date` | Date. Defaults to the current date. | + +## Publish a Draft + +```js +hexo.post.publish(data, replace); +``` + +| Argument | Description | +| --------- | ---------------------- | +| `data` | Data | +| `replace` | Replace existing files | + +The attributes of a post can be defined in `data`. The table below is not exhaustive. Additional attributes may be appended to the front-matter. + +| Data | Description | +| -------- | ------------------------------------------------- | +| `slug` | File name (Required) | +| `layout` | Layout. Defaults to the `default_layout` setting. | + +## Render + +```js +hexo.post.render(source, data); +``` + +| Argument | Description | +| -------- | ------------------------------ | +| `source` | Full path of a file (Optional) | +| `data` | Data | + +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: + +- Execute `before_post_render` filters +- Render with Markdown or other renderers (depending on the extension name) +- Render with [Nunjucks][] +- Execute `after_post_render` filters + +[Nunjucks]: https://mozilla.github.io/nunjucks/ diff --git a/source/fa/api/processor.md b/source/fa/api/processor.md new file mode 100644 index 0000000000..52e91f8d07 --- /dev/null +++ b/source/fa/api/processor.md @@ -0,0 +1,15 @@ +--- +title: Processor +--- + +A processor is used to process source files in the `source` folder. + +## Synopsis + +```js +hexo.extend.processor.register(rule, function (file) { + // ... +}); +``` + +For more info, see [box](box.html). diff --git a/source/fa/api/renderer.md b/source/fa/api/renderer.md new file mode 100644 index 0000000000..916a2c5030 --- /dev/null +++ b/source/fa/api/renderer.md @@ -0,0 +1,86 @@ +--- +title: Renderer +--- + +A renderer is used to render content. + +## Synopsis + +```js +hexo.extend.renderer.register( + name, + output, + function (data, options) { + // ... + }, + sync, +); +``` + +| Argument | Description | +| -------- | ----------------------------------------------------------- | +| `name` | Input filename extension (lower case, without leading `.`) | +| `output` | Output filename extension (lower case, without leading `.`) | +| `sync` | Sync mode | + +Three arguments will be passed into the render function: + +| Argument | Description | +| ---------- | ------------------------------------------------------------------------------------------------- | +| `data` | Include two attributes: file path `path` and file content `text`. `path` won't necessarily exist. | +| `option` | Options | +| `callback` | Callback function of two parameters `err`, `value`. | + +## Example + +### Async Mode + +```js +var stylus = require("stylus"); + +// Callback +hexo.extend.renderer.register( + "styl", + "css", + function (data, options, callback) { + stylus(data.text).set("filename", data.path).render(callback); + }, +); + +// Promise +hexo.extend.renderer.register("styl", "css", function (data, options) { + return new Promise(function (resolve, reject) { + resolve("test"); + }); +}); +``` + +### Sync Mode + +```js +var ejs = require("ejs"); + +hexo.extend.renderer.register( + "ejs", + "html", + function (data, options) { + options.filename = data.path; + return ejs.render(data.text, options); + }, + true, +); +``` + +### Disable Nunjucks tags + +Nunjucks tags `{{ }}` or `{% %}` (utilized by [tag plugin](/docs/tag-plugins)) are processed by default, to disable: + +```js +function lessFn(data, options) { + // do something +} + +lessFn.disableNunjucks = true; + +hexo.extend.renderer.register("less", "css", lessFn); +``` diff --git a/source/fa/api/rendering.md b/source/fa/api/rendering.md new file mode 100644 index 0000000000..30a5b3ee20 --- /dev/null +++ b/source/fa/api/rendering.md @@ -0,0 +1,80 @@ +--- +title: Rendering +--- + +There are two methods for rendering files or strings in Hexo: the asynchronous `hexo.render.render` method and the synchronous `hexo.render.renderSync` method. Unsurprisingly, the two methods are very similar so only the asynchronous `hexo.render.render` will be further discussed in the below paragraphs. + +## Render a String + +When rendering a string, you must specify an `engine` to let Hexo know which rendering engine it should use. + +```js +hexo.render.render({ text: "example", engine: "swig" }).then(function (result) { + // ... +}); +``` + +## Render a File + +When rendering a file, it's not necessary to specify an `engine` because Hexo will detect the relevant rendering engine automatically based on the extension of the file. Of course, you are also allowed to explicitly define the `engine`. + +```js +hexo.render.render({ path: "path/to/file.swig" }).then(function (result) { + // ... +}); +``` + +## Render Options + +You can pass in an options object as the second argument. + +```js +hexo.render.render({ text: "" }, { foo: "foo" }).then(function (result) { + // ... +}); +``` + +## after_render Filters + +When rendering is complete, Hexo will execute the corresponding `after_render` filters. For example, we can use this feature to implement a JavaScript minifier. + +```js +var UglifyJS = require("uglify-js"); + +hexo.extend.filter.register("after_render:js", function (str, data) { + var result = UglifyJS.minify(str); + return result.code; +}); +``` + +## Check Whether a File is Renderable + +You can use the `isRenderable` or `isRenderableSync` method to check whether a file path is renderable. 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 + +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 +hexo.render.getOutput("image.png"); // ''' +``` + +## Disable Nunjucks tags + +If you are not using a [tag plugin](/docs/tag-plugins) and want to use `{{ }}` or `{% %}` in your post without using content [escaping](/docs/troubleshooting#Escape-Contents), you can disable processing of Nunjucks tag in existing renderer by: + +```js +// following example only applies to '.md' file extension +// you may need to cover other extensions, e.g. '.markdown', '.mkd' +const renderer = hexo.render.renderer.get("md"); +if (renderer) { + renderer.disableNunjucks = true; + hexo.extend.renderer.register("md", "html", renderer); +} +``` diff --git a/source/fa/api/router.md b/source/fa/api/router.md new file mode 100644 index 0000000000..afe7e94c6e --- /dev/null +++ b/source/fa/api/router.md @@ -0,0 +1,75 @@ +--- +title: Router +--- + +The router saves all paths used in the site. + +## Get a Path + +The `get` method returns a [Stream][]. For example, to save the path data to a specified destination: + +```js +var data = hexo.route.get("index.html"); +var dest = fs.createWriteStream("somewhere"); + +data.pipe(dest); +``` + +## Set a Path + +The `set` method takes a string, a [Buffer][] or a function. + +```js +// String +hexo.route.set("index.html", "index"); + +// Buffer +hexo.route.set("index.html", new Buffer("index")); + +// Function (Promise) +hexo.route.set("index.html", function () { + return new Promise(function (resolve, reject) { + resolve("index"); + }); +}); + +// Function (Callback) +hexo.route.set("index.html", function (callback) { + callback(null, "index"); +}); +``` + +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", { + data: "index", + modified: false, +}); + +// hexo.route.isModified('index.html') => false +``` + +## Remove a Path + +```js +hexo.route.remove("index.html"); +``` + +## Get the List of Routes + +```js +hexo.route.list(); +``` + +## Format a Path + +The `format` method transforms a string to a valid path. + +```js +hexo.route.format("archives/"); +// archives/index.html +``` + +[Stream]: http://nodejs.org/api/stream.html +[Buffer]: http://nodejs.org/api/buffer.html diff --git a/source/fa/api/scaffolds.md b/source/fa/api/scaffolds.md new file mode 100644 index 0000000000..e7ba7c37c1 --- /dev/null +++ b/source/fa/api/scaffolds.md @@ -0,0 +1,21 @@ +--- +title: Scaffolds +--- + +## Get a Scaffold + +```js +hexo.scaffold.get(name); +``` + +## Set a Scaffold + +```js +hexo.scaffold.set(name, content); +``` + +## Remove a Scaffold + +```js +hexo.scaffold.remove(name); +``` diff --git a/source/fa/api/tag.md b/source/fa/api/tag.md new file mode 100644 index 0000000000..3df8f8d0c4 --- /dev/null +++ b/source/fa/api/tag.md @@ -0,0 +1,169 @@ +--- +title: Tag +--- + +A tag allows users to quickly and easily insert snippets into their posts. + +## Synopsis + +```js +hexo.extend.tag.register( + name, + function (args, content) { + // ... + }, + options, +); +``` + +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. + +Since the introduction of asynchronous rendering in Hexo 3, we are using [Nunjucks][] for rendering. 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. + +```js +hexo.extend.tag.unregister(name); +``` + +**Example** + +```js +const tagFn = (args, content) => { + content = "something"; + return content; +}; + +// https://hexo.io/docs/tag-plugins#YouTube +hexo.extend.tag.unregister("youtube"); + +hexo.extend.tag.register("youtube", tagFn); +``` + +## Options + +### ends + +Use end tags. This option is `false` by default. + +### async + +Enable async mode. This option is `false` by default. + +## Examples + +### Without End Tags + +Insert a Youtube video. + +```js +hexo.extend.tag.register("youtube", function (args) { + var id = args[0]; + return ( + '<div class="video-container"><iframe width="560" height="315" src="http://www.youtube.com/embed/' + + id + + '" frameborder="0" allowfullscreen></iframe></div>' + ); +}); +``` + +### With End Tags + +Insert a pull quote. + +```js +hexo.extend.tag.register( + "pullquote", + function (args, content) { + var className = args.join(" "); + return ( + '<blockquote class="pullquote' + + className + + '">' + + content + + "</blockquote>" + ); + }, + { ends: true }, +); +``` + +### Async Rendering + +Insert a file. + +```js +var fs = require("hexo-fs"); +var pathFn = require("path"); + +hexo.extend.tag.register( + "include_code", + function (args) { + var filename = args[0]; + var path = pathFn.join(hexo.source_dir, filename); + + return fs.readFile(path).then(function (content) { + return "<pre><code>" + content + "</code></pre>"; + }); + }, + { async: true }, +); +``` + +## Front-matter and user configuration + +Any of the following options is valid: + +1. + +```js +hexo.extend.tag.register('foo', function (args) { + const [firstArg] = args; + + // User config + const { config } = hexo; + const editor = config.author + firstArg; + + // Theme config + const { config: themeCfg } = hexo.theme; + if (themeCfg.fancybox) // do something... + + // 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. + +```js index.js +hexo.extend.tag.register("foo", require("./lib/foo")(hexo)); +``` + +```js lib/foo.js +module.exports = hexo => { + return function fooFn(args) { + const [firstArg] = args; + + const { config } = hexo; + const editor = config.author + firstArg; + + const { config: themeCfg } = hexo.theme; + if (themeCfg.fancybox) // do something... + + const { title, _content, content } = this; + + return 'foo'; + }; +}; +``` + +[Nunjucks]: https://mozilla.github.io/nunjucks/ +[Swig]: https://node-swig.github.io/swig-templates/ diff --git a/source/fa/api/themes.md b/source/fa/api/themes.md new file mode 100644 index 0000000000..8e4e6e54b6 --- /dev/null +++ b/source/fa/api/themes.md @@ -0,0 +1,37 @@ +--- +title: Themes +--- + +`hexo.theme` inherits from [Box](box.html), and also saves templates. + +## 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 + +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"); + +view.render({ foo: 1, bar: 2 }).then(function (result) { + // ... +}); +``` + +You can pass options to the `render` method and it will try to process the template with the corresponding renderer and load the [helpers](helper.html). When rendering is complete, it will try to find whether a layout exists. If `layout` is `false` or if it doesn't exist, the result will be returned directly. diff --git a/source/fa/docs/asset-folders.md b/source/fa/docs/asset-folders.md new file mode 100644 index 0000000000..e99495b33c --- /dev/null +++ b/source/fa/docs/asset-folders.md @@ -0,0 +1,55 @@ +--- +title: Asset Folders +--- + +## Global Asset Folder + +Assets are non-post files in the `source` folder, such as images, CSS or JavaScript files. 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 +``` + +With asset folder management enabled, Hexo will create a folder every time you make a new post with the `hexo new [layout] <title>` command. 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 + +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. However, with the release of Hexo 3, several new [tag plugins](/docs/tag-plugins#Include-Assets) were added to core. These enable you to reference your assets more easily in posts: + +``` +{% asset_path slug %} +{% asset_img slug [title] %} +{% 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. + +## Embedding an image using markdown + +[hexo-renderer-marked](https://github.com/hexojs/hexo-renderer-marked) 3.1.0 introduced a new option that allows you to embed an image in markdown without using `asset_img` tag plugin. + +To enable: + +```yml _config.yml +post_asset_folder: true +marked: + prependRoot: true + postAsset: true +``` + +Once enabled, an asset image will be automatically resolved to its corresponding post's path. For example, "image.jpg" is located at "/2020/01/02/foo/image.jpg", meaning it is an asset image of "/2020/01/02/foo/" post, `![](image.jpg)` will be rendered as `<img src="/2020/01/02/foo/image.jpg">`. diff --git a/source/fa/docs/commands.md b/source/fa/docs/commands.md new file mode 100644 index 0000000000..2734d86b5f --- /dev/null +++ b/source/fa/docs/commands.md @@ -0,0 +1,202 @@ +--- +title: Commands +--- + +## init + +```bash +$ hexo init [folder] +``` + +Initializes a website. If no `folder` is provided, Hexo will set up a website in the current directory. + +This command is a shortcut that runs the following steps: + +1. Git clone [hexo-starter](https://github.com/hexojs/hexo-starter) including [hexo-theme-landscape](https://github.com/hexojs/hexo-theme-landscape) into the current directory or a target folder if specified. +2. Install dependencies using a package manager: [Yarn 1](https://classic.yarnpkg.com/lang/en/), [pnpm](https://pnpm.io) or [npm](https://docs.npmjs.com/cli/install), whichever is installed; if there are more than one installed, the priority is as listed. npm is bundled with [Node.js](/docs/#Install-Node-js) by default. + +## new + +```bash +$ hexo new [layout] <title> +``` + +Creates a new article. If no `layout` is provided, Hexo will use the `default_layout` from [\_config.yml](configuration.html). Use the layout `draft` to create a draft. If the `title` contains spaces, surround it with quotation marks. + +| Option | Description | +| ----------------- | ------------------------------------------ | +| `-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 + +```bash +$ hexo generate +``` + +Generates static files. + +| Option | Description | +| --------------------- | ------------------------------------------------------------------------ | +| `-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 + +```bash +$ hexo publish [layout] <filename> +``` + +Publishes a draft. + +## server + +```bash +$ hexo server +``` + +Starts a local server. By default, this is at `http://localhost:4000/`. + +| Option | Description | +| ---------------- | -------------------------------------- | +| `-p`, `--port` | Override default port | +| `-s`, `--static` | Only serve static files | +| `-l`, `--log` | Enable logger. Override logger format. | + +## deploy + +```bash +$ hexo deploy +``` + +Deploys your website. + +| Option | Description | +| ------------------ | -------------------------- | +| `-g`, `--generate` | Generate before deployment | + +## render + +```bash +$ hexo render <file1> [file2] ... +``` + +Renders files. + +| Option | Description | +| ---------------- | ------------------ | +| `-o`, `--output` | Output destination | + +## migrate + +```bash +$ hexo migrate <type> +``` + +[Migrates](migration.html) content from other blog systems. + +## clean + +```bash +$ hexo clean +``` + +Cleans the cache file (`db.json`) and generated files (`public`). + +## list + +```bash +$ hexo list <type> +``` + +Lists all routes. + +## version + +```bash +$ hexo version +``` + +Displays version information. + +## 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`. + +## Options + +### Safe mode + +```bash +$ hexo --safe +``` + +Disables loading plugins and scripts. Try this if you encounter problems after installing a new plugin. + +### Debug mode + +```bash +$ hexo --debug +``` + +Logs verbose messages to the terminal and to `debug.log`. Try this if you encounter any problems with Hexo. If you see errors, please [raise a GitHub issue](https://github.com/hexojs/hexo/issues/new?assignees=&labels=&projects=&template=bug_report.yml). + +### Silent mode + +```bash +$ hexo --silent +``` + +Silences output to the terminal. + +### Customize config file path + +```bash +$ hexo --config custom.yml +``` + +Uses a custom config file (instead of `_config.yml`). Also accepts a comma-separated list (no spaces) of JSON or YAML config files that will combine the files into a single `_multiconfig.yml`. + +```bash +$ hexo --config custom.yml,custom2.json +``` + +### Display drafts + +```bash +$ hexo --draft +``` + +Displays draft posts (stored in the `source/_drafts` folder). + +### Customize CWD + +```bash +$ hexo --cwd /path/to/cwd +``` + +Customizes the path of current working directory. diff --git a/source/fa/docs/configuration.md b/source/fa/docs/configuration.md new file mode 100644 index 0000000000..487a99b92f --- /dev/null +++ b/source/fa/docs/configuration.md @@ -0,0 +1,312 @@ +--- +title: Configuration +--- + +You can modify site settings in `_config.yml` or in an [alternate config file](#Using-an-Alternate-Config). + +### Site + +| Setting | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `title` | The title of your website | +| `subtitle` | The subtitle of your website | +| `description` | The description of your website | +| `keywords` | The keywords of your website. Supports multiple values. | +| `author` | Your name | +| `language` | The language of your website. Use a [2-letter ISO-639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) or optionally [its variant](/docs/internationalization). Default is `en`. | +| `timezone` | The timezone of your website. Hexo uses the setting on your computer by default. You can find the list of available timezones [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Some examples are `America/New_York`, `Japan`, and `UTC`. | + +### URL + +| Setting | Description | Default | +| ---------------------------- | ----------------------------------------------------------------------------------------- | --------------------------- | +| `url` | The URL of your website, must start with `http://` or `https://` | | +| `root` | The root directory of your website | `url's pathname` | +| `permalink` | The [permalink](permalinks.html) format of articles | `:year/:month/:day/:title/` | +| `permalink_defaults` | Default values of each segment in permalink | | +| `pretty_urls` | Rewrite the [`permalink`](permalinks.html) variables to pretty URLs | | +| `pretty_urls.trailing_index` | Trailing `index.html`, set to `false` to remove it | `true` | +| `pretty_urls.trailing_html` | Trailing `.html`, set to `false` to remove it (_does not apply to trailing `index.html`_) | `true` | + +{% note info Website in subdirectory %} +If your website is in a subdirectory (such as `http://example.org/blog`) set `url` to `http://example.org/blog` and set `root` to `/blog/`. +{% endnote %} + +Examples: + +```yaml +# e.g. page.permalink is http://example.com/foo/bar/index.html +pretty_urls: + trailing_index: false +# becomes http://example.com/foo/bar/ +``` + +### Directory + +| Setting | Description | 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` | Category directory | `categories` | +| `code_dir` | Include code directory (subdirectory of `source_dir`) | `downloads/code` | +| `i18n_dir` | i18n directory | `:lang` | +| `skip_render` | Paths that will be copied to `public` raw, without being rendered. You can use [glob expressions](https://github.com/micromatch/micromatch#extended-globbing) for path matching. | | + +Examples: + +```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`. +``` + +### Writing + +| Setting | Description | Default | +| ----------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------- | +| `new_post_name` | The filename format for new posts | `:title.md` | +| `default_layout` | Default layout | `post` | +| `titlecase` | Transform titles into 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` | Applies to the whole `site` or `post` only | `site` | +| `external_link.exclude` | Exclude hostname. Specify subdomain when applicable, including `www` | `[]` | +| `filename_case` | Transform filenames to `1` lower case; `2` upper case | `0` | +| `render_drafts` | Display drafts? | `false` | +| `post_asset_folder` | Enable the [Asset Folder](asset-folders.html)? | `false` | +| `relative_link` | Make links relative to the root folder? | `false` | +| `future` | Display future posts? | `true` | +| `syntax_highlighter` | Code block syntax highlight settings, see [Syntax Highlight](/docs/syntax-highlight) section for usage guide | `highlight.js` | +| `highlight` | Code block syntax highlight settings, see [Highlight.js](/docs/syntax-highlight#Highlight-js) section for usage guide | | +| `prismjs` | Code block syntax highlight settings, see [PrismJS](/docs/syntax-highlight#PrismJS) section for usage guide | | + +### Home page setting + +| Setting | Description | 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` | + +### Category & Tag + +| Setting | Description | Default | +| ------------------ | ----------------------- | --------------- | +| `default_category` | Default category | `uncategorized` | +| `category_map` | Override category slugs | | +| `tag_map` | Override tag slugs | | + +Examples: + +```yaml +category_map: + "yesterday's thoughts": yesterdays-thoughts + "C++": c-plus-plus +``` + +### Date / Time format + +Hexo uses [Moment.js](http://momentjs.com/) to process dates. + +| Setting | Description | Default | +| ---------------- | --------------------------------------------------------------------------------------------------- | ------------ | +| `date_format` | Date format | `YYYY-MM-DD` | +| `time_format` | Time format | `HH:mm:ss` | +| `updated_option` | The [`updated`](/docs/variables#Page-Variables) value to used when not provided in the front-matter | `mtime` | + +{% note info updated_option %} +`updated_option` controls the `updated` value when not provided in the front-matter: + +- `mtime`: Use file modification date as `updated`. It has been the default behaviour of Hexo since 3.0.0 +- `date`: Use `date` as `updated`. Typically used with Git workflow when file modification date could be different. +- `empty`: Simply drop `updated` when not provided. May not be compatible with most themes and plugins. + +`use_date_for_updated` is removed in v7.0.0+. Please use `updated_option: 'date'` instead. +{% endnote %} + +### Pagination + +| Setting | Description | Default | +| ---------------- | --------------------------------------------------------------- | ------- | +| `per_page` | Number of posts displayed on each page. `0` disables pagination | `10` | +| `pagination_dir` | URL format | `page` | + +Examples: + +```yaml +pagination_dir: 'page' +# http://example.com/page/2 + +pagination_dir: 'awesome-page' +# http://example.com/awesome-page/2 +``` + +### Extensions + +| Setting | Description | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `theme` | Theme name. `false` disables theming | +| `theme_config` | Theme configuration. Include any custom theme settings under this key to override theme defaults. | +| `deploy` | Deployment settings | +| `meta_generator` | [Meta generator](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#Attributes) tag. `false` disables injection of the tag. | + +### Include/Exclude Files or Folders + +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` and `exclude` options only apply to the `source/` folder, whereas `ignore` option applies to all folders. + +| Setting | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------- | +| `include` | Include hidden files (including files/folders with a name that starts with an underscore, with an exception\*) | +| `exclude` | Exclude files/folders | +| `ignore` | Ignore files/folders | + +Examples: + +```yaml +# Include/Exclude Files/Folders +include: + - ".nojekyll" + # Include 'source/css/_typing.css'. + - "css/_typing.css" + # Include any file in 'source/_css/'. + - "_css/*" + # Include any file and subfolder in 'source/_css/'. + - "_css/**/*" + +exclude: + # Exclude 'source/js/test.js'. + - "js/test.js" + # Exclude any file in 'source/js/'. + - "js/*" + # Exclude any file and subfolder in 'source/js/'. + - "js/**/*" + # Exclude any file with filename that starts with 'test' in 'source/js/'. + - "js/test*" + # Exclude any file with filename that starts with 'test' in 'source/js/' and its subfolders. + - "js/**/test*" + # Do not use this to exclude posts in the 'source/_posts/'. + # Use skip_render for that. Or prepend an underscore to the filename. + # - "_posts/hello-world.md" # Does not work. + +ignore: + # Ignore any folder named 'foo'. + - "**/foo" + # Ignore 'foo' folder in 'themes/' only. + - "**/themes/*/foo" + # 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:` and `exclude:` do not apply to the `themes/` folder. Either use `ignore:` or alternatively, prepend an underscore to the file/folder name to exclude. + +\* 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. + +### Using an Alternate Config + +A custom config file path can be specified by adding the `--config` flag to your `hexo` commands with a path to an alternate YAML or JSON config file, or a comma-separated list (no spaces) of multiple YAML or JSON files. + +```bash +# use 'custom.yml' in place of '_config.yml' +$ hexo server --config custom.yml + +# use 'custom.yml' & 'custom2.json', prioritizing 'custom2.json' +$ hexo server --config custom.yml,custom2.json +``` + +Using multiple files combines all the config files and saves the merged settings to `_multiconfig.yml`. The later values take precedence. It works with any number of JSON and YAML files with arbitrarily deep objects. Note that **no spaces are allowed in the list**. + +For instance, in the above example if `foo: bar` is in `custom.yml`, but `"foo": "dinosaur"` is in `custom2.json`, `_multiconfig.yml` will contain `foo: dinosaur`. + +### Alternate Theme Config + +Hexo themes are independent projects, with separate `_config.yml` files. + +Instead of forking a theme, and maintaining a custom version with your settings, you can configure it from somewhere else: + +**from `theme_config` in site's primary configuration file** + +> Supported since Hexo 2.8.2 + +```yml +# _config.yml +theme: "my-theme" +theme_config: + bio: "My awesome bio" + foo: + bar: "a" +``` + +```yml +# themes/my-theme/_config.yml +bio: "Some generic bio" +logo: "a-cool-image.png" + foo: + baz: 'b' +``` + +Resulting in theme configuration: + +```json +{ + "bio": "My awesome bio", + "logo": "a-cool-image.png", + "foo": { + "bar": "a", + "baz": "b" + } +} +``` + +**from a dedicated `_config.[theme].yml` file** + +> Supported since Hexo 5.0.0 + +The file should be placed in your site folder, both `yml` and `json` are supported. `theme` inside `_config.yml` must be configured for Hexo to read `_config.[theme].yml` + +```yml +# _config.yml +theme: "my-theme" +``` + +```yml +# _config.my-theme.yml +bio: "My awesome bio" +foo: + bar: "a" +``` + +```yml +# themes/my-theme/_config.yml +bio: "Some generic bio" +logo: "a-cool-image.png" + foo: + baz: 'b' +``` + +Resulting in theme configuration: + +```json +{ + "bio": "My awesome bio", + "logo": "a-cool-image.png", + "foo": { + "bar": "a", + "baz": "b" + } +} +``` + +{% note %} +We strongly recommend that you store your theme configuration in one place. But in case you have to store your theme configuration separately, you need to know the priority of those configurations: The `theme_config` inside site's primary configuration file has the highest priority during merging, then the dedicated theme configuration file. The `_config.yml` file under the theme directory has the lowest priority. +{% endnote %} diff --git a/source/fa/docs/contributing.md b/source/fa/docs/contributing.md new file mode 100644 index 0000000000..d645279a23 --- /dev/null +++ b/source/fa/docs/contributing.md @@ -0,0 +1,111 @@ +--- +title: Contributing +--- + +We welcome you to join the development of Hexo. 🤗 + +## Development + +We welcome you to join the development of Hexo. This document will help you through the process. + +### Before You Start + +Please read [Contributor Covenant Code of Conduct](https://github.com/hexojs/hexo/blob/master/CODE_OF_CONDUCT.md) first. + +Please follow the coding style: + +- Follow [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html). +- Use soft-tabs with a two space indent. +- Don't put commas first. + +Also, Hexo has its own [ESLint config](https://github.com/hexojs/eslint-config-hexo), so please make sure your contribution will make ESLint happy. + +### Workflow + +1. Fork [hexojs/hexo][]. +2. Clone the repository to your computer and install dependencies. + +```bash +$ git clone https://github.com/<username>/hexo.git +$ cd hexo +$ npm install +$ git submodule update --init +``` + +3. Create a feature branch. + +```bash +$ git checkout -b new_feature +``` + +4. Start hacking. +5. Push the branch: + +``` +$ git push origin new_feature +``` + +6. Create a pull request and describe the change. + +### Notice + +- Please don't modify version number in `package.json`. +- Your pull request will only get merged when tests passed. Don't forget to run tests before submission. + +```bash +$ npm test +``` + +## Updating official-plugins + +Also, we welcome PR or issue to [official-plugins](https://github.com/hexojs). 🤗 + +## Updating Documentation + +The Hexo documentation is open source and you can find the source code on [hexojs/site][]. + +### Workflow + +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 +$ git clone https://github.com/<username>/site.git +$ cd site +$ npm install +``` + +3. Start editing the documentation. You can start the server for live previewing. + +```bash +$ hexo server +``` + +4. Push the branch. +5. Create a pull request and describe the change. + +### Translating + +#### Contribute translations + +[![Crowdin](https://badges.crowdin.net/hexo/localized.svg)](https://crowdin.com/project/hexo) + +Now we use the [Crowdin](https://crowdin.com/project/hexo) platform for translation, where anyone can contribute translations and vote for translations without manual git operations. + +#### Add a new language + +1. Submit a new issue to let us know. The members with access to the [Crowdin Project](https://crowdin.com/project/hexo) add the language in settings. +1. After adding language in Crowdin, anyone can contribute translations on it. +1. Add the new language to [`source/_data/language.yml`](https://github.com/hexojs/site/blob/master/source/_data/languages.yml). +1. Copy `en.yml` in [`themes/navy/languages`](https://github.com/hexojs/site/tree/master/themes/navy/languages) and rename it to the language name (all lower case). + +## Reporting Issues + +When you encounter some problems when using Hexo, you can find the solutions in [Troubleshooting](troubleshooting.html) or ask me on [GitHub](https://github.com/hexojs/hexo/issues) or [Google Group](https://groups.google.com/group/hexo). If you can't find the answer, please report it on GitHub. + +1. Represent the problem in [debug mode](commands.html#Debug_mode). +2. Follow the steps from the issue template to provide a debug message and version when submitting a new issue at GitHub. + +[hexojs/hexo]: https://github.com/hexojs/hexo +[hexojs/site]: https://github.com/hexojs/site diff --git a/source/fa/docs/data-files.md b/source/fa/docs/data-files.md new file mode 100644 index 0000000000..e9474aab1a --- /dev/null +++ b/source/fa/docs/data-files.md @@ -0,0 +1,31 @@ +--- +title: Data Files +--- + +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**. This feature loads YAML or JSON files in `source/_data` folder so you can use them in your site. + +{% youtube CN31plHbI-w %} + +For example, add `menu.yml` in `source/_data` folder. + +```yaml +Home: / +Gallery: /gallery/ +Archives: /archives/ +``` + +And you can use them in templates: + +``` +<% for (var link in site.data.menu) { %> + <a href="<%= site.data.menu[link] %>"> <%= link %> </a> +<% } %> +``` + +render like this : + +``` +<a href="/"> Home </a> +<a href="/gallery/"> Gallery </a> +<a href="/archives/"> Archives </a> +``` diff --git a/source/fa/docs/front-matter.md b/source/fa/docs/front-matter.md new file mode 100644 index 0000000000..276b058c4a --- /dev/null +++ b/source/fa/docs/front-matter.md @@ -0,0 +1,75 @@ +--- +title: Front-matter +--- + +{% youtube pfD6FCZdW4Q %} + +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 +--- +title: Hello World +date: 2013/7/13 20:46:25 +--- +``` + +**JSON** + +```json +"title": "Hello World", +"date": "2013/7/13 20:46:25" +;;; +``` + +### Settings & Their Default Values + +| Setting | Description | Default | +| ----------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `layout` | Layout | [`config.default_layout`](/docs/configuration#Writing) | +| `title` | Title | Filename (posts only) | +| `date` | Published date | File created date | +| `updated` | Updated date | File updated date | +| `comments` | Enables comment feature for the post | `true` | +| `tags` | Tags (Not available for pages) | | +| `categories` | Categories (Not available for pages) | | +| `permalink` | Overrides the default permalink of the post. Permalink should end with `/` or `.html` | `null` | +| `excerpt` | Page excerpt in plain text. Use [this plugin](/docs/tag-plugins#Post-Excerpt) to format the text | | +| `disableNunjucks` | Disable rendering of Nunjucks tag `{{ }}`/`{% %}` and [tag plugins](/docs/tag-plugins) when enabled | false | +| `lang` | Set the language to override [auto-detection](/docs/internationalization#Path) | Inherited from `_config.yml` | +| `published` | Whether the post should be published | For posts under `_posts`, it is `true`, and for posts under `_draft`, it is `false` | + +#### Layout + +The default layout is `post`, in accordance with the value of [`default_layout`](/docs/configuration#Writing) setting in `_config.yml`. When the layout is disabled (`layout: false`) in an article, it will not be processed with a theme. However, it will still be rendered by any available renderer: if an article is written in Markdown and a Markdown renderer (like the default [hexo-renderer-marked](https://github.com/hexojs/hexo-renderer-marked)) is installed, it will be rendered to HTML. + +[Tag plugins](/docs/tag-plugins) are always processed regardless of layout, unless disabled by the `disableNunjucks` setting or [renderer](/api/renderer#Disable-Nunjucks-tags). + +#### Categories & 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. + +**Example** + +```yaml +categories: + - Sports + - Baseball +tags: + - Injury + - Fight + - Shocking +``` + +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: + - [Sports, Baseball] + - [MLB, American League, Boston Red Sox] + - [MLB, American League, New York Yankees] + - Rivalries +``` diff --git a/source/fa/docs/generating.md b/source/fa/docs/generating.md new file mode 100644 index 0000000000..2cd48f4208 --- /dev/null +++ b/source/fa/docs/generating.md @@ -0,0 +1,28 @@ +--- +title: Generating +--- + +Generating static files with Hexo is quite easy and fast. + +```bash +$ hexo generate +``` + +{% youtube viEJQPVCoLU %} + +### Watch for File Changes + +Hexo can watch for file changes and regenerate files immediately. Hexo will compare the SHA1 checksum of your files and only write if file changes are detected. + +```bash +$ hexo generate --watch +``` + +### Deploy After Generating + +To deploy after generating, you can run one of the following commands. There is no difference between the two. + +```bash +$ hexo generate --deploy +$ hexo deploy --generate +``` diff --git a/source/fa/docs/github-pages.md b/source/fa/docs/github-pages.md new file mode 100644 index 0000000000..01491e3cef --- /dev/null +++ b/source/fa/docs/github-pages.md @@ -0,0 +1,111 @@ +--- +title: GitHub Pages +--- + +In this tutorial, we use [GitHub Actions](https://docs.github.com/en/actions) to deploy GitHub Pages. It works in both public and private repositories. Skip to the [One-command deployment](#One-command-deployment) section if you prefer not to upload your source folder to GitHub. + +1. Create a repo named <b>_username_.github.io</b>, where username is your username on GitHub. 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. The default branch is usually **main**, older repositories may use **master** branch. + +- To push `main` branch to GitHub: + + ``` + $ git push -u origin main + ``` + +- The `public/` folder is not (and should not be) uploaded by default, make sure the `.gitignore` file contains `public/` line. The folder structure should be roughly similar to [this repo](https://github.com/hexojs/hexo-starter). + +3. 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., `v20.y.z`) +4. In your GitHub repo's setting, navigate to **Settings** > **Pages** > **Source**. Change the source to **GitHub Actions** and save. +5. Create `.github/workflows/pages.yml` in your repo with the following contents (substituting `20` to the major version of Node.js that you noted in previous step): + +```yml .github/workflows/pages.yml +name: Pages + +on: + push: + branches: + - main # default branch + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + # If your repository depends on submodule, please see: https://github.com/actions/checkout + submodules: recursive + - name: Use Node.js 20 + uses: actions/setup-node@v4 + with: + # Examples: 20, 18.19, >=16.20.2, lts/Iron, lts/Hydrogen, *, latest, current, node + # Ref: https://github.com/actions/setup-node#supported-version-syntax + node-version: "20" + - name: Cache NPM dependencies + uses: actions/cache@v4 + with: + path: node_modules + key: ${{ runner.OS }}-npm-cache + restore-keys: | + ${{ runner.OS }}-npm-cache + - name: Install Dependencies + run: npm install + - name: Build + run: npm run build + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./public + deploy: + needs: build + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 +``` + +6. Once the deployment is finished, check the webpage at _username_.github.io. + +Note - if you specify a custom domain name with a `CNAME`, you need to add the `CNAME` file to the `source/` folder. [More info](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 + +If you prefer to have a project page on GitHub: + +1. Navigate to your repo on GitHub. Go to the **Settings** tab. Change the **Repository name** so your blog is available at <b>username.github.io/_repository_</b>, **repository** can be any name, like _blog_ or _hexo_. +2. Edit your **\_config.yml**, change the `url:` value to <b>https://_username_.github.io/_repository_</b>. +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 + +The following instruction is adapted from [one-command deployment](/docs/one-command-deployment) page. + +1. Install [hexo-deployer-git](https://github.com/hexojs/hexo-deployer-git). +2. Add the following configurations to **\_config.yml**, (remove existing lines if any). + +```yml +deploy: + type: git + repo: https://github.com/<username>/<project> + # example, https://github.com/hexojs/hexojs.github.io + branch: gh-pages +``` + +3. Run `hexo clean && hexo deploy`. +4. Check the webpage at _username_.github.io. + +## Useful links + +- [GitHub Pages](https://docs.github.com/en/pages) +- [Publishing with a custom GitHub Actions workflow](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/fa/docs/gitlab-pages.md b/source/fa/docs/gitlab-pages.md new file mode 100644 index 0000000000..b4d102a2ab --- /dev/null +++ b/source/fa/docs/gitlab-pages.md @@ -0,0 +1,45 @@ +--- +title: GitLab Pages +--- + +1. Create a new repository named <b>_username_.gitlab.io</b>, where username is your username on GitLab. If you have already uploaded to other repo, rename the repo instead. +2. Enable Shared Runners via **Settings** > **CI/CD** > **Runners** > **Enable shared runners for this project**. +3. Push the files of your Hexo folder to the repository. The `public/` folder is not (and should not be) uploaded by default, make sure the `.gitignore` file contains `public/` line. The folder structure should be roughly similar to [this repo](https://gitlab.com/pages/hexo). +4. Check what version of Node.js you are using on your local machine with `node --version`. Make a note of the major version (e.g., `v16.y.z`) +5. Add `.gitlab-ci.yml` file to the root folder of your repo (alongside \_config.yml & package.json) with the following content (replacing `16` with the major version of Node.js you noted in previous step): + +```yml +image: node:16-alpine +cache: + paths: + - node_modules/ + +before_script: + - npm install hexo-cli -g + - npm install + +pages: + script: + - npm run build + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH +``` + +6. _username_.gitlab.io should be up and running, once GitLab CI finishes the deployment job, +7. (Optional) If you wish to inspect the generated site assets (html, css, js, etc), they can be found in the [job artifact](https://docs.gitlab.com/ee/ci/jobs/job_artifacts.html). + +## Project page + +If you prefer to have a project page on GitLab: + +1. Go to **Settings** > **General** > **Advanced** > **Change path**. Change the value to a name, so the website is available at <b>username.gitlab.io/_repository_</b>. It can be any name, like _blog_ or _hexo_. +2. Edit **\_config.yml**, change the `url:` value to `https://username.gitlab.io/repository`. +3. Commit and push. + +## Useful links + +- [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/) +- [GitLab CI Docs](https://docs.gitlab.com/ee/ci/yaml/) diff --git a/source/fa/docs/helpers.md b/source/fa/docs/helpers.md new file mode 100644 index 0000000000..6573427eca --- /dev/null +++ b/source/fa/docs/helpers.md @@ -0,0 +1,981 @@ +--- +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 + +### url_for + +Returns a URL with the root path prefixed. Output is encoded automatically. + +```js +<%- url_for(path, [option]) %> +``` + +| 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 + +Returns the relative URL from `from` to `to`. + +```js +<%- 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 + +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, [options]) %> +``` + +| Option | Description | Default | +| ------ | ----------------- | ------- | +| `s` | Output image size | 80 | +| `d` | Default image | | +| `f` | Force default | | +| `r` | Rating | | + +More info: [Gravatar](https://en.gravatar.com/site/implement/images/) + +**Examples:** + +```js +<%- gravatar('a@abc.com') %> +// https://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787 + +<%- gravatar('a@abc.com', 40) %> +// https://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787?s=40 + +<%- gravatar('a@abc.com' {s: 40, d: 'https://via.placeholder.com/150'}) %> +// https://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787?s=40&d=https%3A%2F%2Fvia.placeholder.com%2F150 +``` + +## HTML Tags + +### css + +Loads CSS files. `path` can be a string, an array, an object or an array of objects. [`/<root>/`](/docs/configuration#URL) value is prepended while `.css` extension is appended to the `path` automatically. Use object type for custom attributes. + +```js +<%- css(path, ...) %> +``` + +**Examples:** + +```js +<%- css('style.css') %> +// <link rel="stylesheet" href="/style.css"> + +<%- css(['style.css', 'screen.css']) %> +// <link rel="stylesheet" href="/style.css"> +// <link rel="stylesheet" href="/screen.css"> + +<%- css({ href: 'style.css', integrity: 'foo' }) %> +// <link rel="stylesheet" href="/style.css" integrity="foo"> + +<%- css([{ href: 'style.css', integrity: 'foo' }, { href: 'screen.css', integrity: 'bar' }]) %> +// <link rel="stylesheet" href="/style.css" integrity="foo"> +// <link rel="stylesheet" href="/screen.css" integrity="bar"> +``` + +### js + +Loads JavaScript files. `path` can be a string, an array, an object or an array of objects. [`/<root>/`](/docs/configuration#URL) value is prepended while `.js` extension is appended to the `path` automatically. Use object type for custom attributes. + +```js +<%- js(path, ...) %> +``` + +**Examples:** + +```js +<%- js('script.js') %> +// <script src="/script.js"></script> + +<%- js(['script.js', 'gallery.js']) %> +// <script src="/script.js"></script> +// <script src="/gallery.js"></script> + +<%- js({ src: 'script.js', integrity: 'foo', async: true }) %> +// <script src="/script.js" integrity="foo" async></script> + +<%- js([{ src: 'script.js', integrity: 'foo' }, { src: 'gallery.js', integrity: 'bar' }]) %> +// <script src="/script.js" integrity="foo"></script> +// <script src="/gallery.js" integrity="bar"></script> +``` + +### link_to + +Inserts a link. + +```js +<%- link_to(path, [text], [options]) %> +``` + +| Option | Description | Default | +| ---------- | --------------------------- | ------- | +| `external` | Opens the link in a new tab | false | +| `class` | Class name | | +| `id` | ID | | + +**Examples:** + +```js +<%- link_to('http://www.google.com') %> +// <a href="http://www.google.com" title="http://www.google.com">http://www.google.com</a> + +<%- link_to('http://www.google.com', 'Google') %> +// <a href="http://www.google.com" title="Google">Google</a> + +<%- link_to('http://www.google.com', 'Google', {external: true}) %> +// <a href="http://www.google.com" title="Google" target="_blank" rel="noopener">Google</a> +``` + +### mail_to + +Inserts a mail link. + +```js +<%- mail_to(path, [text], [options]) %> +``` + +| Option | Description | +| --------- | ------------ | +| `class` | Class name | +| `id` | ID | +| `subject` | Mail subject | +| `cc` | CC | +| `bcc` | BCC | +| `body` | Mail content | + +**Examples:** + +```js +<%- mail_to('a@abc.com') %> +// <a href="mailto:a@abc.com" title="a@abc.com">a@abc.com</a> + +<%- mail_to('a@abc.com', 'Email') %> +// <a href="mailto:a@abc.com" title="Email">Email</a> +``` + +### image_tag + +Inserts an image. + +```js +<%- image_tag(path, [options]) %> +``` + +| Option | Description | +| -------- | ----------------------------- | +| `alt` | Alternative text of the image | +| `class` | Class name | +| `id` | ID | +| `width` | Image width | +| `height` | Image height | + +### favicon_tag + +Inserts a favicon. + +```js +<%- favicon_tag(path) %> +``` + +### feed_tag + +Inserts a feed link. + +```js +<%- feed_tag(path, [options]) %> +``` + +| Option | Description | Default | +| ------- | ----------- | -------------- | +| `title` | Feed title | `config.title` | +| `type` | Feed type | | + +**Examples:** + +```js +<%- feed_tag('atom.xml') %> +// <link rel="alternate" href="/atom.xml" title="Hexo" type="application/atom+xml"> + +<%- feed_tag('rss.xml', { title: 'RSS Feed', type: 'rss' }) %> +// <link rel="alternate" href="/atom.xml" title="RSS Feed" type="application/atom+xml"> + +/* Defaults to hexo-generator-feed's config if no argument */ +<%- feed_tag() %> +// <link rel="alternate" href="/atom.xml" title="Hexo" type="application/atom+xml"> +``` + +## Conditional Tags + +### is_current + +Check whether `path` matches the URL of the current page. Use `strict` options to enable strict matching. + +```js +<%- is_current(path, [strict]) %> +``` + +### is_home + +Check whether the current page is home page. + +```js +<%- 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 +<%- is_page() %> +``` + +### is_archive + +Check whether the current page is an archive page. + +```js +<%- is_archive() %> +``` + +### is_year + +Check whether the current page is a yearly archive page. + +```js +<%- is_year() %> +``` + +### is_month + +Check whether the current page is a monthly archive page. + +```js +<%- is_month() %> +``` + +### 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() %> +<%- is_category('hobby') %> +``` + +### 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() %> +<%- is_tag('hobby') %> +``` + +## String Manipulation + +### trim + +Removes prefixing and trailing spaces of a string. + +```js +<%- trim(string) %> +``` + +### strip_html + +Sanitizes all HTML tags in a string. + +```js +<%- strip_html(string) %> +``` + +**Examples:** + +```js +<%- strip_html('It\'s not <b>important</b> anymore!') %> +// It's not important anymore! +``` + +### titlecase + +Transforms a string into proper title caps. + +```js +<%- titlecase(string) %> +``` + +**Examples:** + +```js +<%- titlecase('this is an apple') %> +# This is an Apple +``` + +### markdown + +Renders a string with Markdown. + +```js +<%- markdown(str) %> +``` + +**Examples:** + +```js +<%- markdown('make me **strong**') %> +// make me <strong>strong</strong> +``` + +### render + +Renders a string. + +```js +<%- render(str, engine, [options]) %> +``` + +**Examples:** + +```js +<%- render('p(class="example") Test', 'pug'); %> +// <p class="example">Test</p> +``` + +See [Rendering](https://hexo.io/api/rendering) for more details. + +### word_wrap + +Wraps text into lines no longer than `length`. `length` is 80 by default. + +```js +<%- word_wrap(str, [length]) %> +``` + +**Examples:** + +```js +<%- word_wrap('Once upon a time', 8) %> +// Once upon\n a time +``` + +### truncate + +Truncates text after certain `length`. Default is 30 characters. + +```js +<%- truncate(text, [options]) %> +``` + +**Examples:** + +```js +<%- truncate('Once upon a time in a world far far away', {length: 17}) %> +// Once upon a ti... + +<%- 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 + +Escapes HTML entities in a string. + +```js +<%- escape_html(str) %> +``` + +**Examples:** + +```js +<%- escape_html('<p>Hello "world".</p>') %> +// <p>Hello "world".</p> +``` + +## Templates + +### partial + +Loads other template files. You can define local variables in `locals`. + +```js +<%- partial(layout, [locals], [options]) %> +``` + +| Option | Description | Default | +| ------- | ------------------------------------------------------------------------ | ------- | +| `cache` | Cache contents (Use fragment cache) | `false` | +| `only` | Strict local variables. Only use variables set in `locals` in templates. | `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(){ + return '<header></header>'; +}) %> +``` + +## Date & Time + +### date + +Inserts formatted date. `date` can be unix time, ISO string, date object, or [Moment.js][] object. `format` is `date_format` setting by default. + +```js +<%- date(date, [format]) %> +``` + +**Examples:** + +```js +<%- date(Date.now()) %> +// 2013-01-01 + +<%- date(Date.now(), 'YYYY/M/D') %> +// Jan 1 2013 +``` + +### date_xml + +Inserts date in XML format. `date` can be unix time, ISO string, date object, or [Moment.js][] object. + +```js +<%- date_xml(date) %> +``` + +**Examples:** + +```js +<%- date_xml(Date.now()) %> +// 2013-01-01T00:00:00.000Z +``` + +### time + +Inserts formatted time. `date` can be unix time, ISO string, date object, or [Moment.js][] object. `format` is `time_format` setting by default. + +```js +<%- time(date, [format]) %> +``` + +**Examples:** + +```js +<%- time(Date.now()) %> +// 13:05:12 + +<%- time(Date.now(), 'h:mm:ss a') %> +// 1:05:12 pm +``` + +### full_date + +Inserts formatted date and time. `date` can be unix time, ISO string, date object, or [Moment.js][] object. `format` is `date_format + time_format` setting by default. + +```js +<%- full_date(date, [format]) %> +``` + +**Examples:** + +```js +<%- full_date(new Date()) %> +// Jan 1, 2013 0:00:00 + +<%- full_date(new Date(), 'dddd, MMMM Do YYYY, h:mm:ss a') %> +// Tuesday, January 1st 2013, 12:00:00 am +``` + +### relative_date + +Inserts relative time from now. `date` can be unix time, ISO string, date object, or [Moment.js][] object. + +```js +<%- relative_date(date) %> +``` + +**Examples:** + +```js +<%- relative_date(new Date()) %> +// a few seconds ago + +<%- relative_date(new Date(1000000000000)) %> +// 22 years ago +``` + +### 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. + +```js +<%- time_tag(date, [format]) %> +``` + +**Examples:** + +```js +<%- time_tag(new Date()) %> +// <time datetime="2024-01-22T06:35:31.108Z">2024-01-22</time> + +<%- time_tag(new Date(), 'MMM-D-YYYY') %> +// <time datetime="2024-01-22T06:35:31.108Z">Jan-22-2024</time> +``` + +### moment + +[Moment.js][] library. + +## List + +### list_categories + +Inserts a list of all categories. + +```js +<%- list_categories([options]) %> +``` + +| Option | Description | Default | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `orderby` | Order of categories | name | +| `order` | Sort of order. `1`, `asc` for ascending; `-1`, `desc` for descending | 1 | +| `show_count` | Display the number of posts for each category | true | +| `style` | Style to display the category list. `list` displays categories in an unordered list. Use `false` or any other value to disable it. | list | +| `separator` | Separator between categories. (Only works if `style` is not `list`) | , | +| `depth` | Levels of categories to be displayed. `0` displays all categories and child categories; `-1` is similar to `0` but displayed in flat; `1` displays only top level categories. | 0 | +| `class` | Class name of category list. | category | +| `transform` | The function that changes the display of category name. | | +| `suffix` | Add a suffix to link. | None | + +**Examples:** + +```js +<%- list_categories(post.categories, { + class: 'post-category', + transform(str) { + return titlecase(str); + } +}) %> + +<%- list_categories(post.categories, { + class: 'post-category', + transform(str) { + return str.toUpperCase(); + } +}) %> +``` + +### list_tags + +Inserts a list of all tags. + +```js +<%- list_tags([options]) %> +``` + +| Option | Description | Default | +| ------------ | ----------------------------------------------------------------------------------------------------------------------- | ------- | +| `orderby` | Order of tags | name | +| `order` | Sort of order. `1`, `asc` for ascending; `-1`, `desc` for descending | 1 | +| `show_count` | Display the number of posts for each tag | true | +| `style` | Style to display the tag list. `list` displays tags in an unordered list. Use `false` or any other value to disable it. | list | +| `separator` | Separator between categories. (Only works if `style` is not `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` | The number of tags to display (0 = unlimited) | 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) | +| `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) | + +Examples: + +```ejs +<%- list_tags(site.tags, {class: 'classtest', style: false, separator: ' | '}) %> +<%- list_tags(site.tags, {class: 'classtest', style: 'list'}) %> +<%- list_tags(site.tags, {class: {ul: 'ululul', li: 'lilili', a: 'aaa', count: 'ccc'}, style: false, separator: ' | '}) %> +<%- list_tags(site.tags, {class: {ul: 'ululul', li: 'lilili', a: 'aaa', count: 'ccc'}, style: 'list'}) %> +``` + +### list_archives + +Inserts a list of archives. + +```js +<%- list_archives([options]) %> +``` + +| Option | Description | Default | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | --------- | +| `type` | Type. This value can be `yearly` or `monthly`. | monthly | +| `order` | Sort of order. `1`, `asc` for ascending; `-1`, `desc` for descending | 1 | +| `show_count` | Display the number of posts for each archive | true | +| `format` | Date format | MMMM YYYY | +| `style` | Style to display the archive list. `list` displays archives in an unordered list. Use `false` or any other value to disable it. | list | +| `separator` | Separator between archives. (Only works if `style` is not `list`) | , | +| `class` | Class name of archive list. | archive | +| `transform` | The function that changes the display of archive name. See examples in [list_categories](#list-categories). | | + +### list_posts + +Inserts a list of posts. + +```js +<%- list_posts([options]) %> +``` + +| Option | Description | Default | +| ----------- | ------------------------------------------------------------------------------------------------------------------------- | ------- | +| `orderby` | Order of posts | date | +| `order` | Sort of order. `1`, `asc` for ascending; `-1`, `desc` for descending | 1 | +| `style` | Style to display the post list. `list` displays posts in an unordered list. Use `false` or any other value to disable it. | list | +| `separator` | Separator between posts. (Only works if `style` is not `list`) | , | +| `class` | Class name of post list. | post | +| `amount` | The number of posts to display (0 = unlimited) | 6 | +| `transform` | The function that changes the display of post name. See examples in [list_categories](#list-categories). | | + +### tagcloud + +Inserts a tag cloud. + +```js +<%- tagcloud([tags], [options]) %> +``` + +| Option | Description | Default | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| `min_font` | Minimum font size | 10 | +| `max_font` | Maximum font size | 20 | +| `unit` | Unit of font size | px | +| `amount` | Total amount of tags | unlimited | +| `orderby` | Order of tags | name | +| `order` | Sort order. `1`, `asc` as ascending; `-1`, `desc` as descending | 1 | +| `color` | Colorizes the tag cloud | false | +| `start_color` | Start color. You can use hex (`#b700ff`), rgba (`rgba(183, 0, 255, 1)`), hsla (`hsla(283, 100%, 50%, 1)`) or [color keywords][]. This option only works when `color` is true. | | +| `end_color` | End color. You can use hex (`#b700ff`), rgba (`rgba(183, 0, 255, 1)`), hsla (`hsla(283, 100%, 50%, 1)`) or [color keywords][]. This option only works when `color` is true. | | +| `class` | Class name prefix of tags | | +| `level` | The number of different class names. This option only works when `class` is set. | 10 | +| `show_count` (+6.3.0) | Display the number of posts for each tag | false | +| `count_class` (+6.3.0) | Class name of tag count | count | + +**Examples:** + +```js +// Default options +<%- tagcloud() %> + +// Limit number of tags to 30 +<%- tagcloud({amount: 30}) %> +``` + +## Miscellaneous + +### paginator + +Inserts a paginator. + +```js +<%- paginator(options) %> +``` + +| Option | Description | Default | +| -------------------------- | ---------------------------------------------------------------------------------- | ------------- | +| `base` | Base URL | / | +| `format` | URL format | page/%d/ | +| `total` | The number of pages | 1 | +| `current` | Current page number | 0 | +| `prev_text` | The link text of previous page. Works only if `prev_next` is set to true. | Prev | +| `next_text` | The link text of next page. Works only if `prev_next` is set to true. | Next | +| `space` | The space text | &hellp; | +| `prev_next` | Display previous and next links | 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` | Display all pages. If this is set to true, `end_size` and `mid_size` will not work | false | +| `escape` | Escape HTML tags | true | +| `page_class` (+6.3.0) | Page class name | `page-number` | +| `current_class` (+6.3.0) | Current page class name | `current` | +| `space_class` (+6.3.0) | Space class name | `space` | +| `prev_class` (+6.3.0) | Previous page class name | `extend prev` | +| `next_class` (+6.3.0) | Next page class name | `extend next` | +| `force_prev_next` (+6.3.0) | Force display previous and next links | false | + +**Examples:** + +```js +<%- paginator({ + prev_text: '<', + next_text: '>' +}) %> +``` + +```html +<!-- Rendered as --> +<a href="/1/"><</a> +<a href="/1/">1</a> +2 +<a href="/3/">3</a> +<a href="/3/">></a> +``` + +```js +<%- paginator({ + prev_text: '<i class="fa fa-angle-left"></i>', + next_text: '<i class="fa fa-angle-right"></i>', + escape: false +}) %> +``` + +```html +<!-- Rendered as --> +<a href="/1/"><i class="fa fa-angle-left"></i></a> +<a href="/1/">1</a> +2 +<a href="/3/">3</a> +<a href="/3/"><i class="fa fa-angle-right"></i></a> +``` + +### search_form + +Inserts a Google search form. + +```js +<%- search_form(options) %> +``` + +| Option | Description | Default | +| -------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `class` | The class name of form | search-form | +| `text` | Search hint word | Search | +| `button` | Display 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 + +Formats a number. + +```js +<%- number_format(number, [options]) %> +``` + +| Option | Description | Default | +| ----------- | --------------------------------------------------------------------------- | ------- | +| `precision` | The precision of number. The value can be `false` or a nonnegative integer. | false | +| `delimiter` | The thousands delimiter | , | +| `separator` | The separator between the fractional and integer digits. | . | + +**Examples:** + +```js +<%- number_format(12345.67, {precision: 1}) %> +// 12,345.68 + +<%- number_format(12345.67, {precision: 4}) %> +// 12,345.6700 + +<%- number_format(12345.67, {precision: 0}) %> +// 12,345 + +<%- number_format(12345.67, {delimiter: ''}) %> +// 12345.67 + +<%- number_format(12345.67, {separator: '/'}) %> +// 12,345/67 +``` + +### meta_generator + +Inserts [generator tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta). + +```js +<%- meta_generator() %> +``` + +**Examples:** + +```js +<%- meta_generator() %> +// <meta name="generator" content="Hexo 4.0.0"> +``` + +### open_graph + +Inserts [Open Graph][] data. + +```js +<%- open_graph([options]) %> +``` + +| Option | Description | Default | +| --------------- | ---------------------------------------------------- | ------------------------------------------------------- | +| `title` | Page title (`og:title`) | `page.title` | +| `type` | Page type (`og:type`) | article(post page)<br>website(non-post page) | +| `url` | Page URL (`og:url`) | `url` | +| `image` | Page images (`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` | Site name (`og:site_name`) | `config.title` | +| `description` | Page description (`og:description`) | Page excerpt or first 200 characters of the content | +| `twitter_card` | Twitter card type (`twitter:card`) | summary | +| `twitter_id` | Twitter ID (`twitter:creator`) | | +| `twitter_site` | Twitter Site (`twitter:site`) | | +| `twitter_image` | Twitter Image (`twitter:image`) | | +| `google_plus` | Google+ profile link | | +| `fb_admins` | Facebook admin ID | | +| `fb_app_id` | Facebook App ID | | + +### toc + +Parses all heading tags (h1~h6) in the content and inserts a table of contents. + +```js +<%- toc(str, [options]) %> +``` + +| Option | Description | Default | +| ----------------------- | ---------------------------------------- | ----------------- | +| `class` | Class name | `toc` | +| `class_item` (+6.3.0) | Class name of item | `${class}-item` | +| `class_link` (+6.3.0) | Class name of link | `${class}-link` | +| `class_text` (+6.3.0) | Class name of text | `${class}-text` | +| `class_child` (+6.3.0) | Class name of child | `${class}-child` | +| `class_number` (+6.3.0) | Class name of number | `${class}-number` | +| `class_level` (+6.3.0) | Class name prefix of level | `${class}-level` | +| `list_number` | Displays list number | true | +| `max_depth` | Maximum heading depth of generated toc | 6 | +| `min_depth` | Minimum heading depth of generated toc | 1 | +| `max_items` (+7.3.0) | Maximum number of items in generated toc | `Infinity` | + +**Examples:** + +```js +<%- toc(page.content) %> +``` + +#### data-toc-unnumbered (+6.1.0) + +Headings with attribute `data-toc-unnumbered="true"` will be marked as unnumbered (list number will not be displayed). + +{% note warn "Warning!" %} +For using `data-toc-unnumbered="true"`, the renderer must have the option to add CSS classes. + +Please see the below PRs. + +- https://github.com/hexojs/hexo/pull/4871 +- https://github.com/hexojs/hexo-util/pull/269 +- https://github.com/hexojs/hexo-renderer-markdown-it/pull/174 + {% endnote %} + +[color keywords]: http://www.w3.org/TR/css3-color/#svg-color +[Moment.js]: http://momentjs.com/ +[Open Graph]: http://ogp.me/ diff --git a/source/fa/docs/index.md b/source/fa/docs/index.md new file mode 100644 index 0000000000..7c46e30c63 --- /dev/null +++ b/source/fa/docs/index.md @@ -0,0 +1,111 @@ +--- +title: Documentation +--- + +Welcome to the Hexo documentation. If you encounter any problems when using Hexo, have a look at the [troubleshooting guide](troubleshooting.html), raise an issue on [GitHub](https://github.com/hexojs/hexo/issues) or start a topic on the [Google Group](https://groups.google.com/group/hexo). + +## What is Hexo? + +Hexo is a fast, simple and powerful blog framework. You write posts in [Markdown](http://daringfireball.net/projects/markdown/) (or other markup languages) and Hexo generates static files with a beautiful theme in seconds. + +## Installation + +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 ARted4RniaU %} + +### Requirements + +Installing Hexo is quite easy and only requires the following beforehand: + +- [Node.js](http://nodejs.org/) (See [Required Node.js version](#Required-Node-js-version)) +- [Git](http://git-scm.com/) + +If your computer already has these, congratulations! You can skip to the [Hexo installation](#Install-Hexo) step. + +If not, please follow the following instructions to install all the requirements. + +### Install Git + +- Windows: Download & install [git](https://git-scm.com/download/win). +- Mac: Install it with [Homebrew](https://brew.sh/), [MacPorts](http://www.macports.org/) or [installer](http://sourceforge.net/projects/git-osx-installer/). +- Linux (Ubuntu, Debian): `sudo apt-get install git-core` +- Linux (Fedora, Red Hat, CentOS): `sudo yum install git-core` + +{% note warn For Mac users %} +You may encounter some problems when compiling. Please install Xcode from App Store first. After Xcode is installed, open Xcode and go to **Preferences -> Download -> Command Line Tools -> Install** to install command line tools. +{% endnote %} + +### Install Node.js + +Node.js provides [official installer](https://nodejs.org/en/download/) for most platforms. + +Alternative installation methods: + +- Windows: Install it with [nvs](https://github.com/jasongin/nvs/) (recommended) or [nvm](https://github.com/nvm-sh/nvm). +- Mac: Install it with [Homebrew](https://brew.sh/) or [MacPorts](http://www.macports.org/). +- Linux (DEB/RPM-based): Install it with [NodeSource](https://github.com/nodesource/distributions). +- Others: Install it through respective package manager. Refer to [the guide](https://nodejs.org/en/download/package-manager/) provided by Node.js. + +nvs is also recommended for Mac and Linux to avoid possible permission issue. + +{% note info Windows %} +If you use the official installer, make sure **Add to PATH** is checked (it's checked by default). +{% endnote %} + +{% note warn Mac / Linux %} +If you encounter `EACCES` permission error when trying to install Hexo, please follow [the workaround](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) provided by npmjs; overriding with root/sudo is highly discouraged. +{% endnote %} + +{% note info Linux %} +If you installed Node.js using Snap, you may need to manually run `npm install` in the target folder when [initializing](/docs/commands#init) a blog. +{% endnote %} + +### Install Hexo + +Once all the requirements are installed, you can install Hexo with npm: + +```bash +$ npm install -g hexo-cli +``` + +### Advanced installation and usage + +Advanced users may prefer to install and use `hexo` package instead. + +```bash +$ npm install hexo +``` + +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>` + +### Required Node.js version + +If you are stuck with older Node.js, you can consider installing a past version of Hexo. + +Please note we do not provide bugfixes to past versions of Hexo. + +We highly recommend to always install the [latest version](https://www.npmjs.com/package/hexo?activeTab=versions) of Hexo and the [recommended version](#Requirements) of Node.js, whenever possible. + +| Hexo version | Minimum (Node.js version) | Less than (Node.js version) | +| ------------ | ------------------------- | --------------------------- | +| 8.0+ | 20.19.0 | latest | +| 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/fa/docs/internationalization.md b/source/fa/docs/internationalization.md new file mode 100644 index 0000000000..21df389627 --- /dev/null +++ b/source/fa/docs/internationalization.md @@ -0,0 +1,57 @@ +--- +title: Internationalization (i18n) +--- + +You can use internationalization to present your site in different languages. The default language is set by modifying the `language` setting in `_config.yml`. You can also set multiple languages and modify the order of default languages. + +```yaml +language: zh-tw + +language: +- zh-tw +- en +``` + +### Language Files + +Language files can be YAML or JSON files. You should put them into the `languages` folder in the theme. There is support for the [printf format](https://github.com/alexei/sprintf.js) in language files. + +### Templates + +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: + title: Home + add: Add + video: + zero: No videos + one: One video + other: %d videos +``` + +```js +<%= __('index.title') %> +// Home + +<%= _p('index.video', 3) %> +// 3 videos +``` + +### Path + +You can set the language of pages in front-matter, or modify the `i18n_dir` setting in `_config.yml` to enable automatic detection by Hexo. + +```yaml +i18n_dir: :lang +``` + +The default value of `i18n_dir` setting is `:lang`, which means that Hexo will detect the language within the first segment of URL. For example: + +```plain +/index.html => en +/archives/index.html => en +/zh-tw/index.html => zh-tw +``` + +The string will only be served as a language when the language file exists. So `archives` in `/archives/index.html` (example 2) will not get served as a language. diff --git a/source/fa/docs/migration.md b/source/fa/docs/migration.md new file mode 100644 index 0000000000..a240934dc1 --- /dev/null +++ b/source/fa/docs/migration.md @@ -0,0 +1,73 @@ +--- +title: Migration +--- + +## RSS + +First, install the `hexo-migrator-rss` plugin. + +```bash +$ npm install hexo-migrator-rss --save +``` + +Once the plugin is installed, run the following command to migrate all posts from RSS. `source` can be a file path or URL. + +```bash +$ hexo migrate rss <source> +``` + +## Jekyll + +Move all files in the Jekyll `_posts` folder to the `source/_posts` folder. + +Modify the `new_post_name` setting in `_config.yml`: + +```yaml +new_post_name: :year-:month-:day-:title.md +``` + +## Octopress + +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 +``` + +## WordPress + +First, install the `hexo-migrator-wordpress` plugin. + +```bash +$ npm install hexo-migrator-wordpress --save +``` + +Export your WordPress site by going to "Tools" → "Export" → "WordPress" in the WordPress dashboard (see the [WordPress support page](http://en.support.wordpress.com/export/) for more details). + +Now run: + +```bash +$ hexo migrate wordpress <source> +``` + +Where `source` is the file path or URL to the WordPress export file. + +## Joomla + +First, install the `hexo-migrator-joomla` plugin. + +```bash +$ npm install hexo-migrator-joomla --save +``` + +Export your Joomla articles using the [J2XML](http://extensions.joomla.org/extensions/migration-a-conversion/data-import-a-export/12816?qh=YToxOntpOjA7czo1OiJqMnhtbCI7fQ%3D%3D) component. + +Now run: + +```bash +$ hexo migrate joomla <source> +``` + +Where `source` is the file path or URL to the Joomla export file. diff --git a/source/fa/docs/one-command-deployment.md b/source/fa/docs/one-command-deployment.md new file mode 100644 index 0000000000..4c65599d34 --- /dev/null +++ b/source/fa/docs/one-command-deployment.md @@ -0,0 +1,252 @@ +--- +title: One-Command Deployment +--- + +Hexo provides a fast and easy deployment strategy. You only need one single command to deploy your site to your server. + +```bash +$ hexo deploy +``` + +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 +``` + +You can use multiple deployers. Hexo will execute each deployer in order. + +```yaml +deploy: + - type: git + repo: + - type: heroku + repo: +``` + +Refer to the [Plugins](https://hexo.io/plugins/) list for more deployment plugins. + +## Git + +1. Install [hexo-deployer-git][]. + +```bash +$ npm install hexo-deployer-git --save +``` + +2. Edit **\_config.yml** (with example values shown below as comments): + +```yaml +deploy: + type: git + repo: <repository url> # https://bitbucket.org/JohnSmith/johnsmith.bitbucket.io + branch: [branch] + message: [message] +``` + +| Option | Description | Default | +| --------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `repo` | URL of the target repository | | +| `branch` | Branch name. | `gh-pages` (GitHub)<br>`coding-pages` (Coding.net)<br>`master` (others) | +| `message` | Customize commit message. | `Site updated: {% raw %}{{ now('YYYY-MM-DD HH:mm:ss') }}{% endraw %}` | +| `token` | Optional token value to authenticate with the repo. Prefix with `$` to read token from environment variable | | + +3. Deploy your site `hexo clean && hexo deploy`. + +- You will be prompted with username and password of the target repository, unless you authenticate with a token or ssh key. +- hexo-deployer-git does not store your username and password. Use [git-credential-cache](https://git-scm.com/docs/git-credential-cache) to store them temporarily. + +4. Navigate to your repository settings and change the "Pages" branch to `gh-pages` (or the branch specified in your config). The deployed site should be live on the link shown on the "Pages" setting. + +## Heroku + +Install [hexo-deployer-heroku][]. + +```bash +$ npm install hexo-deployer-heroku --save +``` + +Edit settings. + +```yaml +deploy: + type: heroku + repo: <repository url> + message: [message] +``` + +| Option | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------- | +| `repo`, `repository` | Heroku repository URL | +| `message` | Customize commit message (Default to `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 + +Install [hexo-deployer-rsync][]. + +```bash +$ npm install hexo-deployer-rsync --save +``` + +Edit settings. + +```yaml +deploy: + type: rsync + host: <host> + user: <user> + root: <root> + port: [port] + delete: [true|false] + verbose: [true|false] + ignore_errors: [true|false] +``` + +| Option | Description | Default | +| --------------- | ------------------------------- | ------- | +| `host` | Address of remote host | | +| `user` | Username | | +| `root` | Root directory of remote host | | +| `port` | Port | 22 | +| `delete` | Delete old files on remote host | true | +| `verbose` | Display verbose messages | true | +| `ignore_errors` | Ignore errors | false | + +## FTPSync + +Install [hexo-deployer-ftpsync][]. + +```bash +$ npm install hexo-deployer-ftpsync --save +``` + +Edit settings. + +```yaml +deploy: + type: ftpsync + host: <host> + user: <user> + pass: <password> + remote: [remote] + port: [port] + clear: [true|false] + verbose: [true|false] +``` + +| Option | Description | Default | +| --------- | ------------------------------------------------------------------------ | ------- | +| `host` | Address of remote host | | +| `user` | Username | | +| `pass` | Password | | +| `remote` | Root directory of remote host | `/` | +| `port` | Port | 21 | +| `clear` | Remove all files and directories from the remote directory before upload | 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 +``` + +Edit settings. + +```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 | Description | 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) is a cloud platform that enables developers to host Jamstack websites and web services that deploy instantly, scale automatically, and require no supervision, all with zero configuration. They provide a global edge network, SSL encryption, asset compression, cache invalidation, and more. + +Step 1: Add a build script to your `package.json` file: + +```json +{ + "scripts": { + "build": "hexo generate" + } +} +``` + +Step 2: Deploy your Hexo Website to Vercel + +To deploy your Hexo app with a [Vercel for Git Integration](https://vercel.com/docs/git-integrations), make sure it has been pushed to a Git repository. + +Import the project into Vercel using the [Import Flow](https://vercel.com/import/git). During the import, you will find all relevant options preconfigured for you; however, you can choose to change any of these options, a list of which can be found [here](https://vercel.com/docs/build-step#build-&-development-settings). + +After your project has been imported, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/platform/deployments#preview), and all changes made to the [Production Branch](https://vercel.com/docs/git-integrations#production-branch) (commonly "main") will result in a [Production Deployment](https://vercel.com/docs/platform/deployments#production). + +Alternatively, you can click the deploy button below to create a new project: + +[![Deploy Vercel](https://vercel.com/button)](https://vercel.com/new/hexo) + +## Bip + +[Bip](https://bip.sh) is a commercial hosting service that provides zero downtime deployment, a global CDN, SSL, unlimited bandwidth and more for static websites. Plans are available on a pay as you go, per domain basis. + +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). + +1: Initialise your project directory + +```bash +$ bip init +``` + +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. + +2: Deploy your website + +```bash +$ hexo generate —deploy && bip deploy +``` + +After a few moments, your website will be deployed. + +## Other Methods + +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-ftpsync]: https://github.com/hexojs/hexo-deployer-ftpsync +[hexo-deployer-sftp]: https://github.com/lucascaro/hexo-deployer-sftp diff --git a/source/fa/docs/permalinks.md b/source/fa/docs/permalinks.md new file mode 100644 index 0000000000..eb0074ab7a --- /dev/null +++ b/source/fa/docs/permalinks.md @@ -0,0 +1,86 @@ +--- +title: Permalinks +--- + +You can specify the permalinks for your site in `_config.yml` or in the front-matter for each post. + +### Variables + +Besides the following variables, you can use any attributes in the permalink except `:path` and `:permalink`. + +| Variable | Description | +| ------------- | ----------------------------------------------------------------------------------- | +| `:year` | Published year of posts (4-digit) | +| `:month` | Published month of posts (2-digit) | +| `:i_month` | Published month of posts (Without leading zeros) | +| `: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) | +| `:timestamp` | Timestamp of post's published [date](./front-matter#Settings-Their-Default-Values) | +| `:title` | Filename (relative to "source/\_posts/" folder) | +| `:name` | Filename | +| `:post_title` | Post title | +| `:id` | Post ID (_not persistent across [cache reset](/docs/commands#clean)_) | +| `:category` | Categories. If the post is uncategorized, it will use the `default_category` value. | +| `:hash` | SHA1 hash of filename (same as `:title`) and date (12-hexadecimal) | + +You can define the default value of each variable in the permalink through the `permalink_defaults` setting: + +```yaml +permalink_defaults: + lang: en +``` + +### Examples + +```yaml source/_posts/hello-world.md +title: Hello World +date: 2013-07-14 17:01:34 +categories: + - foo + - bar +``` + +| Setting | Result | +| ------------------------------- | --------------------------- | +| `:year/:month/:day/:title/` | 2013/07/14/hello-world/ | +| `:year-:month-:day-:title.html` | 2013-07-14-hello-world.html | +| `:category/:title/` | foo/bar/hello-world/ | +| `:title-:hash/` | hello-world-a2c8ac003b43/ | + +```yaml source/_posts/lorem/hello-world.md +title: Hello World +date: 2013-07-14 17:01:34 +categories: + - foo + - bar +``` + +| Setting | Result | +| --------------------------- | ----------------------------- | +| `:year/:month/:day/:title/` | 2013/07/14/lorem/hello-world/ | +| `:year/:month/:day/:name/` | 2013/07/14/hello-world/ | + +### Multi-language Support + +To create a multi-language site, you can modify the `new_post_name` and `permalink` settings like this: + +```yaml +new_post_name: :lang/:title.md +permalink: :lang/:title/ +``` + +When you create a new post, the post will be saved to: + +```bash +$ hexo new "Hello World" --lang tw +# => source/_posts/tw/Hello-World.md +``` + +and the URL will be: + +```plain +http://localhost:4000/tw/hello-world/ +``` diff --git a/source/fa/docs/plugins.md b/source/fa/docs/plugins.md new file mode 100644 index 0000000000..f09842b3c1 --- /dev/null +++ b/source/fa/docs/plugins.md @@ -0,0 +1,77 @@ +--- +title: Plugins +--- + +Hexo has a powerful plugin system, which makes it easy to extend functions without modifying the source code of the core module. There are two kinds of plugins in Hexo: + +### Script + +If your plugin is relatively simple, it's recommended to use a script. All you need to do is put your JavaScript files in the `scripts` folder and Hexo will load them during initialization. + +### Plugin + +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. + +Your new folder must contain at least two files: one containing the actual JavaScript code and one `package.json` file that describes the purpose of the plugin and sets its dependencies. + +```plain +. +├── index.js +└── package.json +``` + +At the very least, you should set the `name`, `version` and `main` entries in `package.json`. For example: + +```json package.json +{ + "name": "hexo-my-plugin", + "version": "0.0.1", + "main": "index" +} +``` + +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. + +### Tools + +You can make use of the official tools provided by Hexo to accelerate development: + +- [hexo-fs][]：File IO +- [hexo-util][]：Utilities +- [hexo-i18n][]：Localization (i18n) +- [hexo-pagination][]：Generate pagination data + +### Publishing + +When your plugin is ready, you may consider publishing it to the [plugin list](/plugins) to invite other people to start using it. Publishing your own plugins is very similar to [updating documentation](contributing.html#Updating_Documentation). + +1. Fork [hexojs/site][] +2. Clone the repository to your computer and install dependencies. + + ```shell + $ git clone https://github.com/<username>/site.git + $ cd site + $ npm install + ``` + +3. Create a new yaml file in `source/_data/plugins/`, use your plugin name as the file name + +4. Edit `source/_data/plugins/<your-plugin-name>.yml` and add your plugin. For example: + + ```yaml + description: Server module for Hexo. + link: https://github.com/hexojs/hexo-server + tags: + - official + - server + - console + ``` + +5. Push the branch. +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 +[hexo-i18n]: https://github.com/hexojs/hexo-i18n +[hexo-pagination]: https://github.com/hexojs/hexo-pagination +[hexojs/site]: https://github.com/hexojs/site diff --git a/source/fa/docs/server.md b/source/fa/docs/server.md new file mode 100644 index 0000000000..dead13d061 --- /dev/null +++ b/source/fa/docs/server.md @@ -0,0 +1,41 @@ +--- +title: Server +--- + +## [hexo-server][] + +With the release of Hexo 3, the server has been separated from the main module. To start using the server, you will first have to install [hexo-server][]. + +```bash +$ npm install hexo-server --save +``` + +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 +``` + +If you want to change the port or if you're encountering `EADDRINUSE` errors, use the `-p` option to set a different port. + +```bash +$ hexo server -p 5000 +``` + +### Static Mode + +In static mode, only files in the `public` folder will be served and file watching is disabled. You have to run `hexo generate` before starting the server. Usually used in production. + +```bash +$ hexo server -s +``` + +### Custom 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 +``` + +[hexo-server]: https://github.com/hexojs/hexo-server diff --git a/source/fa/docs/setup.md b/source/fa/docs/setup.md new file mode 100644 index 0000000000..6a04acd7d7 --- /dev/null +++ b/source/fa/docs/setup.md @@ -0,0 +1,69 @@ +--- +title: Setup +--- + +{% youtube 0m2HnATkHOk %} + +Once Hexo is installed, run the following commands to initialize Hexo in the target `<folder>`. + +```bash +$ hexo init <folder> +$ cd <folder> +$ npm install +``` + +Once initialized, here's what your project folder will look like: + +```plain +. +├── _config.yml +├── package.json +├── scaffolds +├── source +| ├── _drafts +| └── _posts +└── themes +``` + +### \_config.yml + +Site [configuration](configuration.html) file. You can configure most settings here. + +### package.json + +Application data. The [EJS](https://ejs.co/), [Stylus](http://learnboost.github.io/stylus/) and [Markdown](http://daringfireball.net/projects/markdown/) renderers are installed by default. If you want, you can uninstall them later. + +```json package.json +{ + "name": "hexo-site", + "version": "0.0.0", + "private": true, + "hexo": { + "version": "" + }, + "dependencies": { + "hexo": "^7.0.0", + "hexo-generator-archive": "^2.0.0", + "hexo-generator-category": "^2.0.0", + "hexo-generator-index": "^3.0.0", + "hexo-generator-tag": "^2.0.0", + "hexo-renderer-ejs": "^2.0.0", + "hexo-renderer-stylus": "^3.0.0", + "hexo-renderer-marked": "^6.0.0", + "hexo-server": "^3.0.0", + "hexo-theme-landscape": "^1.0.0" + } +} +``` + +### scaffolds + +[Scaffold](writing.html#Scaffolds) folder. When you create a new post, Hexo bases the new file on the scaffold. + +### source + +Source folder. This is where you put your site's content. Hexo ignores hidden files and files or folders whose names are prefixed with `_` (underscore) - except the `_posts` folder. Renderable files (e.g. Markdown, HTML) will be processed and put into the `public` folder, while other files will simply be copied. + +### themes + +[Theme](themes.html) folder. Hexo generates a static website by combining the site contents with the theme. diff --git a/source/fa/docs/syntax-highlight.md b/source/fa/docs/syntax-highlight.md new file mode 100644 index 0000000000..c148666117 --- /dev/null +++ b/source/fa/docs/syntax-highlight.md @@ -0,0 +1,294 @@ +--- +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. + +## How to use code block in posts + +Hexo supports two ways to write code block: [Tag Plugin - Code Block](tag-plugins#Code-Block) and [Tag Plugin - Backtick Code Block](https://hexo.io/docs/tag-plugins#Backtick-Code-Block): + +````markdown +{% codeblock [title] [lang:language] [url] [link text] [additional options] %} +code snippet +{% endcodeblock %} + +{% code [title] [lang:language] [url] [link text] [additional options] %} +code snippet +{% endcode %} + +```[language] [title] [url] [link text] [additional options] +code snippet +``` +```` +The third syntax is 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 the 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. +## Configuration +below v7.0.0: + +```yaml +# _config.yml +highlight: + enable: true + auto_detect: false + line_number: true + line_threshold: 0 + tab_replace: "" + exclude_languages: + - example + wrap: true + hljs: false +prismjs: + enable: false + preprocess: true + line_number: true + line_threshold: 0 + 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: + enable: false +prismjs: + enable: false +``` + +v7.0.0+: + +```yaml +# _config.yml +syntax_highlighter: # empty +``` + +When both `highlight.enable` and `prismjs.enable` are `false` (below v7.0.0) or `syntax_highlighter` is empty (v7.0.0+), 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>`: + +````markdown +```yaml +hello: hexo +``` +```` + +```html +<pre> + <code class="yaml">hello: hexo</code> +</pre> +``` + +When no built-in syntax highlight is enabled, you can either install third-party syntax-highlight plugin, or use a browser-side syntax highlighter (e.g. `highlight.js` and `prism.js` both support running in browser). + +## Highlight.js + +below v7.0.0: + +```yaml +# _config.yml +highlight: + enable: true + auto_detect: false + line_number: true + line_threshold: 0 + tab_replace: " " + exclude_languages: + - example + wrap: true + hljs: false +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`. + +### auto_detect + +`auto_detect` is a `highlight.js` feature that detects language of the code block automatically. + +> 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. +{% endnote %} + +### line_number + +`highlight.js` [does not](https://highlightjs.readthedocs.io/en/latest/line-numbers.html) support line number. + +Hexo adds line number by wrapping output inside `<figure>` and `<table>`: + +```html +<figure class="highlight yaml"> + <table> + <tbody> + <tr> + <td class="gutter"> + <pre><span class="line">1</span><br></pre> + </td> + <td class="code"> + <pre><span class="line"><span class="attr">hello:</span><span class="string">hexo</span></span><br></pre> + </td> + </tr> + </tbody> + </table> +</figure> +``` + +It is not the behavior of `highlight.js` and requires custom CSS for `<figure>` and `<table>` elements; some themes have built-in support. + +You might also notice that all `class` has no `hljs-` prefixed, we will revisit it [later part](#hljs). + +### 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`. + +### tab_replace + +Replace tabs inside code block with given string. By default it is 2 spaces. + +### exclude_languages (+6.1.0) + +Only wrap with `<pre><code class="lang"></code></pre>` and will not render all tags(`span`, and `br`) in content if are languages match this option. + +### 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: + +```html +<pre><code class="yaml"> +<span class="comment"># _config.yml</span> +<span class="attr">hexo:</span> <span class="string">hexo</span> +</code></pre> +``` + +{% 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 %} + +### hljs + +When `hljs` is set to `true`, all the HTML output will have `class` prefixed with `hljs-` (regardless `wrap` is enabled or not): + +```html +<pre><code class="yaml hljs"> +<span class="hljs-comment"># _config.yml</span> +<span class="hljs-attr">hexo:</span> <span class="hljs-string">hexo</span> +</code></pre> +``` + +> Tip: When `line_number` is set to `false`, `wrap` is set to false and `hljs` is set to `true`, you can then use `highlight.js` [theme](https://github.com/highlightjs/highlight.js/tree/master/src/styles) directly in your site. + +## PrismJS + +below v7.0.0: + +```yaml +# _config.yml +highlight: + enable: false +prismjs: + enable: true + preprocess: true + line_number: true + line_threshold: 0 + tab_replace: "" +``` + +v7.0.0+: + +```yaml +# _config.yml +syntax_highlighter: prismjs +prismjs: + preprocess: true + line_number: true + line_threshold: 0 + tab_replace: "" +``` + +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. + +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. +- [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: + +- [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`. +- [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_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`. + +### 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`. + +### tab_replace + +Replace `\t` inside code block with given string. By default it is 2 spaces. + +## Other useful information + +- [Highlight.js](https://highlightjs.readthedocs.io/en/latest/) +- [PrismJS](https://prismjs.com/) + +The source codes behind Hexo's syntax highlighting are available in: + +- [Highlight.js Utility Functions](https://github.com/hexojs/hexo-util/blob/master/lib/highlight.ts) +- [PrismJS Utility Functions](https://github.com/hexojs/hexo-util/blob/master/lib/prism.ts) +- [Tag Plugin - Code Block](https://github.com/hexojs/hexo/blob/master/lib/plugins/tag/code.ts) +- [Tag Plugin - Backtick Code Block](https://github.com/hexojs/hexo/blob/master/lib/plugins/filter/before_post_render/backtick_code_block.ts) diff --git a/source/fa/docs/tag-plugins.md b/source/fa/docs/tag-plugins.md new file mode 100644 index 0000000000..098e13cb20 --- /dev/null +++ b/source/fa/docs/tag-plugins.md @@ -0,0 +1,493 @@ +--- +title: Tag Plugins +--- + +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 I07XMi7MHd4 %} + +_Tag plugins should not be wrapped inside Markdown syntax, e.g. `[]({% post_path lorem-ipsum %})` is not supported._ + +## Block Quote + +Perfect for adding quotes to your post, with optional author, source and title information. + +**Alias:** quote + +``` +{% blockquote [author[, source]] [link] [source_link_title] %} +content +{% endblockquote %} +``` + +### Examples + +**No arguments. Plain blockquote.** + +``` +{% blockquote %} +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque hendrerit lacus ut purus iaculis feugiat. Sed nec tempor elit, quis aliquam neque. Curabitur sed diam eget dolor fermentum semper at eu lorem. +{% endblockquote %} +``` + +{% blockquote %} +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque hendrerit lacus ut purus iaculis feugiat. Sed nec tempor elit, quis aliquam neque. Curabitur sed diam eget dolor fermentum semper at eu lorem. +{% endblockquote %} + +**Quote from a book** + +``` +{% blockquote David Levithan, Wide Awake %} +Do not just seek happiness for yourself. 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. +{% endblockquote %} + +**Quote from Twitter** + +``` +{% blockquote @DevDocs https://twitter.com/devdocs/status/356095192085962752 %} +NEW: DevDocs now comes with syntax highlighting. http://devdocs.io +{% endblockquote %} +``` + +{% blockquote @DevDocs https://twitter.com/devdocs/status/356095192085962752 %} +NEW: DevDocs now comes with syntax highlighting. http://devdocs.io +{% endblockquote %} + +**Quote from an article on the web** + +``` +{% 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 %} +``` + +{% 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 %} + +## Code Block + +A useful feature for adding code snippets to your post. + +**Alias:** code + +``` +{% codeblock [title] [lang:language] [url] [link text] [additional options] %} +code snippet +{% endcodeblock %} +``` + +Specify additional options in `option:value` format, e.g. `line_number:false first_line:5`. + +| Extra Options | Description | Default | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `line_number` | Show 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` | Enable code highlighting | `true` | +| `first_line` | Specify the first line number | `1` | +| `mark` | Line highlight specific line(s), each value separated by a comma. Specify the number range using a dash<br>Example: `mark:1,4-7,10` will mark lines 1, 4 to 7 and 10. | | +| `wrap` | Wrap the code block in [`<table>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table) | `true` | + +### Examples + +**A plain code block** + +``` +{% codeblock %} +alert('Hello World!'); +{% endcodeblock %} +``` + +{% codeblock %} +alert('Hello World!'); +{% endcodeblock %} + +**Specifying the language** + +``` +{% codeblock lang:objc %} +[rectangle setX: 10 y: 10 width: 20 height: 20]; +{% endcodeblock %} +``` + +{% codeblock lang:objc %} +[rectangle setX: 10 y: 10 width: 20 height: 20]; +{% endcodeblock %} + +**Adding a caption to the code block** + +``` +{% codeblock Array.map %} +array.map(callback[, thisArg]) +{% endcodeblock %} +``` + +{% codeblock Array.map %} +array.map(callback[, thisArg]) +{% endcodeblock %} + +**Adding a caption and a URL** + +``` +{% codeblock _.compact http://underscorejs.org/#compact Underscore.js %} +_.compact([0, 1, false, 2, '', 3]); +=> [1, 2, 3] +{% endcodeblock %} +``` + +{% codeblock _.compact http://underscorejs.org/#compact Underscore.js %} +\_.compact([0, 1, false, 2, '', 3]); => [1, 2, 3] +{% endcodeblock %} + +## 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] +code snippet +`` +{% endraw %} + +## Pull Quote + +To add pull quotes to your posts: + +``` +{% pullquote [class] %} +content +{% endpullquote %} +``` + +## jsFiddle (deleted in `v7.0.0`) + +{% note warn %} +The tag was removed in Hexo 7.0.0. We have provided a plugin [hexo-tag-embed](https://github.com/hexojs/hexo-tag-embed) for backward compatibility with your existing posts. +{% endnote %} + +To embed a jsFiddle snippet: + +``` +{% jsfiddle shorttag [tabs] [skin] [width] [height] %} +``` + +## Gist (deleted in `v7.0.0`) + +{% note warn %} +Please use [hexo-tag-embed](https://github.com/hexojs/hexo-tag-embed) instead if you use `v7.0.0+`. +{% endnote %} + +To embed a Gist snippet: + +``` +{% gist gist_id [filename] %} +``` + +## iframe + +To embed an iframe: + +``` +{% iframe url [width] [height] %} +``` + +## Image + +Inserts an image with specified size. + +``` +{% img [class names] /path/to/image [width] [height] '"title text" "alt text"' %} +``` + +## Link + +Inserts a link with `target="_blank"` attribute. + +``` +{% link text url [external] [title] %} +``` + +## Include Code + +Inserts code snippets in `source/downloads/code` folder. The folder location can be specified through the `code_dir` option in the config. + +``` +{% include_code [title] [lang:language] [from:line] [to:line] path/to/file %} +``` + +### Examples + +**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 (deleted in `v7.0.0`) + +{% note warn %} +Please use [hexo-tag-embed](https://github.com/hexojs/hexo-tag-embed) instead if you use `v7.0.0+`. +{% endnote %} + +Inserts a YouTube video. + +``` +{% youtube video_id [type] [cookie] %} +``` + +### Examples + +**Embed a video** + +``` +{% youtube lJIrF4YjHfQ %} +``` + +**Embed a playlist** + +``` +{% youtube PL9hW1uS6HUfscJ9DHkOSoOX45MjXduUxo 'playlist' %} +``` + +**Enable privacy-enhanced mode** + +YouTube's cookie is not used in this mode. + +``` +{% youtube lJIrF4YjHfQ false %} +{% youtube PL9hW1uS6HUfscJ9DHkOSoOX45MjXduUxo 'playlist' false %} +``` + +## Vimeo (deleted in `v7.0.0`) + +{% note warn %} +Please use [hexo-tag-embed](https://github.com/hexojs/hexo-tag-embed) instead if you use `v7.0.0+`. +{% endnote %} + +Inserts a responsive or specified size Vimeo video. + +``` +{% vimeo video_id [width] [height] %} +``` + +## Include Posts + +Include links to other posts. + +``` +{% post_path filename %} +{% post_link filename [title] [escape] %} +``` + +You can ignore permalink and folder information, like languages and dates, when using this tag. + +For instance: `{% raw %}{% post_link how-to-bake-a-cake %}{% endraw %}`. + +This will work as long as the filename of the post is `how-to-bake-a-cake.md`, even if the post is located at `source/posts/2015-02-my-family-holiday` and has permalink `2018/en/how-to-bake-a-cake`. + +You can customize the text to display, instead of displaying the post's title. + +Post's title and custom text are escaped by default. You can use the `escape` option to disable escaping. + +For instance: + +**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' %} + +**Do not escape title.** + +``` +{% post_link hexo-4-released '<b>bold</b> custom title' false %} +``` + +{% 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 %} +{% asset_img [class names] slug [width] [height] [title text [alt text]] %} +{% asset_link filename [title] [escape] %} +``` + +### Embed image + +_hexo-renderer-marked 3.1.0+ can (optionally) resolves the post's path of an image automatically, refer to [this section](/docs/asset-folders#Embedding-an-image-using-markdown) on how to enable it._ + +"foo.jpg" is located at `http://example.com/2020/01/02/hello/foo.jpg`. + +**Default (no option)** + +`{% asset_img foo.jpg %}` + +```html +<img src="/2020/01/02/hello/foo.jpg" /> +``` + +**Custom class** + +`{% asset_img post-image foo.jpg %}` + +```html +<img src="/2020/01/02/hello/foo.jpg" class="post-image" /> +``` + +**Display size** + +`{% asset_img foo.jpg 500 400 %}` + +```html +<img src="/2020/01/02/hello/foo.jpg" width="500" height="400" /> +``` + +**Title & Alt** + +`{% asset_img foo.jpg "lorem ipsum'dolor'" %}` + +```html +<img src="/2020/01/02/hello/foo.jpg" title="lorem ipsum" alt="dolor" /> +``` + +## URL + +### url_for (7.0.0+) + +Returns a url with the root path prefixed. Output is encoded automatically. + +``` +{% url_for text path [relative] %} +``` + +**Examples:** + +```yml +_config.yml +root: /blog/ # example +``` + +``` +{% url_for blog index.html %} +``` + +```html +<a href="/blog/index.html">blog</a> +``` + +Relative link, follows `relative_link` option by default e.g. post/page path is '/foo/bar/index.html' + +```yml +_config.yml +relative_link: true +``` + +``` +{% url_for blog index.html %} +``` + +```html +<a href="../../index.html">blog</a> +``` + +You could also disable it to output a non-relative link, even when `relative_link` is enabled and vice versa. + +``` +{% url_for blog index.html false %} +``` + +```html +<a href="/index.html">blog</a> +``` + +### full_url_for (7.0.0+) + +Returns a url with the `config.url` prefixed. Output is encoded automatically. + +``` +{% full_url_for text path %} +``` + +**Examples:** + +```yml +_config.yml +url: https://example.com/blog # example +``` + +``` +{% full_url_for index /a/path %} +``` + +```html +<a href="https://example.com/blog/a/path">index</a> +``` + +## Raw + +If certain content is causing processing issues in your posts, wrap it with the `raw` tag to avoid rendering errors. + +``` +{% raw %} +content +{% endraw %} +``` + +## Post Excerpt + +Use text placed before the `<!-- more -->` tag as an excerpt for the post. `excerpt:` value in the [front-matter](/docs/front-matter#Settings-amp-Their-Default-Values), if specified, will take precedent. + +**Examples:** + +``` +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. +``` diff --git a/source/fa/docs/templates.md b/source/fa/docs/templates.md new file mode 100644 index 0000000000..d5385a0abd --- /dev/null +++ b/source/fa/docs/templates.md @@ -0,0 +1,110 @@ +--- +title: Templates +--- + +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. At the very least, a theme should contain an `index` template. + +{% youtube mb65bQ4iUc4 %} + +| Template | Page | Fallback | +| ---------- | ----------------- | --------- | +| `index` | Home page | | +| `post` | Posts | `index` | +| `page` | Pages | `index` | +| `archive` | Archives | `index` | +| `category` | Category archives | `archive` | +| `tag` | Tag archives | `archive` | + +## Layouts + +When pages share a similar structure - for instance, when two templates have both a header and a footer - you can consider using a `layout` to declare these structural similarities. Every layout file should contain a `body` variable to display the contents of the template in question. For example: + +```html index.ejs +index +``` + +```html layout.ejs +<!doctype html> +<html> + <body> + <%- body %> + </body> +</html> +``` + +yields: + +```html +<!doctype html> +<html> + <body> + index + </body> +</html> +``` + +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. + +## Partials + +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> +``` + +```html index.ejs +<%- partial('partial/header') %> +<div id="content">Home page</div> +``` + +yields: + +```html +<h1 id="logo">My Site</h1> +<div id="content">Home page</div> +``` + +## Local Variables + +You can define local variables in templates and use them in other templates. + +```html partial/header.ejs +<h1 id="logo"><%= title %></h1> +``` + +```html index.ejs +<%- partial('partial/header', {title: 'Hello World'}) %> +<div id="content">Home page</div> +``` + +yields: + +```html +<h1 id="logo">Hello World</h1> +<div id="content">Home page</div> +``` + +## Optimization + +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. Aside from simplifying your theme, you may also try Fragment Caching, which was introduced in Hexo 2.7. + +This feature was borrowed from [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. + +Fragment caching is best used for headers, footers, sidebars or other static content that is unlikely to change from template to template. For example: + +```js +<%- fragment_cache('header', function(){ + return '<header></header>'; +}); +``` + +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. +{% endnote %} diff --git a/source/fa/docs/themes.md b/source/fa/docs/themes.md new file mode 100644 index 0000000000..c142ebf49d --- /dev/null +++ b/source/fa/docs/themes.md @@ -0,0 +1,83 @@ +--- +title: Themes +--- + +{% youtube 5ROIU_9dYe4 %} + +It's easy to build a Hexo theme - you just have to create a new folder. To start using your theme, modify the `theme` setting in your site's `_config.yml`. A theme should have the following structure: + +```plain +. +├── _config.yml +├── languages +├── layout +├── scripts +└── source +``` + +### \_config.yml + +Theme configuration file. Unlike the site's primary configuration file, modifying this doesn't require a server restart. + +### languages + +Language folder. See [internationalization (i18n)](internationalization.html) for more info. + +### layout + +Layout folder. This folder contains the theme's template files, which define the appearance of your website. Hexo provides the [Nunjucks][] template engine by default, but you can easily install additional plugins to support alternative engines such as [EJS][] or [Pug][]. Hexo chooses the template engine based on the file extension of the template (just like the posts). For example: + +```plain +layout.ejs - uses EJS +layout.njk - uses Nunjucks +``` + +See [templates](templates.html) for more info. + +### scripts + +Script folder. Hexo will automatically load all JavaScript files in this folder during initialization. For more info, see [plugins](plugins.html). + +### source + +Source folder. Place your assets (e.g. CSS and JavaScript files) here. Hexo ignores hidden files and files or folders prefixed with `_` (underscore). + +Hexo will process and save all renderable files to the `public` folder. Non-renderable files will be copied to the `public` folder directly. + +### Publishing + +When you have finished building your theme, you can publish it to the [theme list](/themes). Before doing so, you should run the [theme unit test](https://github.com/hexojs/hexo-theme-unit-test) to ensure that everything works. The steps for publishing a theme are very similar to those for [updating documentation](contributing.html#Updating_Documentation). + +1. Fork [hexojs/site][] +2. Clone the repository to your computer and install dependencies. + + ```shell + $ git clone https://github.com/<username>/site.git + $ cd site + $ npm install + ``` + +3. Create a new yaml file in `source/_data/themes/`, use your theme name as the file name + +4. Edit `source/_data/themes/<your-theme-name>.yml` and add your theme. For example: + + ```yaml + 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 + ``` + +5. Add a screenshot (with the same name as the theme) to `source/themes/screenshots`. It must be a 800\*500px PNG. +6. Push the branch. +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 +[hexojs/site]: https://github.com/hexojs/site +[Nunjucks]: https://mozilla.github.io/nunjucks/ diff --git a/source/fa/docs/troubleshooting.md b/source/fa/docs/troubleshooting.md new file mode 100644 index 0000000000..19a5ef2632 --- /dev/null +++ b/source/fa/docs/troubleshooting.md @@ -0,0 +1,294 @@ +--- +title: Troubleshooting +--- + +In case you're experiencing problems with using Hexo, here is a list of solutions to some frequently encountered issues. If this page doesn't help you solve your problem, try doing a search on [GitHub](https://github.com/hexojs/hexo/issues) or our [Google Group](https://groups.google.com/group/hexo). + +## YAML Parsing Error + +```plain +JS-YAML: incomplete explicit mapping pair; a key node is missed at line 18, column 29: + last_updated: Last updated: %s +``` + +Wrap the string with quotations if it contains colons. + +```plain +JS-YAML: bad indentation of a mapping entry at line 18, column 31: + last_updated:"Last updated: %s" +``` + +Make sure you are using soft tabs and add a space after colons. + +You can see [YAML Spec](http://www.yaml.org/spec/1.2/spec.html) for more info. + +## EMFILE Error + +```plain +Error: EMFILE, too many open files +``` + +Though Node.js has non-blocking I/O, the maximum number of synchronous I/O is still limited by the system. 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 +``` + +**Error: cannot modify limit** + +If you encounter the following error: + +```bash +$ ulimit -n 10000 +ulimit: open files: cannot modify limit: Operation not permitted +``` + +It means some system-wide configurations are preventing `ulimit` to being increased to a certain limit. + +To override the limit: + +1. Add the following line to "/etc/security/limits.conf": + +``` +* - nofile 10000 + +# '*' 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) + +``` +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": + +``` +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 Deployment Problems + +### RPC failed + +```plain +error: RPC failed; result=22, HTTP code = 403 + +fatal: 'username.github.io' does not appear to be a git repository +``` + +Make sure you have [set up git](https://help.github.com/articles/set-up-git) on your computer properly or try to use HTTPS repository URL instead. + +### 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` + +## Server Problems + +```plain +Error: listen EADDRINUSE +``` + +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 +``` + +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 +$ npm install hexo --no-optional +``` + +See [#1326](https://github.com/hexojs/hexo/issues/1326#issuecomment-113871796) + +## Iterate Data Model on Jade or Swig + +Hexo uses [Warehouse][] for its data model. It's not an array so you may have to transform objects into iterables. + +``` +{% for post in site.posts.toArray() %} +{% endfor %} +``` + +## Data Not Updated + +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 +``` + +## 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 uses [Nunjucks][] to render posts ([Swig][] was used in the older version, which shares a similar syntax). 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 %} +Hello {{ world }} +{% endraw %} +``` + +```` +``` +Hello {{ world }} +``` +```` + +## ENOSPC Error (Linux) + +Sometimes when running the command `$ hexo server` it returns an error: + +``` +Error: watch ENOSPC ... +``` + +It can be fixed by running `$ npm dedupe` or, if that doesn't help, try the following in the Linux console: + +``` +$ echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p +``` + +This will increase the limit for the number of files you can watch. + +## EMPERM Error (Windows Subsystem for Linux) + +When running `$ hexo server` in a BashOnWindows environment, it returns the following error: + +``` +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: + +```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). + +## 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 +Template render error: (unknown path) +``` + +Possible cause: + +- 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. [`{% raw %} {# {% endraw %}`](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 install js-yaml@latest +``` + +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/ +[Nunjucks]: https://mozilla.github.io/nunjucks/ diff --git a/source/fa/docs/variables.md b/source/fa/docs/variables.md new file mode 100644 index 0000000000..ee076a0858 --- /dev/null +++ b/source/fa/docs/variables.md @@ -0,0 +1,103 @@ +--- +title: Variables +--- + +{% youtube T9oAax-IRw0 %} + +### Global Variables + +| Variable | Description | Type | +| -------- | ------------------------------------------------------------------- | --------------------------------------- | +| `site` | Sitewide information. | `object`; see [Site Variables][] | +| `page` | Page specific information and custom variables set in front-matter. | `object`; see [Page Variables][] | +| `config` | Site configuration. | `object` (your site's \_config file) | +| `theme` | Theme configuration. Inherits from site configuration. | `object` (your theme's \_config file) | +| `path` | Path of current page | `string` | +| `url` | Full URL of current page | `string` | +| `env` | Environment variables | ??? | + +{% 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 + +| Variable | Description | Type | +| ----------------- | -------------- | ---------------------- | +| `site.posts` | All posts | [Query][queryo] object | +| `site.pages` | All pages | [Query][queryo] object | +| `site.categories` | All categories | [Query][queryo] object | +| `site.tags` | All tags | [Query][queryo] object | + +### Page Variables + +**Article (`page`)** + +| Variable | Description | Type | +| ------------------ | -------------------------------------------------------------------------------------- | -------------------- | +| `page.title` | Article title | `string` | +| `page.date` | Article created date | [Moment.js][] object | +| `page.updated` | Article last updated date | [Moment.js][] object | +| `page.comments` | Comment enabled or not | `boolean` | +| `page.layout` | Layout name | `string` | +| `page.content` | The full processed content of the article | `string` | +| `page.excerpt` | Article excerpt | `string` | +| `page.more` | Contents except article excerpt | `string` | +| `page.source` | The path of the source file | `string` | +| `page.full_source` | Full path of the source file | `string` | +| `page.path` | The URL of the article without root URL. We usually use `url_for(page.path)` in theme. | `string` | +| `page.permalink` | Full (encoded) URL of the article | `string` | +| `page.prev` | The previous post, `null` if the post is the first post | ??? | +| `page.next` | The next post, `null` if the post is the last post | ??? | +| `page.raw` | The raw data of the article | ??? | +| `page.photos` | The photos of the article (Used in gallery posts) | array of ??? | +| `page.link` | The external link of the article (Used in link posts) | `string` | + +**Post (`post`):** Same as `page` layout but add the following variables. + +| Variable | Description | Type | +| ----------------- | ------------------------------- | -------------- | +| `page.published` | 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 ??? | + +**Home (`index`)** + +| Variable | Description | Type | +| ------------------ | --------------------------------------------------------------------------------------- | -------- | +| `page.per_page` | Posts displayed per page | `number` | +| `page.total` | Total number of pages | `number` | +| `page.current` | Current page number | `number` | +| `page.current_url` | The URL of current page | `string` | +| `page.posts` | Posts in this page ([Data Model](https://hexojs.github.io/warehouse/)) | `object` | +| `page.prev` | Previous page number. `0` if the current page is the first. | `number` | +| `page.prev_link` | The URL of previous page. `''` if the current page is the first. | `string` | +| `page.next` | Next page number. `0` if the current page is the last. | `number` | +| `page.next_link` | The URL of next page. `''` if the current page is the last. | `string` | +| `page.path` | The URL of current page without root URL. We usually use `url_for(page.path)` in theme. | `string` | + +**Archive (`archive`):** Same as `index` layout but add the following variables. + +| Variable | Description | Type | +| -------------- | --------------------------------------------- | --------- | +| `page.archive` | Equals `true` | `boolean` | +| `page.year` | Archive year (4-digit) | `number` | +| `page.month` | Archive month (2-digit without leading zeros) | `number` | + +**Category (`category`):** Same as `index` layout but add the following variables. + +| Variable | Description | Type | +| --------------- | ------------- | -------- | +| `page.category` | Category name | `string` | + +**Tag (`tag`):** Same as `index` layout but add the following variables. + +| Variable | Description | Type | +| ---------- | ----------- | -------- | +| `page.tag` | Tag name | `string` | + +[queryo]: https://hexojs.github.io/warehouse/classes/query.default.html + +[Moment.js]: http://momentjs.com/ +[Site Variables]: #Site-Variables +[Page Variables]: #Page-Variables diff --git a/source/fa/docs/writing.md b/source/fa/docs/writing.md new file mode 100644 index 0000000000..14ad1e780b --- /dev/null +++ b/source/fa/docs/writing.md @@ -0,0 +1,74 @@ +--- +title: Writing +--- + +{% youtube AIqBubK6ZLc %} + +To create a new post or a new page, you can run the following command: + +```bash +$ hexo new [layout] <title> +``` + +`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 + +There are three default layouts in Hexo: `post`, `page` and `draft`. Files created by each of them is saved to a different path. Newly created posts are saved to the `source/_posts` folder. + +| Layout | Path | +| ------- | ---------------- | +| `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](/docs/front-matter#Layout) for more details. +{% endnote %} + +## Filename + +By default, Hexo uses the post title as its filename. You can edit the `new_post_name` setting in `_config.yml` to change the default filename. For example, `:year-:month-:day-:title.md` will prefix filenames with the post creation date. You can use the following placeholders: + +| Placeholder | Description | +| ----------- | -------------------------------------------------------- | +| `: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` | + +## Drafts + +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> +``` + +Drafts are not displayed by default. You can add the `--draft` option when running Hexo or enable the `render_drafts` setting in `_config.yml` to render drafts. + +## Scaffolds + +When creating posts, Hexo will build files based on the corresponding file in `scaffolds` folder. For example: + +```bash +$ hexo new photo "My Gallery" +``` + +When you run this command, Hexo will try to find `photo.md` in the `scaffolds` folder and build the post based on it. The following placeholders are available in scaffolds: + +| Placeholder | Description | +| ----------- | ----------------- | +| `layout` | Layout | +| `title` | Title | +| `date` | File created date | + +## Supported Formats + +Hexo supports 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. + +You can rename your posts and change the file extension from `.md` to `.ejs`, then Hexo will use `hexo-renderer-ejs` to render that file, and so do the other formats. diff --git a/source/fa/index.md b/source/fa/index.md new file mode 100644 index 0000000000..e5f4469e1a --- /dev/null +++ b/source/fa/index.md @@ -0,0 +1,41 @@ +--- +layout: index +description: Hexo is a fast, simple & powerful blog framework powered by Node.js. +subtitle: A fast, simple & powerful blog framework +comments: false +--- + +<ul id="intro-feature-list"> + <li class="intro-feature-wrap"> + <div class="intro-feature"> + <div class="intro-feature-icon"> + <i class="fa fa-bolt"></i> + </div> + <h3 class="intro-feature-title">Blazing Fast</h3> + <p class="intro-feature-desc">Incredible generating speed powered by Node.js. Hundreds of files take only seconds to build.</p> + </div> + </li> + <li class="intro-feature-wrap"> + <div class="intro-feature"> + <div class="intro-feature-icon"> + <i class="fa fa-pencil"></i> + </div> + <h3 class="intro-feature-title">Markdown Support</h3> + <p class="intro-feature-desc">All features of GitHub Flavored Markdown are supported, including most Octopress plugins.</p> + </div></li><li class="intro-feature-wrap"> + <div class="intro-feature"> + <div class="intro-feature-icon"> + <i class="fa fa-cloud-upload"></i> + </div> + <h3 class="intro-feature-title">One-Command Deployment</h3> + <p class="intro-feature-desc">You only need one command to deploy your site to GitHub Pages, Heroku or other platforms.</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">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> diff --git a/source/tr/api/box.md b/source/tr/api/box.md new file mode 100644 index 0000000000..5b14bc6b2f --- /dev/null +++ b/source/tr/api/box.md @@ -0,0 +1,62 @@ +--- +title: Box +--- + +Box is a container used for processing files in a specified folder. Hexo uses two different boxes: `hexo.source` and `hexo.theme`. The former is used to process the `source` folder and the latter to process the `theme` folder. + +## Load Files + +Box provides two methods for loading files: `process` and `watch`. `process` loads all files in the folder. `watch` does the same, but also starts watching for file changes. + +```js +box.process().then(function () { + // ... +}); + +box.watch().then(function () { + // You can call box.unwatch() later to stop watching. +}); +``` + +## Path Matching + +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 +``` + +See [util.Pattern][] for more info. + +## Processors + +A processor is an essential element of Box and is used to process files. You can use path matching as described above to restrict what exactly the processor should process. Register a new processor with the `addProcessor` method. + +```js +box.addProcessor("posts/:id", function (file) { + // +}); +``` + +Box passes the content of matched files to processors. This information can then be read straight from the `file` argument in the callback: + +| Attribute | Description | +| --------- | ----------------------------------------------------------------- | +| `source` | Full path of the file | +| `path` | Relative path to the box of the file | +| `type` | File type. The value can be `create`, `update`, `skip`, `delete`. | +| `params` | The information from path matching. | + +Box also provides some methods so you don't have to do file IO by yourself. + +| Method | Description | +| ------------ | --------------------------------------- | +| `read` | Read a file | +| `readSync` | Read a file synchronously | +| `stat` | Read the status of a file | +| `statSync` | Read the status of a file synchronously | +| `render` | Render a file | +| `renderSync` | Render a file synchronously | + +[util.Pattern]: https://github.com/hexojs/hexo-util#patternrule diff --git a/source/tr/api/console.md b/source/tr/api/console.md new file mode 100644 index 0000000000..5c94dd2458 --- /dev/null +++ b/source/tr/api/console.md @@ -0,0 +1,75 @@ +--- +title: Console +--- + +The console forms the bridge between Hexo and its users. It registers and describes the available console commands. + +## Synopsis + +```js +hexo.extend.console.register(name, desc, options, function (args) { + // ... +}); +``` + +| Argument | Description | +| --------- | ----------- | +| `name` | Name | +| `desc` | Description | +| `options` | Options | + +An argument `args` will be passed into the function. This is the argument that users type into the terminal. It's parsed by [Minimist][]. + +## Options + +### usage + +The usage of a console command. For example: + +```js +{ + usage: "[layout] <title>"; +} +// hexo new [layout] <title> +``` + +### arguments + +The description of each argument of a console command. For example: + +```js +{ + arguments: [ + { name: "layout", desc: "Post layout" }, + { name: "title", desc: "Post title" }, + ]; +} +``` + +### options + +The description of each option of a console command. For example: + +```js +{ + options: [{ name: "-r, --replace", desc: "Replace existing files" }]; +} +``` + +### desc + +More detailed information about a console command. + +## Example + +```js +hexo.extend.console.register( + "config", + "Display configuration", + function (args) { + console.log(hexo.config); + }, +); +``` + +[Minimist]: https://github.com/minimistjs/minimist diff --git a/source/tr/api/deployer.md b/source/tr/api/deployer.md new file mode 100644 index 0000000000..c26df36fdd --- /dev/null +++ b/source/tr/api/deployer.md @@ -0,0 +1,15 @@ +--- +title: Deployer +--- + +A deployer helps users quickly deploy their site to a remote server without complicated commands. + +## Synopsis + +```js +hexo.extend.deployer.register(name, function (args) { + // ... +}); +``` + +An argument `args` will be passed into the function. It contains the `deploy` value set in `_config.yml`, as well as the exact input users typed into their terminal. diff --git a/source/tr/api/events.md b/source/tr/api/events.md new file mode 100644 index 0000000000..06b913a525 --- /dev/null +++ b/source/tr/api/events.md @@ -0,0 +1,54 @@ +--- +title: Events +--- + +Hexo inherits from [EventEmitter][]. 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 + +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) { + // +}); +``` + +| Data | Description | +| -------------- | -------------------------- | +| `post.path` | Full path of the post file | +| `post.content` | Content of the post file | + +### processBefore + +Emitted before processing begins. This event returns a path representing the root directory of the box. + +### processAfter + +Emitted after processing finishes. This event returns a path representing the root directory of the box. + +### ready + +Emitted after initialization finishes. + +[EventEmitter]: https://nodejs.org/dist/latest/docs/api/events.html diff --git a/source/tr/api/filter.md b/source/tr/api/filter.md new file mode 100644 index 0000000000..e7d9f30672 --- /dev/null +++ b/source/tr/api/filter.md @@ -0,0 +1,226 @@ +--- +title: Filter +--- + +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). + +## Synopsis + +```js +hexo.extend.filter.register(type, function() { + // User configuration + const { config } = this; + if (config.external_link.enable) // do something... + + // Theme configuration + const { config: themeCfg } = this.theme; + if (themeCfg.fancybox) // do something... + +}, priority); +``` + +You can define the `priority`. Lower `priority` means that it will be executed first. The default `priority` is 10. We recommend using user-configurable priority value that user can specify in the config, e.g. `hexo.config.your_plugin.priority`. + +## Execute Filters + +```js +hexo.extend.filter.exec(type, data, options); +hexo.extend.filter.execSync(type, data, options); +``` + +| Option | Description | +| --------- | --------------------------------- | +| `context` | Context | +| `args` | Arguments. This must be an array. | + +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. You can even use `args` to specify other arguments in filters. For example: + +```js +hexo.extend.filter.register("test", function (data, arg1, arg2) { + // data === 'some data' + // arg1 === 'foo' + // arg2 === 'bar' + + return "something"; +}); + +hexo.extend.filter.register("test", function (data, arg1, arg2) { + // data === 'something' +}); + +hexo.extend.filter.exec("test", "some data", { + args: ["foo", "bar"], +}); +``` + +You can also use the following methods to execute filters: + +```js +hexo.execFilter(type, data, options); +hexo.execFilterSync(type, data, options); +``` + +## Unregister Filters + +```js +hexo.extend.filter.unregister(type, filter); +``` + +**Example** + +```js +// Unregister a filter which is registered with named function + +const filterFn = (data) => { + data = "something"; + return data; +}; +hexo.extend.filter.register("example", filterFn); + +hexo.extend.filter.unregister("example", filterFn); +``` + +```js +// Unregister a filter which is registered with commonjs module + +hexo.extend.filter.register("example", require("path/to/filter")); + +hexo.extend.filter.unregister("example", require("path/to/filter")); +``` + +## Filter List + +Here is a list of filters used by Hexo. + +### before_post_render + +Executed before a post is rendered. Refer to [post rendering](posts.html#Render) to learn the execution steps. + +For example, to transform the title to lower case: + +```js +hexo.extend.filter.register("before_post_render", function (data) { + data.title = data.title.toLowerCase(); + return data; +}); +``` + +### after_post_render + +Executed after a post is rendered. Refer to [post rendering](posts.html#Render) to learn the execution steps. + +For example, to replace `@username` with a link to a Twitter profile: + +```js +hexo.extend.filter.register("after_post_render", function (data) { + data.content = data.content.replace( + /@(\d+)/, + '<a href="http://twitter.com/$1">#$1</a>', + ); + return data; +}); +``` + +### before_exit + +Executed before Hexo is about to exit -- this will run right after `hexo.exit` is called. + +```js +hexo.extend.filter.register("before_exit", function () { + // ... +}); +``` + +### before_generate + +Executed before generation begins. + +```js +hexo.extend.filter.register("before_generate", function () { + // ... +}); +``` + +### after_generate + +Executed after generation finishes. + +```js +hexo.extend.filter.register("after_generate", function () { + // ... +}); +``` + +### template_locals + +Modify [local variables](../docs/variables.html) in templates. + +For example, to add the current time to the local variables of templates: + +```js +hexo.extend.filter.register("template_locals", function (locals) { + locals.now = Date.now(); + return locals; +}); +``` + +### after_init + +Executed after Hexo is initialized -- this will run right after `hexo.init` completes. + +```js +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 + +Executed after rendering finishes. You can see [rendering](rendering.html#after_render_Filters) for more info. + +### after_clean + +Executed after generated files and cache are removed with `hexo clean` command. + +```js +hexo.extend.filter.register("after_clean", function () { + // remove some other temporary files +}); +``` + +### server_middleware + +Add middleware to the server. `app` is a [Connect][] instance. + +For example, to add `X-Powered-By: Hexo` to the response header: + +```js +hexo.extend.filter.register("server_middleware", function (app) { + app.use(function (req, res, next) { + res.setHeader("X-Powered-By", "Hexo"); + next(); + }); +}); +``` + +[Connect]: https://github.com/senchalabs/connect diff --git a/source/tr/api/generator.md b/source/tr/api/generator.md new file mode 100644 index 0000000000..5f7218cf90 --- /dev/null +++ b/source/tr/api/generator.md @@ -0,0 +1,111 @@ +--- +title: Generator +--- + +A generator builds routes based on processed files. + +## Synopsis + +```js +hexo.extend.generator.register(name, function (locals) { + // ... +}); +``` + +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. + +## Update Routes + +```js +hexo.extend.generator.register("test", function (locals) { + // Object + return { + path: "foo", + data: "foo", + }; + + // Array + return [ + { path: "foo", data: "foo" }, + { path: "bar", data: "bar" }, + ]; +}); +``` + +| Attribute | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `path` | Path not including the prefixing `/`. | +| `data` | 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. | + +When the source files are updated, Hexo will execute all generators and rebuild the routes. **Please return the data and do not access the router directly.** + +## Example + +### Archive Page + +Create an archive page at `archives/index.html`. We pass all posts as data to the templates. This data is equivalent to the `page` variable in templates. + +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) { + return { + path: "archives/index.html", + data: locals, + layout: ["archive", "index"], + }; +}); +``` + +### Archive Page with Pagination + +You can use the convenient official tool [hexo-pagination][] to easily build archive pages with pagination. + +```js +var pagination = require("hexo-pagination"); + +hexo.extend.generator.register("archive", function (locals) { + // hexo-pagination makes an index.html for the /archives route + return pagination("archives", locals.posts, { + perPage: 10, + layout: ["archive", "index"], + data: {}, + }); +}); +``` + +### Generate All Posts + +Iterate over all posts in `locals.posts` and create routes for all the posts. + +```js +hexo.extend.generator.register("post", function (locals) { + return locals.posts.map(function (post) { + return { + path: post.path, + data: post, + layout: "post", + }; + }); +}); +``` + +### Copy Files + +This time we don't return the data explicitly but instead set `data` to a function so the route will build `fs.ReadStream` only when needed. + +```js +var fs = require("hexo-fs"); + +hexo.extend.generator.register("asset", function (locals) { + return { + path: "file.txt", + data: function () { + return fs.createReadStream("path/to/file.txt"); + }, + }; +}); +``` + +[hexo-pagination]: https://github.com/hexojs/hexo-pagination diff --git a/source/tr/api/helper.md b/source/tr/api/helper.md new file mode 100644 index 0000000000..76a72e8bcd --- /dev/null +++ b/source/tr/api/helper.md @@ -0,0 +1,52 @@ +--- +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. + +## Synopsis + +```js +hexo.extend.helper.register(name, function () { + // ... +}); +``` + +## Example + +```js +hexo.extend.helper.register("js", function (path) { + return '<script src="' + path + '"></script>'; +}); +``` + +```js +<%- js('script.js') %> +// <script src="script.js"></script> +``` + +## FAQ + +### Where to place custom helper? + +Place it under `scripts/` or `themes/<yourtheme>/scripts/` folder. + +### How do I use another registered helper in my custom helper? + +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) { + return '<script src="' + this.url_for(path) + '"></script>'; +}); +``` + +### How do I use a registered helper in another extension (e.g. Filter, Injector)? + +`hexo.extend.helper.get` will return the helper function, but it needs to have hexo as its context, so: + +```js +const url_for = hexo.extend.helper.get("url_for").bind(hexo); +``` diff --git a/source/tr/api/index.md b/source/tr/api/index.md new file mode 100644 index 0000000000..acca2eea71 --- /dev/null +++ b/source/tr/api/index.md @@ -0,0 +1,75 @@ +--- +title: API +--- + +This documentation provides more detailed information about the API and will be particularly helpful for people who want to modify the Hexo source code or write new plugins. If you are interested in more basic usage of Hexo, please refer to the [docs](../docs) instead. + +Please note that this documentation is only valid for Hexo 3 and above. + +## Initialize + +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"); +var hexo = new Hexo(process.cwd(), {}); + +hexo.init().then(function () { + // ... +}); +``` + +| Option | Description | Default | +| ------------------ | ----------------------------------------------------------------------------------------------------- | --------------------------------- | +| `debug` | Enable debug mode. Display debug messages in the terminal and save `debug.log` in the root directory. | `false` | +| `safe` | Enable safe mode. Don't load any plugins. | `false` | +| `silent` | Enable silent mode. Don't display any messages in the terminal. | `false` | +| `config` | Specify the path of the configuration file. | `_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 | + +## Load Files + +Hexo provides two methods for loading files: `load` and `watch`. `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. + +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.watch().then(function () { + // You can call hexo.unwatch() later to stop watching. +}); +``` + +## Execute Commands + +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 + +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 + .call("generate") + .then(function () { + return hexo.exit(); + }) + .catch(function (err) { + return hexo.exit(err); + }); +``` diff --git a/source/tr/api/injector.md b/source/tr/api/injector.md new file mode 100644 index 0000000000..a1200bf9d7 --- /dev/null +++ b/source/tr/api/injector.md @@ -0,0 +1,141 @@ +--- +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. + +## Synopsis + +```js +hexo.extend.injector.register(entry, value, to); +``` + +### entry `<string>` + +Where the code will be injected inside the HTML. + +Support those values: + +- `head_begin`: Inject code snippet right after `<head>` (Default). +- `head_end`: Inject code snippet right before `</head>`. +- `body_begin`: Inject code snippet right after `<body>`. +- `body_end`: Inject code snippet right before `</body>`. + +### value `<string> | <Function>` + +> A function that returns string is supported. + +The code snippet to be injected. + +### to `<string>` + +Which page will code snippets being injected. + +- `default`: Inject to every page (Default). +- `home`: Only inject to home page (which has `is_home()` helper being `true`) +- `post`: Only inject to post pages (which has `is_post()` helper being `true`) +- `page`: Only inject to pages (which has `is_page()` helper being `true`) +- `archive`: Only inject to archive pages (which has `is_archive()` helper being `true`) +- `category`: Only inject to category pages (which has `is_category()` helper being `true`) +- `tag`: Only inject to tag pages (which has `is_tag()` helper being `true`) +- Custom layout name could be used as well, see [Writing - Layout](/docs/writing#Layout). + +--- + +There are other internal functions, see [hexojs/hexo#4049](https://github.com/hexojs/hexo/pull/4049) for more details. + +## Example + +```js +const css = hexo.extend.helper.get("css").bind(hexo); +const js = hexo.extend.helper.get("js").bind(hexo); + +hexo.extend.injector.register( + "head_end", + () => { + return css( + "https://cdn.jsdelivr.net/npm/aplayer@1.10.1/dist/APlayer.min.css", + ); + }, + "music", +); + +hexo.extend.injector.register( + "body_end", + '<script src="https://cdn.jsdelivr.net/npm/aplayer@1.10.1/dist/APlayer.min.js">', + "music", +); + +hexo.extend.injector.register("body_end", () => { + return js("/js/jquery.js"); +}); +``` + +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. + +## Accessing user configuration + +Use any of the following options: + +1. + +```js +const css = hexo.extend.helper.get("css").bind(hexo); + +hexo.extend.injector.register("head_end", () => { + const { cssPath } = hexo.config.fooPlugin; + return css(cssPath); +}); +``` + +2. + +```js index.js +/* global hexo */ + +hexo.extend.injector.register("head_end", require("./lib/inject").bind(hexo)); +``` + +```js lib/inject.js +module.exports = function () { + const css = this.extend.helper.get("css"); + const { cssPath } = this.config.fooPlugin; + return css(cssPath); +}; +``` + +```js lib/inject.js +function injectFn() { + const css = this.extend.helper.get("css"); + const { cssPath } = this.config.fooPlugin; + return css(cssPath); +} + +module.exports = injectFn; +``` + +3. + +```js index.js +/* global hexo */ + +hexo.extend.injector.register("head_end", require("./lib/inject")(hexo)); +``` + +```js lib/inject.js +module.exports = (hexo) => () => { + const css = hexo.extend.helper.get("css").bind(hexo); + const { cssPath } = hexo.config.fooPlugin; + return css(cssPath); +}; +``` + +```js lib/inject.js +const injectFn = (hexo) => { + const css = hexo.extend.helper.get("css").bind(hexo); + const { cssPath } = hexo.config.fooPlugin; + return css(cssPath); +}; + +module.exports = (hexo) => injectFn(hexo); +``` diff --git a/source/tr/api/locals.md b/source/tr/api/locals.md new file mode 100644 index 0000000000..2b2e54a848 --- /dev/null +++ b/source/tr/api/locals.md @@ -0,0 +1,46 @@ +--- +title: Local Variables +--- + +Local variables are used for template rendering, which is the `site` variable in templates. + +## Default Variables + +| Variable | Description | +| ------------ | -------------- | +| `posts` | All posts | +| `pages` | All pages | +| `categories` | All categories | +| `tags` | All tags | + +## Get a Variable + +```js +hexo.locals.get("posts"); +``` + +## Set a Variable + +```js +hexo.locals.set('posts', function(){ + return ... +}); +``` + +## Remove a Variable + +```js +hexo.locals.remove("posts"); +``` + +## Get All Variable + +```js +hexo.locals.toObject(); +``` + +## Invalidate the cache + +```js +hexo.locals.invalidate(); +``` diff --git a/source/tr/api/migrator.md b/source/tr/api/migrator.md new file mode 100644 index 0000000000..2f57a842c1 --- /dev/null +++ b/source/tr/api/migrator.md @@ -0,0 +1,15 @@ +--- +title: Migrator +--- + +A migrator helps users migrate from other systems to Hexo. + +## Synopsis + +```js +hexo.extend.migrator.register(name, function (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/tr/api/posts.md b/source/tr/api/posts.md new file mode 100644 index 0000000000..055988f4ae --- /dev/null +++ b/source/tr/api/posts.md @@ -0,0 +1,62 @@ +--- +title: Posts +--- + +## Create a Post + +```js +hexo.post.create(data, replace); +``` + +| Argument | Description | +| --------- | ---------------------- | +| `data` | Data | +| `replace` | Replace existing files | + +The attributes of a post can be defined in `data`. The table below is not exhaustive. Additional attributes may be appended to the front-matter. + +| Data | Description | +| -------- | -------------------------------------------------------------------------------- | +| `title` | Title | +| `slug` | URL | +| `layout` | Layout. Defaults to the `default_layout` setting. | +| `path` | Path. Hexo builds the post path based on the `new_post_path` setting by default. | +| `date` | Date. Defaults to the current date. | + +## Publish a Draft + +```js +hexo.post.publish(data, replace); +``` + +| Argument | Description | +| --------- | ---------------------- | +| `data` | Data | +| `replace` | Replace existing files | + +The attributes of a post can be defined in `data`. The table below is not exhaustive. Additional attributes may be appended to the front-matter. + +| Data | Description | +| -------- | ------------------------------------------------- | +| `slug` | File name (Required) | +| `layout` | Layout. Defaults to the `default_layout` setting. | + +## Render + +```js +hexo.post.render(source, data); +``` + +| Argument | Description | +| -------- | ------------------------------ | +| `source` | Full path of a file (Optional) | +| `data` | Data | + +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: + +- Execute `before_post_render` filters +- Render with Markdown or other renderers (depending on the extension name) +- Render with [Nunjucks][] +- Execute `after_post_render` filters + +[Nunjucks]: https://mozilla.github.io/nunjucks/ diff --git a/source/tr/api/processor.md b/source/tr/api/processor.md new file mode 100644 index 0000000000..52e91f8d07 --- /dev/null +++ b/source/tr/api/processor.md @@ -0,0 +1,15 @@ +--- +title: Processor +--- + +A processor is used to process source files in the `source` folder. + +## Synopsis + +```js +hexo.extend.processor.register(rule, function (file) { + // ... +}); +``` + +For more info, see [box](box.html). diff --git a/source/tr/api/renderer.md b/source/tr/api/renderer.md new file mode 100644 index 0000000000..916a2c5030 --- /dev/null +++ b/source/tr/api/renderer.md @@ -0,0 +1,86 @@ +--- +title: Renderer +--- + +A renderer is used to render content. + +## Synopsis + +```js +hexo.extend.renderer.register( + name, + output, + function (data, options) { + // ... + }, + sync, +); +``` + +| Argument | Description | +| -------- | ----------------------------------------------------------- | +| `name` | Input filename extension (lower case, without leading `.`) | +| `output` | Output filename extension (lower case, without leading `.`) | +| `sync` | Sync mode | + +Three arguments will be passed into the render function: + +| Argument | Description | +| ---------- | ------------------------------------------------------------------------------------------------- | +| `data` | Include two attributes: file path `path` and file content `text`. `path` won't necessarily exist. | +| `option` | Options | +| `callback` | Callback function of two parameters `err`, `value`. | + +## Example + +### Async Mode + +```js +var stylus = require("stylus"); + +// Callback +hexo.extend.renderer.register( + "styl", + "css", + function (data, options, callback) { + stylus(data.text).set("filename", data.path).render(callback); + }, +); + +// Promise +hexo.extend.renderer.register("styl", "css", function (data, options) { + return new Promise(function (resolve, reject) { + resolve("test"); + }); +}); +``` + +### Sync Mode + +```js +var ejs = require("ejs"); + +hexo.extend.renderer.register( + "ejs", + "html", + function (data, options) { + options.filename = data.path; + return ejs.render(data.text, options); + }, + true, +); +``` + +### Disable Nunjucks tags + +Nunjucks tags `{{ }}` or `{% %}` (utilized by [tag plugin](/docs/tag-plugins)) are processed by default, to disable: + +```js +function lessFn(data, options) { + // do something +} + +lessFn.disableNunjucks = true; + +hexo.extend.renderer.register("less", "css", lessFn); +``` diff --git a/source/tr/api/rendering.md b/source/tr/api/rendering.md new file mode 100644 index 0000000000..30a5b3ee20 --- /dev/null +++ b/source/tr/api/rendering.md @@ -0,0 +1,80 @@ +--- +title: Rendering +--- + +There are two methods for rendering files or strings in Hexo: the asynchronous `hexo.render.render` method and the synchronous `hexo.render.renderSync` method. Unsurprisingly, the two methods are very similar so only the asynchronous `hexo.render.render` will be further discussed in the below paragraphs. + +## Render a String + +When rendering a string, you must specify an `engine` to let Hexo know which rendering engine it should use. + +```js +hexo.render.render({ text: "example", engine: "swig" }).then(function (result) { + // ... +}); +``` + +## Render a File + +When rendering a file, it's not necessary to specify an `engine` because Hexo will detect the relevant rendering engine automatically based on the extension of the file. Of course, you are also allowed to explicitly define the `engine`. + +```js +hexo.render.render({ path: "path/to/file.swig" }).then(function (result) { + // ... +}); +``` + +## Render Options + +You can pass in an options object as the second argument. + +```js +hexo.render.render({ text: "" }, { foo: "foo" }).then(function (result) { + // ... +}); +``` + +## after_render Filters + +When rendering is complete, Hexo will execute the corresponding `after_render` filters. For example, we can use this feature to implement a JavaScript minifier. + +```js +var UglifyJS = require("uglify-js"); + +hexo.extend.filter.register("after_render:js", function (str, data) { + var result = UglifyJS.minify(str); + return result.code; +}); +``` + +## Check Whether a File is Renderable + +You can use the `isRenderable` or `isRenderableSync` method to check whether a file path is renderable. 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 + +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 +hexo.render.getOutput("image.png"); // ''' +``` + +## Disable Nunjucks tags + +If you are not using a [tag plugin](/docs/tag-plugins) and want to use `{{ }}` or `{% %}` in your post without using content [escaping](/docs/troubleshooting#Escape-Contents), you can disable processing of Nunjucks tag in existing renderer by: + +```js +// following example only applies to '.md' file extension +// you may need to cover other extensions, e.g. '.markdown', '.mkd' +const renderer = hexo.render.renderer.get("md"); +if (renderer) { + renderer.disableNunjucks = true; + hexo.extend.renderer.register("md", "html", renderer); +} +``` diff --git a/source/tr/api/router.md b/source/tr/api/router.md new file mode 100644 index 0000000000..afe7e94c6e --- /dev/null +++ b/source/tr/api/router.md @@ -0,0 +1,75 @@ +--- +title: Router +--- + +The router saves all paths used in the site. + +## Get a Path + +The `get` method returns a [Stream][]. For example, to save the path data to a specified destination: + +```js +var data = hexo.route.get("index.html"); +var dest = fs.createWriteStream("somewhere"); + +data.pipe(dest); +``` + +## Set a Path + +The `set` method takes a string, a [Buffer][] or a function. + +```js +// String +hexo.route.set("index.html", "index"); + +// Buffer +hexo.route.set("index.html", new Buffer("index")); + +// Function (Promise) +hexo.route.set("index.html", function () { + return new Promise(function (resolve, reject) { + resolve("index"); + }); +}); + +// Function (Callback) +hexo.route.set("index.html", function (callback) { + callback(null, "index"); +}); +``` + +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", { + data: "index", + modified: false, +}); + +// hexo.route.isModified('index.html') => false +``` + +## Remove a Path + +```js +hexo.route.remove("index.html"); +``` + +## Get the List of Routes + +```js +hexo.route.list(); +``` + +## Format a Path + +The `format` method transforms a string to a valid path. + +```js +hexo.route.format("archives/"); +// archives/index.html +``` + +[Stream]: http://nodejs.org/api/stream.html +[Buffer]: http://nodejs.org/api/buffer.html diff --git a/source/tr/api/scaffolds.md b/source/tr/api/scaffolds.md new file mode 100644 index 0000000000..e7ba7c37c1 --- /dev/null +++ b/source/tr/api/scaffolds.md @@ -0,0 +1,21 @@ +--- +title: Scaffolds +--- + +## Get a Scaffold + +```js +hexo.scaffold.get(name); +``` + +## Set a Scaffold + +```js +hexo.scaffold.set(name, content); +``` + +## Remove a Scaffold + +```js +hexo.scaffold.remove(name); +``` diff --git a/source/tr/api/tag.md b/source/tr/api/tag.md new file mode 100644 index 0000000000..3df8f8d0c4 --- /dev/null +++ b/source/tr/api/tag.md @@ -0,0 +1,169 @@ +--- +title: Tag +--- + +A tag allows users to quickly and easily insert snippets into their posts. + +## Synopsis + +```js +hexo.extend.tag.register( + name, + function (args, content) { + // ... + }, + options, +); +``` + +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. + +Since the introduction of asynchronous rendering in Hexo 3, we are using [Nunjucks][] for rendering. 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. + +```js +hexo.extend.tag.unregister(name); +``` + +**Example** + +```js +const tagFn = (args, content) => { + content = "something"; + return content; +}; + +// https://hexo.io/docs/tag-plugins#YouTube +hexo.extend.tag.unregister("youtube"); + +hexo.extend.tag.register("youtube", tagFn); +``` + +## Options + +### ends + +Use end tags. This option is `false` by default. + +### async + +Enable async mode. This option is `false` by default. + +## Examples + +### Without End Tags + +Insert a Youtube video. + +```js +hexo.extend.tag.register("youtube", function (args) { + var id = args[0]; + return ( + '<div class="video-container"><iframe width="560" height="315" src="http://www.youtube.com/embed/' + + id + + '" frameborder="0" allowfullscreen></iframe></div>' + ); +}); +``` + +### With End Tags + +Insert a pull quote. + +```js +hexo.extend.tag.register( + "pullquote", + function (args, content) { + var className = args.join(" "); + return ( + '<blockquote class="pullquote' + + className + + '">' + + content + + "</blockquote>" + ); + }, + { ends: true }, +); +``` + +### Async Rendering + +Insert a file. + +```js +var fs = require("hexo-fs"); +var pathFn = require("path"); + +hexo.extend.tag.register( + "include_code", + function (args) { + var filename = args[0]; + var path = pathFn.join(hexo.source_dir, filename); + + return fs.readFile(path).then(function (content) { + return "<pre><code>" + content + "</code></pre>"; + }); + }, + { async: true }, +); +``` + +## Front-matter and user configuration + +Any of the following options is valid: + +1. + +```js +hexo.extend.tag.register('foo', function (args) { + const [firstArg] = args; + + // User config + const { config } = hexo; + const editor = config.author + firstArg; + + // Theme config + const { config: themeCfg } = hexo.theme; + if (themeCfg.fancybox) // do something... + + // 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. + +```js index.js +hexo.extend.tag.register("foo", require("./lib/foo")(hexo)); +``` + +```js lib/foo.js +module.exports = hexo => { + return function fooFn(args) { + const [firstArg] = args; + + const { config } = hexo; + const editor = config.author + firstArg; + + const { config: themeCfg } = hexo.theme; + if (themeCfg.fancybox) // do something... + + const { title, _content, content } = this; + + return 'foo'; + }; +}; +``` + +[Nunjucks]: https://mozilla.github.io/nunjucks/ +[Swig]: https://node-swig.github.io/swig-templates/ diff --git a/source/tr/api/themes.md b/source/tr/api/themes.md new file mode 100644 index 0000000000..8e4e6e54b6 --- /dev/null +++ b/source/tr/api/themes.md @@ -0,0 +1,37 @@ +--- +title: Themes +--- + +`hexo.theme` inherits from [Box](box.html), and also saves templates. + +## 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 + +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"); + +view.render({ foo: 1, bar: 2 }).then(function (result) { + // ... +}); +``` + +You can pass options to the `render` method and it will try to process the template with the corresponding renderer and load the [helpers](helper.html). When rendering is complete, it will try to find whether a layout exists. If `layout` is `false` or if it doesn't exist, the result will be returned directly. diff --git a/source/tr/docs/asset-folders.md b/source/tr/docs/asset-folders.md new file mode 100644 index 0000000000..e99495b33c --- /dev/null +++ b/source/tr/docs/asset-folders.md @@ -0,0 +1,55 @@ +--- +title: Asset Folders +--- + +## Global Asset Folder + +Assets are non-post files in the `source` folder, such as images, CSS or JavaScript files. 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 +``` + +With asset folder management enabled, Hexo will create a folder every time you make a new post with the `hexo new [layout] <title>` command. 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 + +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. However, with the release of Hexo 3, several new [tag plugins](/docs/tag-plugins#Include-Assets) were added to core. These enable you to reference your assets more easily in posts: + +``` +{% asset_path slug %} +{% asset_img slug [title] %} +{% 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. + +## Embedding an image using markdown + +[hexo-renderer-marked](https://github.com/hexojs/hexo-renderer-marked) 3.1.0 introduced a new option that allows you to embed an image in markdown without using `asset_img` tag plugin. + +To enable: + +```yml _config.yml +post_asset_folder: true +marked: + prependRoot: true + postAsset: true +``` + +Once enabled, an asset image will be automatically resolved to its corresponding post's path. For example, "image.jpg" is located at "/2020/01/02/foo/image.jpg", meaning it is an asset image of "/2020/01/02/foo/" post, `![](image.jpg)` will be rendered as `<img src="/2020/01/02/foo/image.jpg">`. diff --git a/source/tr/docs/commands.md b/source/tr/docs/commands.md new file mode 100644 index 0000000000..2734d86b5f --- /dev/null +++ b/source/tr/docs/commands.md @@ -0,0 +1,202 @@ +--- +title: Commands +--- + +## init + +```bash +$ hexo init [folder] +``` + +Initializes a website. If no `folder` is provided, Hexo will set up a website in the current directory. + +This command is a shortcut that runs the following steps: + +1. Git clone [hexo-starter](https://github.com/hexojs/hexo-starter) including [hexo-theme-landscape](https://github.com/hexojs/hexo-theme-landscape) into the current directory or a target folder if specified. +2. Install dependencies using a package manager: [Yarn 1](https://classic.yarnpkg.com/lang/en/), [pnpm](https://pnpm.io) or [npm](https://docs.npmjs.com/cli/install), whichever is installed; if there are more than one installed, the priority is as listed. npm is bundled with [Node.js](/docs/#Install-Node-js) by default. + +## new + +```bash +$ hexo new [layout] <title> +``` + +Creates a new article. If no `layout` is provided, Hexo will use the `default_layout` from [\_config.yml](configuration.html). Use the layout `draft` to create a draft. If the `title` contains spaces, surround it with quotation marks. + +| Option | Description | +| ----------------- | ------------------------------------------ | +| `-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 + +```bash +$ hexo generate +``` + +Generates static files. + +| Option | Description | +| --------------------- | ------------------------------------------------------------------------ | +| `-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 + +```bash +$ hexo publish [layout] <filename> +``` + +Publishes a draft. + +## server + +```bash +$ hexo server +``` + +Starts a local server. By default, this is at `http://localhost:4000/`. + +| Option | Description | +| ---------------- | -------------------------------------- | +| `-p`, `--port` | Override default port | +| `-s`, `--static` | Only serve static files | +| `-l`, `--log` | Enable logger. Override logger format. | + +## deploy + +```bash +$ hexo deploy +``` + +Deploys your website. + +| Option | Description | +| ------------------ | -------------------------- | +| `-g`, `--generate` | Generate before deployment | + +## render + +```bash +$ hexo render <file1> [file2] ... +``` + +Renders files. + +| Option | Description | +| ---------------- | ------------------ | +| `-o`, `--output` | Output destination | + +## migrate + +```bash +$ hexo migrate <type> +``` + +[Migrates](migration.html) content from other blog systems. + +## clean + +```bash +$ hexo clean +``` + +Cleans the cache file (`db.json`) and generated files (`public`). + +## list + +```bash +$ hexo list <type> +``` + +Lists all routes. + +## version + +```bash +$ hexo version +``` + +Displays version information. + +## 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`. + +## Options + +### Safe mode + +```bash +$ hexo --safe +``` + +Disables loading plugins and scripts. Try this if you encounter problems after installing a new plugin. + +### Debug mode + +```bash +$ hexo --debug +``` + +Logs verbose messages to the terminal and to `debug.log`. Try this if you encounter any problems with Hexo. If you see errors, please [raise a GitHub issue](https://github.com/hexojs/hexo/issues/new?assignees=&labels=&projects=&template=bug_report.yml). + +### Silent mode + +```bash +$ hexo --silent +``` + +Silences output to the terminal. + +### Customize config file path + +```bash +$ hexo --config custom.yml +``` + +Uses a custom config file (instead of `_config.yml`). Also accepts a comma-separated list (no spaces) of JSON or YAML config files that will combine the files into a single `_multiconfig.yml`. + +```bash +$ hexo --config custom.yml,custom2.json +``` + +### Display drafts + +```bash +$ hexo --draft +``` + +Displays draft posts (stored in the `source/_drafts` folder). + +### Customize CWD + +```bash +$ hexo --cwd /path/to/cwd +``` + +Customizes the path of current working directory. diff --git a/source/tr/docs/configuration.md b/source/tr/docs/configuration.md new file mode 100644 index 0000000000..487a99b92f --- /dev/null +++ b/source/tr/docs/configuration.md @@ -0,0 +1,312 @@ +--- +title: Configuration +--- + +You can modify site settings in `_config.yml` or in an [alternate config file](#Using-an-Alternate-Config). + +### Site + +| Setting | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `title` | The title of your website | +| `subtitle` | The subtitle of your website | +| `description` | The description of your website | +| `keywords` | The keywords of your website. Supports multiple values. | +| `author` | Your name | +| `language` | The language of your website. Use a [2-letter ISO-639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) or optionally [its variant](/docs/internationalization). Default is `en`. | +| `timezone` | The timezone of your website. Hexo uses the setting on your computer by default. You can find the list of available timezones [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Some examples are `America/New_York`, `Japan`, and `UTC`. | + +### URL + +| Setting | Description | Default | +| ---------------------------- | ----------------------------------------------------------------------------------------- | --------------------------- | +| `url` | The URL of your website, must start with `http://` or `https://` | | +| `root` | The root directory of your website | `url's pathname` | +| `permalink` | The [permalink](permalinks.html) format of articles | `:year/:month/:day/:title/` | +| `permalink_defaults` | Default values of each segment in permalink | | +| `pretty_urls` | Rewrite the [`permalink`](permalinks.html) variables to pretty URLs | | +| `pretty_urls.trailing_index` | Trailing `index.html`, set to `false` to remove it | `true` | +| `pretty_urls.trailing_html` | Trailing `.html`, set to `false` to remove it (_does not apply to trailing `index.html`_) | `true` | + +{% note info Website in subdirectory %} +If your website is in a subdirectory (such as `http://example.org/blog`) set `url` to `http://example.org/blog` and set `root` to `/blog/`. +{% endnote %} + +Examples: + +```yaml +# e.g. page.permalink is http://example.com/foo/bar/index.html +pretty_urls: + trailing_index: false +# becomes http://example.com/foo/bar/ +``` + +### Directory + +| Setting | Description | 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` | Category directory | `categories` | +| `code_dir` | Include code directory (subdirectory of `source_dir`) | `downloads/code` | +| `i18n_dir` | i18n directory | `:lang` | +| `skip_render` | Paths that will be copied to `public` raw, without being rendered. You can use [glob expressions](https://github.com/micromatch/micromatch#extended-globbing) for path matching. | | + +Examples: + +```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`. +``` + +### Writing + +| Setting | Description | Default | +| ----------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------- | +| `new_post_name` | The filename format for new posts | `:title.md` | +| `default_layout` | Default layout | `post` | +| `titlecase` | Transform titles into 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` | Applies to the whole `site` or `post` only | `site` | +| `external_link.exclude` | Exclude hostname. Specify subdomain when applicable, including `www` | `[]` | +| `filename_case` | Transform filenames to `1` lower case; `2` upper case | `0` | +| `render_drafts` | Display drafts? | `false` | +| `post_asset_folder` | Enable the [Asset Folder](asset-folders.html)? | `false` | +| `relative_link` | Make links relative to the root folder? | `false` | +| `future` | Display future posts? | `true` | +| `syntax_highlighter` | Code block syntax highlight settings, see [Syntax Highlight](/docs/syntax-highlight) section for usage guide | `highlight.js` | +| `highlight` | Code block syntax highlight settings, see [Highlight.js](/docs/syntax-highlight#Highlight-js) section for usage guide | | +| `prismjs` | Code block syntax highlight settings, see [PrismJS](/docs/syntax-highlight#PrismJS) section for usage guide | | + +### Home page setting + +| Setting | Description | 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` | + +### Category & Tag + +| Setting | Description | Default | +| ------------------ | ----------------------- | --------------- | +| `default_category` | Default category | `uncategorized` | +| `category_map` | Override category slugs | | +| `tag_map` | Override tag slugs | | + +Examples: + +```yaml +category_map: + "yesterday's thoughts": yesterdays-thoughts + "C++": c-plus-plus +``` + +### Date / Time format + +Hexo uses [Moment.js](http://momentjs.com/) to process dates. + +| Setting | Description | Default | +| ---------------- | --------------------------------------------------------------------------------------------------- | ------------ | +| `date_format` | Date format | `YYYY-MM-DD` | +| `time_format` | Time format | `HH:mm:ss` | +| `updated_option` | The [`updated`](/docs/variables#Page-Variables) value to used when not provided in the front-matter | `mtime` | + +{% note info updated_option %} +`updated_option` controls the `updated` value when not provided in the front-matter: + +- `mtime`: Use file modification date as `updated`. It has been the default behaviour of Hexo since 3.0.0 +- `date`: Use `date` as `updated`. Typically used with Git workflow when file modification date could be different. +- `empty`: Simply drop `updated` when not provided. May not be compatible with most themes and plugins. + +`use_date_for_updated` is removed in v7.0.0+. Please use `updated_option: 'date'` instead. +{% endnote %} + +### Pagination + +| Setting | Description | Default | +| ---------------- | --------------------------------------------------------------- | ------- | +| `per_page` | Number of posts displayed on each page. `0` disables pagination | `10` | +| `pagination_dir` | URL format | `page` | + +Examples: + +```yaml +pagination_dir: 'page' +# http://example.com/page/2 + +pagination_dir: 'awesome-page' +# http://example.com/awesome-page/2 +``` + +### Extensions + +| Setting | Description | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `theme` | Theme name. `false` disables theming | +| `theme_config` | Theme configuration. Include any custom theme settings under this key to override theme defaults. | +| `deploy` | Deployment settings | +| `meta_generator` | [Meta generator](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#Attributes) tag. `false` disables injection of the tag. | + +### Include/Exclude Files or Folders + +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` and `exclude` options only apply to the `source/` folder, whereas `ignore` option applies to all folders. + +| Setting | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------- | +| `include` | Include hidden files (including files/folders with a name that starts with an underscore, with an exception\*) | +| `exclude` | Exclude files/folders | +| `ignore` | Ignore files/folders | + +Examples: + +```yaml +# Include/Exclude Files/Folders +include: + - ".nojekyll" + # Include 'source/css/_typing.css'. + - "css/_typing.css" + # Include any file in 'source/_css/'. + - "_css/*" + # Include any file and subfolder in 'source/_css/'. + - "_css/**/*" + +exclude: + # Exclude 'source/js/test.js'. + - "js/test.js" + # Exclude any file in 'source/js/'. + - "js/*" + # Exclude any file and subfolder in 'source/js/'. + - "js/**/*" + # Exclude any file with filename that starts with 'test' in 'source/js/'. + - "js/test*" + # Exclude any file with filename that starts with 'test' in 'source/js/' and its subfolders. + - "js/**/test*" + # Do not use this to exclude posts in the 'source/_posts/'. + # Use skip_render for that. Or prepend an underscore to the filename. + # - "_posts/hello-world.md" # Does not work. + +ignore: + # Ignore any folder named 'foo'. + - "**/foo" + # Ignore 'foo' folder in 'themes/' only. + - "**/themes/*/foo" + # 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:` and `exclude:` do not apply to the `themes/` folder. Either use `ignore:` or alternatively, prepend an underscore to the file/folder name to exclude. + +\* 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. + +### Using an Alternate Config + +A custom config file path can be specified by adding the `--config` flag to your `hexo` commands with a path to an alternate YAML or JSON config file, or a comma-separated list (no spaces) of multiple YAML or JSON files. + +```bash +# use 'custom.yml' in place of '_config.yml' +$ hexo server --config custom.yml + +# use 'custom.yml' & 'custom2.json', prioritizing 'custom2.json' +$ hexo server --config custom.yml,custom2.json +``` + +Using multiple files combines all the config files and saves the merged settings to `_multiconfig.yml`. The later values take precedence. It works with any number of JSON and YAML files with arbitrarily deep objects. Note that **no spaces are allowed in the list**. + +For instance, in the above example if `foo: bar` is in `custom.yml`, but `"foo": "dinosaur"` is in `custom2.json`, `_multiconfig.yml` will contain `foo: dinosaur`. + +### Alternate Theme Config + +Hexo themes are independent projects, with separate `_config.yml` files. + +Instead of forking a theme, and maintaining a custom version with your settings, you can configure it from somewhere else: + +**from `theme_config` in site's primary configuration file** + +> Supported since Hexo 2.8.2 + +```yml +# _config.yml +theme: "my-theme" +theme_config: + bio: "My awesome bio" + foo: + bar: "a" +``` + +```yml +# themes/my-theme/_config.yml +bio: "Some generic bio" +logo: "a-cool-image.png" + foo: + baz: 'b' +``` + +Resulting in theme configuration: + +```json +{ + "bio": "My awesome bio", + "logo": "a-cool-image.png", + "foo": { + "bar": "a", + "baz": "b" + } +} +``` + +**from a dedicated `_config.[theme].yml` file** + +> Supported since Hexo 5.0.0 + +The file should be placed in your site folder, both `yml` and `json` are supported. `theme` inside `_config.yml` must be configured for Hexo to read `_config.[theme].yml` + +```yml +# _config.yml +theme: "my-theme" +``` + +```yml +# _config.my-theme.yml +bio: "My awesome bio" +foo: + bar: "a" +``` + +```yml +# themes/my-theme/_config.yml +bio: "Some generic bio" +logo: "a-cool-image.png" + foo: + baz: 'b' +``` + +Resulting in theme configuration: + +```json +{ + "bio": "My awesome bio", + "logo": "a-cool-image.png", + "foo": { + "bar": "a", + "baz": "b" + } +} +``` + +{% note %} +We strongly recommend that you store your theme configuration in one place. But in case you have to store your theme configuration separately, you need to know the priority of those configurations: The `theme_config` inside site's primary configuration file has the highest priority during merging, then the dedicated theme configuration file. The `_config.yml` file under the theme directory has the lowest priority. +{% endnote %} diff --git a/source/tr/docs/contributing.md b/source/tr/docs/contributing.md new file mode 100644 index 0000000000..d645279a23 --- /dev/null +++ b/source/tr/docs/contributing.md @@ -0,0 +1,111 @@ +--- +title: Contributing +--- + +We welcome you to join the development of Hexo. 🤗 + +## Development + +We welcome you to join the development of Hexo. This document will help you through the process. + +### Before You Start + +Please read [Contributor Covenant Code of Conduct](https://github.com/hexojs/hexo/blob/master/CODE_OF_CONDUCT.md) first. + +Please follow the coding style: + +- Follow [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html). +- Use soft-tabs with a two space indent. +- Don't put commas first. + +Also, Hexo has its own [ESLint config](https://github.com/hexojs/eslint-config-hexo), so please make sure your contribution will make ESLint happy. + +### Workflow + +1. Fork [hexojs/hexo][]. +2. Clone the repository to your computer and install dependencies. + +```bash +$ git clone https://github.com/<username>/hexo.git +$ cd hexo +$ npm install +$ git submodule update --init +``` + +3. Create a feature branch. + +```bash +$ git checkout -b new_feature +``` + +4. Start hacking. +5. Push the branch: + +``` +$ git push origin new_feature +``` + +6. Create a pull request and describe the change. + +### Notice + +- Please don't modify version number in `package.json`. +- Your pull request will only get merged when tests passed. Don't forget to run tests before submission. + +```bash +$ npm test +``` + +## Updating official-plugins + +Also, we welcome PR or issue to [official-plugins](https://github.com/hexojs). 🤗 + +## Updating Documentation + +The Hexo documentation is open source and you can find the source code on [hexojs/site][]. + +### Workflow + +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 +$ git clone https://github.com/<username>/site.git +$ cd site +$ npm install +``` + +3. Start editing the documentation. You can start the server for live previewing. + +```bash +$ hexo server +``` + +4. Push the branch. +5. Create a pull request and describe the change. + +### Translating + +#### Contribute translations + +[![Crowdin](https://badges.crowdin.net/hexo/localized.svg)](https://crowdin.com/project/hexo) + +Now we use the [Crowdin](https://crowdin.com/project/hexo) platform for translation, where anyone can contribute translations and vote for translations without manual git operations. + +#### Add a new language + +1. Submit a new issue to let us know. The members with access to the [Crowdin Project](https://crowdin.com/project/hexo) add the language in settings. +1. After adding language in Crowdin, anyone can contribute translations on it. +1. Add the new language to [`source/_data/language.yml`](https://github.com/hexojs/site/blob/master/source/_data/languages.yml). +1. Copy `en.yml` in [`themes/navy/languages`](https://github.com/hexojs/site/tree/master/themes/navy/languages) and rename it to the language name (all lower case). + +## Reporting Issues + +When you encounter some problems when using Hexo, you can find the solutions in [Troubleshooting](troubleshooting.html) or ask me on [GitHub](https://github.com/hexojs/hexo/issues) or [Google Group](https://groups.google.com/group/hexo). If you can't find the answer, please report it on GitHub. + +1. Represent the problem in [debug mode](commands.html#Debug_mode). +2. Follow the steps from the issue template to provide a debug message and version when submitting a new issue at GitHub. + +[hexojs/hexo]: https://github.com/hexojs/hexo +[hexojs/site]: https://github.com/hexojs/site diff --git a/source/tr/docs/data-files.md b/source/tr/docs/data-files.md new file mode 100644 index 0000000000..e9474aab1a --- /dev/null +++ b/source/tr/docs/data-files.md @@ -0,0 +1,31 @@ +--- +title: Data Files +--- + +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**. This feature loads YAML or JSON files in `source/_data` folder so you can use them in your site. + +{% youtube CN31plHbI-w %} + +For example, add `menu.yml` in `source/_data` folder. + +```yaml +Home: / +Gallery: /gallery/ +Archives: /archives/ +``` + +And you can use them in templates: + +``` +<% for (var link in site.data.menu) { %> + <a href="<%= site.data.menu[link] %>"> <%= link %> </a> +<% } %> +``` + +render like this : + +``` +<a href="/"> Home </a> +<a href="/gallery/"> Gallery </a> +<a href="/archives/"> Archives </a> +``` diff --git a/source/tr/docs/front-matter.md b/source/tr/docs/front-matter.md new file mode 100644 index 0000000000..276b058c4a --- /dev/null +++ b/source/tr/docs/front-matter.md @@ -0,0 +1,75 @@ +--- +title: Front-matter +--- + +{% youtube pfD6FCZdW4Q %} + +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 +--- +title: Hello World +date: 2013/7/13 20:46:25 +--- +``` + +**JSON** + +```json +"title": "Hello World", +"date": "2013/7/13 20:46:25" +;;; +``` + +### Settings & Their Default Values + +| Setting | Description | Default | +| ----------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `layout` | Layout | [`config.default_layout`](/docs/configuration#Writing) | +| `title` | Title | Filename (posts only) | +| `date` | Published date | File created date | +| `updated` | Updated date | File updated date | +| `comments` | Enables comment feature for the post | `true` | +| `tags` | Tags (Not available for pages) | | +| `categories` | Categories (Not available for pages) | | +| `permalink` | Overrides the default permalink of the post. Permalink should end with `/` or `.html` | `null` | +| `excerpt` | Page excerpt in plain text. Use [this plugin](/docs/tag-plugins#Post-Excerpt) to format the text | | +| `disableNunjucks` | Disable rendering of Nunjucks tag `{{ }}`/`{% %}` and [tag plugins](/docs/tag-plugins) when enabled | false | +| `lang` | Set the language to override [auto-detection](/docs/internationalization#Path) | Inherited from `_config.yml` | +| `published` | Whether the post should be published | For posts under `_posts`, it is `true`, and for posts under `_draft`, it is `false` | + +#### Layout + +The default layout is `post`, in accordance with the value of [`default_layout`](/docs/configuration#Writing) setting in `_config.yml`. When the layout is disabled (`layout: false`) in an article, it will not be processed with a theme. However, it will still be rendered by any available renderer: if an article is written in Markdown and a Markdown renderer (like the default [hexo-renderer-marked](https://github.com/hexojs/hexo-renderer-marked)) is installed, it will be rendered to HTML. + +[Tag plugins](/docs/tag-plugins) are always processed regardless of layout, unless disabled by the `disableNunjucks` setting or [renderer](/api/renderer#Disable-Nunjucks-tags). + +#### Categories & 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. + +**Example** + +```yaml +categories: + - Sports + - Baseball +tags: + - Injury + - Fight + - Shocking +``` + +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: + - [Sports, Baseball] + - [MLB, American League, Boston Red Sox] + - [MLB, American League, New York Yankees] + - Rivalries +``` diff --git a/source/tr/docs/generating.md b/source/tr/docs/generating.md new file mode 100644 index 0000000000..2cd48f4208 --- /dev/null +++ b/source/tr/docs/generating.md @@ -0,0 +1,28 @@ +--- +title: Generating +--- + +Generating static files with Hexo is quite easy and fast. + +```bash +$ hexo generate +``` + +{% youtube viEJQPVCoLU %} + +### Watch for File Changes + +Hexo can watch for file changes and regenerate files immediately. Hexo will compare the SHA1 checksum of your files and only write if file changes are detected. + +```bash +$ hexo generate --watch +``` + +### Deploy After Generating + +To deploy after generating, you can run one of the following commands. There is no difference between the two. + +```bash +$ hexo generate --deploy +$ hexo deploy --generate +``` diff --git a/source/tr/docs/github-pages.md b/source/tr/docs/github-pages.md new file mode 100644 index 0000000000..01491e3cef --- /dev/null +++ b/source/tr/docs/github-pages.md @@ -0,0 +1,111 @@ +--- +title: GitHub Pages +--- + +In this tutorial, we use [GitHub Actions](https://docs.github.com/en/actions) to deploy GitHub Pages. It works in both public and private repositories. Skip to the [One-command deployment](#One-command-deployment) section if you prefer not to upload your source folder to GitHub. + +1. Create a repo named <b>_username_.github.io</b>, where username is your username on GitHub. 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. The default branch is usually **main**, older repositories may use **master** branch. + +- To push `main` branch to GitHub: + + ``` + $ git push -u origin main + ``` + +- The `public/` folder is not (and should not be) uploaded by default, make sure the `.gitignore` file contains `public/` line. The folder structure should be roughly similar to [this repo](https://github.com/hexojs/hexo-starter). + +3. 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., `v20.y.z`) +4. In your GitHub repo's setting, navigate to **Settings** > **Pages** > **Source**. Change the source to **GitHub Actions** and save. +5. Create `.github/workflows/pages.yml` in your repo with the following contents (substituting `20` to the major version of Node.js that you noted in previous step): + +```yml .github/workflows/pages.yml +name: Pages + +on: + push: + branches: + - main # default branch + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + # If your repository depends on submodule, please see: https://github.com/actions/checkout + submodules: recursive + - name: Use Node.js 20 + uses: actions/setup-node@v4 + with: + # Examples: 20, 18.19, >=16.20.2, lts/Iron, lts/Hydrogen, *, latest, current, node + # Ref: https://github.com/actions/setup-node#supported-version-syntax + node-version: "20" + - name: Cache NPM dependencies + uses: actions/cache@v4 + with: + path: node_modules + key: ${{ runner.OS }}-npm-cache + restore-keys: | + ${{ runner.OS }}-npm-cache + - name: Install Dependencies + run: npm install + - name: Build + run: npm run build + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./public + deploy: + needs: build + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 +``` + +6. Once the deployment is finished, check the webpage at _username_.github.io. + +Note - if you specify a custom domain name with a `CNAME`, you need to add the `CNAME` file to the `source/` folder. [More info](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 + +If you prefer to have a project page on GitHub: + +1. Navigate to your repo on GitHub. Go to the **Settings** tab. Change the **Repository name** so your blog is available at <b>username.github.io/_repository_</b>, **repository** can be any name, like _blog_ or _hexo_. +2. Edit your **\_config.yml**, change the `url:` value to <b>https://_username_.github.io/_repository_</b>. +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 + +The following instruction is adapted from [one-command deployment](/docs/one-command-deployment) page. + +1. Install [hexo-deployer-git](https://github.com/hexojs/hexo-deployer-git). +2. Add the following configurations to **\_config.yml**, (remove existing lines if any). + +```yml +deploy: + type: git + repo: https://github.com/<username>/<project> + # example, https://github.com/hexojs/hexojs.github.io + branch: gh-pages +``` + +3. Run `hexo clean && hexo deploy`. +4. Check the webpage at _username_.github.io. + +## Useful links + +- [GitHub Pages](https://docs.github.com/en/pages) +- [Publishing with a custom GitHub Actions workflow](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/tr/docs/gitlab-pages.md b/source/tr/docs/gitlab-pages.md new file mode 100644 index 0000000000..b4d102a2ab --- /dev/null +++ b/source/tr/docs/gitlab-pages.md @@ -0,0 +1,45 @@ +--- +title: GitLab Pages +--- + +1. Create a new repository named <b>_username_.gitlab.io</b>, where username is your username on GitLab. If you have already uploaded to other repo, rename the repo instead. +2. Enable Shared Runners via **Settings** > **CI/CD** > **Runners** > **Enable shared runners for this project**. +3. Push the files of your Hexo folder to the repository. The `public/` folder is not (and should not be) uploaded by default, make sure the `.gitignore` file contains `public/` line. The folder structure should be roughly similar to [this repo](https://gitlab.com/pages/hexo). +4. Check what version of Node.js you are using on your local machine with `node --version`. Make a note of the major version (e.g., `v16.y.z`) +5. Add `.gitlab-ci.yml` file to the root folder of your repo (alongside \_config.yml & package.json) with the following content (replacing `16` with the major version of Node.js you noted in previous step): + +```yml +image: node:16-alpine +cache: + paths: + - node_modules/ + +before_script: + - npm install hexo-cli -g + - npm install + +pages: + script: + - npm run build + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH +``` + +6. _username_.gitlab.io should be up and running, once GitLab CI finishes the deployment job, +7. (Optional) If you wish to inspect the generated site assets (html, css, js, etc), they can be found in the [job artifact](https://docs.gitlab.com/ee/ci/jobs/job_artifacts.html). + +## Project page + +If you prefer to have a project page on GitLab: + +1. Go to **Settings** > **General** > **Advanced** > **Change path**. Change the value to a name, so the website is available at <b>username.gitlab.io/_repository_</b>. It can be any name, like _blog_ or _hexo_. +2. Edit **\_config.yml**, change the `url:` value to `https://username.gitlab.io/repository`. +3. Commit and push. + +## Useful links + +- [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/) +- [GitLab CI Docs](https://docs.gitlab.com/ee/ci/yaml/) diff --git a/source/tr/docs/helpers.md b/source/tr/docs/helpers.md new file mode 100644 index 0000000000..6573427eca --- /dev/null +++ b/source/tr/docs/helpers.md @@ -0,0 +1,981 @@ +--- +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 + +### url_for + +Returns a URL with the root path prefixed. Output is encoded automatically. + +```js +<%- url_for(path, [option]) %> +``` + +| 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 + +Returns the relative URL from `from` to `to`. + +```js +<%- 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 + +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, [options]) %> +``` + +| Option | Description | Default | +| ------ | ----------------- | ------- | +| `s` | Output image size | 80 | +| `d` | Default image | | +| `f` | Force default | | +| `r` | Rating | | + +More info: [Gravatar](https://en.gravatar.com/site/implement/images/) + +**Examples:** + +```js +<%- gravatar('a@abc.com') %> +// https://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787 + +<%- gravatar('a@abc.com', 40) %> +// https://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787?s=40 + +<%- gravatar('a@abc.com' {s: 40, d: 'https://via.placeholder.com/150'}) %> +// https://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787?s=40&d=https%3A%2F%2Fvia.placeholder.com%2F150 +``` + +## HTML Tags + +### css + +Loads CSS files. `path` can be a string, an array, an object or an array of objects. [`/<root>/`](/docs/configuration#URL) value is prepended while `.css` extension is appended to the `path` automatically. Use object type for custom attributes. + +```js +<%- css(path, ...) %> +``` + +**Examples:** + +```js +<%- css('style.css') %> +// <link rel="stylesheet" href="/style.css"> + +<%- css(['style.css', 'screen.css']) %> +// <link rel="stylesheet" href="/style.css"> +// <link rel="stylesheet" href="/screen.css"> + +<%- css({ href: 'style.css', integrity: 'foo' }) %> +// <link rel="stylesheet" href="/style.css" integrity="foo"> + +<%- css([{ href: 'style.css', integrity: 'foo' }, { href: 'screen.css', integrity: 'bar' }]) %> +// <link rel="stylesheet" href="/style.css" integrity="foo"> +// <link rel="stylesheet" href="/screen.css" integrity="bar"> +``` + +### js + +Loads JavaScript files. `path` can be a string, an array, an object or an array of objects. [`/<root>/`](/docs/configuration#URL) value is prepended while `.js` extension is appended to the `path` automatically. Use object type for custom attributes. + +```js +<%- js(path, ...) %> +``` + +**Examples:** + +```js +<%- js('script.js') %> +// <script src="/script.js"></script> + +<%- js(['script.js', 'gallery.js']) %> +// <script src="/script.js"></script> +// <script src="/gallery.js"></script> + +<%- js({ src: 'script.js', integrity: 'foo', async: true }) %> +// <script src="/script.js" integrity="foo" async></script> + +<%- js([{ src: 'script.js', integrity: 'foo' }, { src: 'gallery.js', integrity: 'bar' }]) %> +// <script src="/script.js" integrity="foo"></script> +// <script src="/gallery.js" integrity="bar"></script> +``` + +### link_to + +Inserts a link. + +```js +<%- link_to(path, [text], [options]) %> +``` + +| Option | Description | Default | +| ---------- | --------------------------- | ------- | +| `external` | Opens the link in a new tab | false | +| `class` | Class name | | +| `id` | ID | | + +**Examples:** + +```js +<%- link_to('http://www.google.com') %> +// <a href="http://www.google.com" title="http://www.google.com">http://www.google.com</a> + +<%- link_to('http://www.google.com', 'Google') %> +// <a href="http://www.google.com" title="Google">Google</a> + +<%- link_to('http://www.google.com', 'Google', {external: true}) %> +// <a href="http://www.google.com" title="Google" target="_blank" rel="noopener">Google</a> +``` + +### mail_to + +Inserts a mail link. + +```js +<%- mail_to(path, [text], [options]) %> +``` + +| Option | Description | +| --------- | ------------ | +| `class` | Class name | +| `id` | ID | +| `subject` | Mail subject | +| `cc` | CC | +| `bcc` | BCC | +| `body` | Mail content | + +**Examples:** + +```js +<%- mail_to('a@abc.com') %> +// <a href="mailto:a@abc.com" title="a@abc.com">a@abc.com</a> + +<%- mail_to('a@abc.com', 'Email') %> +// <a href="mailto:a@abc.com" title="Email">Email</a> +``` + +### image_tag + +Inserts an image. + +```js +<%- image_tag(path, [options]) %> +``` + +| Option | Description | +| -------- | ----------------------------- | +| `alt` | Alternative text of the image | +| `class` | Class name | +| `id` | ID | +| `width` | Image width | +| `height` | Image height | + +### favicon_tag + +Inserts a favicon. + +```js +<%- favicon_tag(path) %> +``` + +### feed_tag + +Inserts a feed link. + +```js +<%- feed_tag(path, [options]) %> +``` + +| Option | Description | Default | +| ------- | ----------- | -------------- | +| `title` | Feed title | `config.title` | +| `type` | Feed type | | + +**Examples:** + +```js +<%- feed_tag('atom.xml') %> +// <link rel="alternate" href="/atom.xml" title="Hexo" type="application/atom+xml"> + +<%- feed_tag('rss.xml', { title: 'RSS Feed', type: 'rss' }) %> +// <link rel="alternate" href="/atom.xml" title="RSS Feed" type="application/atom+xml"> + +/* Defaults to hexo-generator-feed's config if no argument */ +<%- feed_tag() %> +// <link rel="alternate" href="/atom.xml" title="Hexo" type="application/atom+xml"> +``` + +## Conditional Tags + +### is_current + +Check whether `path` matches the URL of the current page. Use `strict` options to enable strict matching. + +```js +<%- is_current(path, [strict]) %> +``` + +### is_home + +Check whether the current page is home page. + +```js +<%- 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 +<%- is_page() %> +``` + +### is_archive + +Check whether the current page is an archive page. + +```js +<%- is_archive() %> +``` + +### is_year + +Check whether the current page is a yearly archive page. + +```js +<%- is_year() %> +``` + +### is_month + +Check whether the current page is a monthly archive page. + +```js +<%- is_month() %> +``` + +### 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() %> +<%- is_category('hobby') %> +``` + +### 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() %> +<%- is_tag('hobby') %> +``` + +## String Manipulation + +### trim + +Removes prefixing and trailing spaces of a string. + +```js +<%- trim(string) %> +``` + +### strip_html + +Sanitizes all HTML tags in a string. + +```js +<%- strip_html(string) %> +``` + +**Examples:** + +```js +<%- strip_html('It\'s not <b>important</b> anymore!') %> +// It's not important anymore! +``` + +### titlecase + +Transforms a string into proper title caps. + +```js +<%- titlecase(string) %> +``` + +**Examples:** + +```js +<%- titlecase('this is an apple') %> +# This is an Apple +``` + +### markdown + +Renders a string with Markdown. + +```js +<%- markdown(str) %> +``` + +**Examples:** + +```js +<%- markdown('make me **strong**') %> +// make me <strong>strong</strong> +``` + +### render + +Renders a string. + +```js +<%- render(str, engine, [options]) %> +``` + +**Examples:** + +```js +<%- render('p(class="example") Test', 'pug'); %> +// <p class="example">Test</p> +``` + +See [Rendering](https://hexo.io/api/rendering) for more details. + +### word_wrap + +Wraps text into lines no longer than `length`. `length` is 80 by default. + +```js +<%- word_wrap(str, [length]) %> +``` + +**Examples:** + +```js +<%- word_wrap('Once upon a time', 8) %> +// Once upon\n a time +``` + +### truncate + +Truncates text after certain `length`. Default is 30 characters. + +```js +<%- truncate(text, [options]) %> +``` + +**Examples:** + +```js +<%- truncate('Once upon a time in a world far far away', {length: 17}) %> +// Once upon a ti... + +<%- 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 + +Escapes HTML entities in a string. + +```js +<%- escape_html(str) %> +``` + +**Examples:** + +```js +<%- escape_html('<p>Hello "world".</p>') %> +// <p>Hello "world".</p> +``` + +## Templates + +### partial + +Loads other template files. You can define local variables in `locals`. + +```js +<%- partial(layout, [locals], [options]) %> +``` + +| Option | Description | Default | +| ------- | ------------------------------------------------------------------------ | ------- | +| `cache` | Cache contents (Use fragment cache) | `false` | +| `only` | Strict local variables. Only use variables set in `locals` in templates. | `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(){ + return '<header></header>'; +}) %> +``` + +## Date & Time + +### date + +Inserts formatted date. `date` can be unix time, ISO string, date object, or [Moment.js][] object. `format` is `date_format` setting by default. + +```js +<%- date(date, [format]) %> +``` + +**Examples:** + +```js +<%- date(Date.now()) %> +// 2013-01-01 + +<%- date(Date.now(), 'YYYY/M/D') %> +// Jan 1 2013 +``` + +### date_xml + +Inserts date in XML format. `date` can be unix time, ISO string, date object, or [Moment.js][] object. + +```js +<%- date_xml(date) %> +``` + +**Examples:** + +```js +<%- date_xml(Date.now()) %> +// 2013-01-01T00:00:00.000Z +``` + +### time + +Inserts formatted time. `date` can be unix time, ISO string, date object, or [Moment.js][] object. `format` is `time_format` setting by default. + +```js +<%- time(date, [format]) %> +``` + +**Examples:** + +```js +<%- time(Date.now()) %> +// 13:05:12 + +<%- time(Date.now(), 'h:mm:ss a') %> +// 1:05:12 pm +``` + +### full_date + +Inserts formatted date and time. `date` can be unix time, ISO string, date object, or [Moment.js][] object. `format` is `date_format + time_format` setting by default. + +```js +<%- full_date(date, [format]) %> +``` + +**Examples:** + +```js +<%- full_date(new Date()) %> +// Jan 1, 2013 0:00:00 + +<%- full_date(new Date(), 'dddd, MMMM Do YYYY, h:mm:ss a') %> +// Tuesday, January 1st 2013, 12:00:00 am +``` + +### relative_date + +Inserts relative time from now. `date` can be unix time, ISO string, date object, or [Moment.js][] object. + +```js +<%- relative_date(date) %> +``` + +**Examples:** + +```js +<%- relative_date(new Date()) %> +// a few seconds ago + +<%- relative_date(new Date(1000000000000)) %> +// 22 years ago +``` + +### 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. + +```js +<%- time_tag(date, [format]) %> +``` + +**Examples:** + +```js +<%- time_tag(new Date()) %> +// <time datetime="2024-01-22T06:35:31.108Z">2024-01-22</time> + +<%- time_tag(new Date(), 'MMM-D-YYYY') %> +// <time datetime="2024-01-22T06:35:31.108Z">Jan-22-2024</time> +``` + +### moment + +[Moment.js][] library. + +## List + +### list_categories + +Inserts a list of all categories. + +```js +<%- list_categories([options]) %> +``` + +| Option | Description | Default | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `orderby` | Order of categories | name | +| `order` | Sort of order. `1`, `asc` for ascending; `-1`, `desc` for descending | 1 | +| `show_count` | Display the number of posts for each category | true | +| `style` | Style to display the category list. `list` displays categories in an unordered list. Use `false` or any other value to disable it. | list | +| `separator` | Separator between categories. (Only works if `style` is not `list`) | , | +| `depth` | Levels of categories to be displayed. `0` displays all categories and child categories; `-1` is similar to `0` but displayed in flat; `1` displays only top level categories. | 0 | +| `class` | Class name of category list. | category | +| `transform` | The function that changes the display of category name. | | +| `suffix` | Add a suffix to link. | None | + +**Examples:** + +```js +<%- list_categories(post.categories, { + class: 'post-category', + transform(str) { + return titlecase(str); + } +}) %> + +<%- list_categories(post.categories, { + class: 'post-category', + transform(str) { + return str.toUpperCase(); + } +}) %> +``` + +### list_tags + +Inserts a list of all tags. + +```js +<%- list_tags([options]) %> +``` + +| Option | Description | Default | +| ------------ | ----------------------------------------------------------------------------------------------------------------------- | ------- | +| `orderby` | Order of tags | name | +| `order` | Sort of order. `1`, `asc` for ascending; `-1`, `desc` for descending | 1 | +| `show_count` | Display the number of posts for each tag | true | +| `style` | Style to display the tag list. `list` displays tags in an unordered list. Use `false` or any other value to disable it. | list | +| `separator` | Separator between categories. (Only works if `style` is not `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` | The number of tags to display (0 = unlimited) | 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) | +| `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) | + +Examples: + +```ejs +<%- list_tags(site.tags, {class: 'classtest', style: false, separator: ' | '}) %> +<%- list_tags(site.tags, {class: 'classtest', style: 'list'}) %> +<%- list_tags(site.tags, {class: {ul: 'ululul', li: 'lilili', a: 'aaa', count: 'ccc'}, style: false, separator: ' | '}) %> +<%- list_tags(site.tags, {class: {ul: 'ululul', li: 'lilili', a: 'aaa', count: 'ccc'}, style: 'list'}) %> +``` + +### list_archives + +Inserts a list of archives. + +```js +<%- list_archives([options]) %> +``` + +| Option | Description | Default | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | --------- | +| `type` | Type. This value can be `yearly` or `monthly`. | monthly | +| `order` | Sort of order. `1`, `asc` for ascending; `-1`, `desc` for descending | 1 | +| `show_count` | Display the number of posts for each archive | true | +| `format` | Date format | MMMM YYYY | +| `style` | Style to display the archive list. `list` displays archives in an unordered list. Use `false` or any other value to disable it. | list | +| `separator` | Separator between archives. (Only works if `style` is not `list`) | , | +| `class` | Class name of archive list. | archive | +| `transform` | The function that changes the display of archive name. See examples in [list_categories](#list-categories). | | + +### list_posts + +Inserts a list of posts. + +```js +<%- list_posts([options]) %> +``` + +| Option | Description | Default | +| ----------- | ------------------------------------------------------------------------------------------------------------------------- | ------- | +| `orderby` | Order of posts | date | +| `order` | Sort of order. `1`, `asc` for ascending; `-1`, `desc` for descending | 1 | +| `style` | Style to display the post list. `list` displays posts in an unordered list. Use `false` or any other value to disable it. | list | +| `separator` | Separator between posts. (Only works if `style` is not `list`) | , | +| `class` | Class name of post list. | post | +| `amount` | The number of posts to display (0 = unlimited) | 6 | +| `transform` | The function that changes the display of post name. See examples in [list_categories](#list-categories). | | + +### tagcloud + +Inserts a tag cloud. + +```js +<%- tagcloud([tags], [options]) %> +``` + +| Option | Description | Default | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| `min_font` | Minimum font size | 10 | +| `max_font` | Maximum font size | 20 | +| `unit` | Unit of font size | px | +| `amount` | Total amount of tags | unlimited | +| `orderby` | Order of tags | name | +| `order` | Sort order. `1`, `asc` as ascending; `-1`, `desc` as descending | 1 | +| `color` | Colorizes the tag cloud | false | +| `start_color` | Start color. You can use hex (`#b700ff`), rgba (`rgba(183, 0, 255, 1)`), hsla (`hsla(283, 100%, 50%, 1)`) or [color keywords][]. This option only works when `color` is true. | | +| `end_color` | End color. You can use hex (`#b700ff`), rgba (`rgba(183, 0, 255, 1)`), hsla (`hsla(283, 100%, 50%, 1)`) or [color keywords][]. This option only works when `color` is true. | | +| `class` | Class name prefix of tags | | +| `level` | The number of different class names. This option only works when `class` is set. | 10 | +| `show_count` (+6.3.0) | Display the number of posts for each tag | false | +| `count_class` (+6.3.0) | Class name of tag count | count | + +**Examples:** + +```js +// Default options +<%- tagcloud() %> + +// Limit number of tags to 30 +<%- tagcloud({amount: 30}) %> +``` + +## Miscellaneous + +### paginator + +Inserts a paginator. + +```js +<%- paginator(options) %> +``` + +| Option | Description | Default | +| -------------------------- | ---------------------------------------------------------------------------------- | ------------- | +| `base` | Base URL | / | +| `format` | URL format | page/%d/ | +| `total` | The number of pages | 1 | +| `current` | Current page number | 0 | +| `prev_text` | The link text of previous page. Works only if `prev_next` is set to true. | Prev | +| `next_text` | The link text of next page. Works only if `prev_next` is set to true. | Next | +| `space` | The space text | &hellp; | +| `prev_next` | Display previous and next links | 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` | Display all pages. If this is set to true, `end_size` and `mid_size` will not work | false | +| `escape` | Escape HTML tags | true | +| `page_class` (+6.3.0) | Page class name | `page-number` | +| `current_class` (+6.3.0) | Current page class name | `current` | +| `space_class` (+6.3.0) | Space class name | `space` | +| `prev_class` (+6.3.0) | Previous page class name | `extend prev` | +| `next_class` (+6.3.0) | Next page class name | `extend next` | +| `force_prev_next` (+6.3.0) | Force display previous and next links | false | + +**Examples:** + +```js +<%- paginator({ + prev_text: '<', + next_text: '>' +}) %> +``` + +```html +<!-- Rendered as --> +<a href="/1/"><</a> +<a href="/1/">1</a> +2 +<a href="/3/">3</a> +<a href="/3/">></a> +``` + +```js +<%- paginator({ + prev_text: '<i class="fa fa-angle-left"></i>', + next_text: '<i class="fa fa-angle-right"></i>', + escape: false +}) %> +``` + +```html +<!-- Rendered as --> +<a href="/1/"><i class="fa fa-angle-left"></i></a> +<a href="/1/">1</a> +2 +<a href="/3/">3</a> +<a href="/3/"><i class="fa fa-angle-right"></i></a> +``` + +### search_form + +Inserts a Google search form. + +```js +<%- search_form(options) %> +``` + +| Option | Description | Default | +| -------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `class` | The class name of form | search-form | +| `text` | Search hint word | Search | +| `button` | Display 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 + +Formats a number. + +```js +<%- number_format(number, [options]) %> +``` + +| Option | Description | Default | +| ----------- | --------------------------------------------------------------------------- | ------- | +| `precision` | The precision of number. The value can be `false` or a nonnegative integer. | false | +| `delimiter` | The thousands delimiter | , | +| `separator` | The separator between the fractional and integer digits. | . | + +**Examples:** + +```js +<%- number_format(12345.67, {precision: 1}) %> +// 12,345.68 + +<%- number_format(12345.67, {precision: 4}) %> +// 12,345.6700 + +<%- number_format(12345.67, {precision: 0}) %> +// 12,345 + +<%- number_format(12345.67, {delimiter: ''}) %> +// 12345.67 + +<%- number_format(12345.67, {separator: '/'}) %> +// 12,345/67 +``` + +### meta_generator + +Inserts [generator tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta). + +```js +<%- meta_generator() %> +``` + +**Examples:** + +```js +<%- meta_generator() %> +// <meta name="generator" content="Hexo 4.0.0"> +``` + +### open_graph + +Inserts [Open Graph][] data. + +```js +<%- open_graph([options]) %> +``` + +| Option | Description | Default | +| --------------- | ---------------------------------------------------- | ------------------------------------------------------- | +| `title` | Page title (`og:title`) | `page.title` | +| `type` | Page type (`og:type`) | article(post page)<br>website(non-post page) | +| `url` | Page URL (`og:url`) | `url` | +| `image` | Page images (`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` | Site name (`og:site_name`) | `config.title` | +| `description` | Page description (`og:description`) | Page excerpt or first 200 characters of the content | +| `twitter_card` | Twitter card type (`twitter:card`) | summary | +| `twitter_id` | Twitter ID (`twitter:creator`) | | +| `twitter_site` | Twitter Site (`twitter:site`) | | +| `twitter_image` | Twitter Image (`twitter:image`) | | +| `google_plus` | Google+ profile link | | +| `fb_admins` | Facebook admin ID | | +| `fb_app_id` | Facebook App ID | | + +### toc + +Parses all heading tags (h1~h6) in the content and inserts a table of contents. + +```js +<%- toc(str, [options]) %> +``` + +| Option | Description | Default | +| ----------------------- | ---------------------------------------- | ----------------- | +| `class` | Class name | `toc` | +| `class_item` (+6.3.0) | Class name of item | `${class}-item` | +| `class_link` (+6.3.0) | Class name of link | `${class}-link` | +| `class_text` (+6.3.0) | Class name of text | `${class}-text` | +| `class_child` (+6.3.0) | Class name of child | `${class}-child` | +| `class_number` (+6.3.0) | Class name of number | `${class}-number` | +| `class_level` (+6.3.0) | Class name prefix of level | `${class}-level` | +| `list_number` | Displays list number | true | +| `max_depth` | Maximum heading depth of generated toc | 6 | +| `min_depth` | Minimum heading depth of generated toc | 1 | +| `max_items` (+7.3.0) | Maximum number of items in generated toc | `Infinity` | + +**Examples:** + +```js +<%- toc(page.content) %> +``` + +#### data-toc-unnumbered (+6.1.0) + +Headings with attribute `data-toc-unnumbered="true"` will be marked as unnumbered (list number will not be displayed). + +{% note warn "Warning!" %} +For using `data-toc-unnumbered="true"`, the renderer must have the option to add CSS classes. + +Please see the below PRs. + +- https://github.com/hexojs/hexo/pull/4871 +- https://github.com/hexojs/hexo-util/pull/269 +- https://github.com/hexojs/hexo-renderer-markdown-it/pull/174 + {% endnote %} + +[color keywords]: http://www.w3.org/TR/css3-color/#svg-color +[Moment.js]: http://momentjs.com/ +[Open Graph]: http://ogp.me/ diff --git a/source/tr/docs/index.md b/source/tr/docs/index.md new file mode 100644 index 0000000000..7c46e30c63 --- /dev/null +++ b/source/tr/docs/index.md @@ -0,0 +1,111 @@ +--- +title: Documentation +--- + +Welcome to the Hexo documentation. If you encounter any problems when using Hexo, have a look at the [troubleshooting guide](troubleshooting.html), raise an issue on [GitHub](https://github.com/hexojs/hexo/issues) or start a topic on the [Google Group](https://groups.google.com/group/hexo). + +## What is Hexo? + +Hexo is a fast, simple and powerful blog framework. You write posts in [Markdown](http://daringfireball.net/projects/markdown/) (or other markup languages) and Hexo generates static files with a beautiful theme in seconds. + +## Installation + +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 ARted4RniaU %} + +### Requirements + +Installing Hexo is quite easy and only requires the following beforehand: + +- [Node.js](http://nodejs.org/) (See [Required Node.js version](#Required-Node-js-version)) +- [Git](http://git-scm.com/) + +If your computer already has these, congratulations! You can skip to the [Hexo installation](#Install-Hexo) step. + +If not, please follow the following instructions to install all the requirements. + +### Install Git + +- Windows: Download & install [git](https://git-scm.com/download/win). +- Mac: Install it with [Homebrew](https://brew.sh/), [MacPorts](http://www.macports.org/) or [installer](http://sourceforge.net/projects/git-osx-installer/). +- Linux (Ubuntu, Debian): `sudo apt-get install git-core` +- Linux (Fedora, Red Hat, CentOS): `sudo yum install git-core` + +{% note warn For Mac users %} +You may encounter some problems when compiling. Please install Xcode from App Store first. After Xcode is installed, open Xcode and go to **Preferences -> Download -> Command Line Tools -> Install** to install command line tools. +{% endnote %} + +### Install Node.js + +Node.js provides [official installer](https://nodejs.org/en/download/) for most platforms. + +Alternative installation methods: + +- Windows: Install it with [nvs](https://github.com/jasongin/nvs/) (recommended) or [nvm](https://github.com/nvm-sh/nvm). +- Mac: Install it with [Homebrew](https://brew.sh/) or [MacPorts](http://www.macports.org/). +- Linux (DEB/RPM-based): Install it with [NodeSource](https://github.com/nodesource/distributions). +- Others: Install it through respective package manager. Refer to [the guide](https://nodejs.org/en/download/package-manager/) provided by Node.js. + +nvs is also recommended for Mac and Linux to avoid possible permission issue. + +{% note info Windows %} +If you use the official installer, make sure **Add to PATH** is checked (it's checked by default). +{% endnote %} + +{% note warn Mac / Linux %} +If you encounter `EACCES` permission error when trying to install Hexo, please follow [the workaround](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) provided by npmjs; overriding with root/sudo is highly discouraged. +{% endnote %} + +{% note info Linux %} +If you installed Node.js using Snap, you may need to manually run `npm install` in the target folder when [initializing](/docs/commands#init) a blog. +{% endnote %} + +### Install Hexo + +Once all the requirements are installed, you can install Hexo with npm: + +```bash +$ npm install -g hexo-cli +``` + +### Advanced installation and usage + +Advanced users may prefer to install and use `hexo` package instead. + +```bash +$ npm install hexo +``` + +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>` + +### Required Node.js version + +If you are stuck with older Node.js, you can consider installing a past version of Hexo. + +Please note we do not provide bugfixes to past versions of Hexo. + +We highly recommend to always install the [latest version](https://www.npmjs.com/package/hexo?activeTab=versions) of Hexo and the [recommended version](#Requirements) of Node.js, whenever possible. + +| Hexo version | Minimum (Node.js version) | Less than (Node.js version) | +| ------------ | ------------------------- | --------------------------- | +| 8.0+ | 20.19.0 | latest | +| 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/tr/docs/internationalization.md b/source/tr/docs/internationalization.md new file mode 100644 index 0000000000..21df389627 --- /dev/null +++ b/source/tr/docs/internationalization.md @@ -0,0 +1,57 @@ +--- +title: Internationalization (i18n) +--- + +You can use internationalization to present your site in different languages. The default language is set by modifying the `language` setting in `_config.yml`. You can also set multiple languages and modify the order of default languages. + +```yaml +language: zh-tw + +language: +- zh-tw +- en +``` + +### Language Files + +Language files can be YAML or JSON files. You should put them into the `languages` folder in the theme. There is support for the [printf format](https://github.com/alexei/sprintf.js) in language files. + +### Templates + +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: + title: Home + add: Add + video: + zero: No videos + one: One video + other: %d videos +``` + +```js +<%= __('index.title') %> +// Home + +<%= _p('index.video', 3) %> +// 3 videos +``` + +### Path + +You can set the language of pages in front-matter, or modify the `i18n_dir` setting in `_config.yml` to enable automatic detection by Hexo. + +```yaml +i18n_dir: :lang +``` + +The default value of `i18n_dir` setting is `:lang`, which means that Hexo will detect the language within the first segment of URL. For example: + +```plain +/index.html => en +/archives/index.html => en +/zh-tw/index.html => zh-tw +``` + +The string will only be served as a language when the language file exists. So `archives` in `/archives/index.html` (example 2) will not get served as a language. diff --git a/source/tr/docs/migration.md b/source/tr/docs/migration.md new file mode 100644 index 0000000000..a240934dc1 --- /dev/null +++ b/source/tr/docs/migration.md @@ -0,0 +1,73 @@ +--- +title: Migration +--- + +## RSS + +First, install the `hexo-migrator-rss` plugin. + +```bash +$ npm install hexo-migrator-rss --save +``` + +Once the plugin is installed, run the following command to migrate all posts from RSS. `source` can be a file path or URL. + +```bash +$ hexo migrate rss <source> +``` + +## Jekyll + +Move all files in the Jekyll `_posts` folder to the `source/_posts` folder. + +Modify the `new_post_name` setting in `_config.yml`: + +```yaml +new_post_name: :year-:month-:day-:title.md +``` + +## Octopress + +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 +``` + +## WordPress + +First, install the `hexo-migrator-wordpress` plugin. + +```bash +$ npm install hexo-migrator-wordpress --save +``` + +Export your WordPress site by going to "Tools" → "Export" → "WordPress" in the WordPress dashboard (see the [WordPress support page](http://en.support.wordpress.com/export/) for more details). + +Now run: + +```bash +$ hexo migrate wordpress <source> +``` + +Where `source` is the file path or URL to the WordPress export file. + +## Joomla + +First, install the `hexo-migrator-joomla` plugin. + +```bash +$ npm install hexo-migrator-joomla --save +``` + +Export your Joomla articles using the [J2XML](http://extensions.joomla.org/extensions/migration-a-conversion/data-import-a-export/12816?qh=YToxOntpOjA7czo1OiJqMnhtbCI7fQ%3D%3D) component. + +Now run: + +```bash +$ hexo migrate joomla <source> +``` + +Where `source` is the file path or URL to the Joomla export file. diff --git a/source/tr/docs/one-command-deployment.md b/source/tr/docs/one-command-deployment.md new file mode 100644 index 0000000000..4c65599d34 --- /dev/null +++ b/source/tr/docs/one-command-deployment.md @@ -0,0 +1,252 @@ +--- +title: One-Command Deployment +--- + +Hexo provides a fast and easy deployment strategy. You only need one single command to deploy your site to your server. + +```bash +$ hexo deploy +``` + +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 +``` + +You can use multiple deployers. Hexo will execute each deployer in order. + +```yaml +deploy: + - type: git + repo: + - type: heroku + repo: +``` + +Refer to the [Plugins](https://hexo.io/plugins/) list for more deployment plugins. + +## Git + +1. Install [hexo-deployer-git][]. + +```bash +$ npm install hexo-deployer-git --save +``` + +2. Edit **\_config.yml** (with example values shown below as comments): + +```yaml +deploy: + type: git + repo: <repository url> # https://bitbucket.org/JohnSmith/johnsmith.bitbucket.io + branch: [branch] + message: [message] +``` + +| Option | Description | Default | +| --------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `repo` | URL of the target repository | | +| `branch` | Branch name. | `gh-pages` (GitHub)<br>`coding-pages` (Coding.net)<br>`master` (others) | +| `message` | Customize commit message. | `Site updated: {% raw %}{{ now('YYYY-MM-DD HH:mm:ss') }}{% endraw %}` | +| `token` | Optional token value to authenticate with the repo. Prefix with `$` to read token from environment variable | | + +3. Deploy your site `hexo clean && hexo deploy`. + +- You will be prompted with username and password of the target repository, unless you authenticate with a token or ssh key. +- hexo-deployer-git does not store your username and password. Use [git-credential-cache](https://git-scm.com/docs/git-credential-cache) to store them temporarily. + +4. Navigate to your repository settings and change the "Pages" branch to `gh-pages` (or the branch specified in your config). The deployed site should be live on the link shown on the "Pages" setting. + +## Heroku + +Install [hexo-deployer-heroku][]. + +```bash +$ npm install hexo-deployer-heroku --save +``` + +Edit settings. + +```yaml +deploy: + type: heroku + repo: <repository url> + message: [message] +``` + +| Option | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------- | +| `repo`, `repository` | Heroku repository URL | +| `message` | Customize commit message (Default to `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 + +Install [hexo-deployer-rsync][]. + +```bash +$ npm install hexo-deployer-rsync --save +``` + +Edit settings. + +```yaml +deploy: + type: rsync + host: <host> + user: <user> + root: <root> + port: [port] + delete: [true|false] + verbose: [true|false] + ignore_errors: [true|false] +``` + +| Option | Description | Default | +| --------------- | ------------------------------- | ------- | +| `host` | Address of remote host | | +| `user` | Username | | +| `root` | Root directory of remote host | | +| `port` | Port | 22 | +| `delete` | Delete old files on remote host | true | +| `verbose` | Display verbose messages | true | +| `ignore_errors` | Ignore errors | false | + +## FTPSync + +Install [hexo-deployer-ftpsync][]. + +```bash +$ npm install hexo-deployer-ftpsync --save +``` + +Edit settings. + +```yaml +deploy: + type: ftpsync + host: <host> + user: <user> + pass: <password> + remote: [remote] + port: [port] + clear: [true|false] + verbose: [true|false] +``` + +| Option | Description | Default | +| --------- | ------------------------------------------------------------------------ | ------- | +| `host` | Address of remote host | | +| `user` | Username | | +| `pass` | Password | | +| `remote` | Root directory of remote host | `/` | +| `port` | Port | 21 | +| `clear` | Remove all files and directories from the remote directory before upload | 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 +``` + +Edit settings. + +```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 | Description | 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) is a cloud platform that enables developers to host Jamstack websites and web services that deploy instantly, scale automatically, and require no supervision, all with zero configuration. They provide a global edge network, SSL encryption, asset compression, cache invalidation, and more. + +Step 1: Add a build script to your `package.json` file: + +```json +{ + "scripts": { + "build": "hexo generate" + } +} +``` + +Step 2: Deploy your Hexo Website to Vercel + +To deploy your Hexo app with a [Vercel for Git Integration](https://vercel.com/docs/git-integrations), make sure it has been pushed to a Git repository. + +Import the project into Vercel using the [Import Flow](https://vercel.com/import/git). During the import, you will find all relevant options preconfigured for you; however, you can choose to change any of these options, a list of which can be found [here](https://vercel.com/docs/build-step#build-&-development-settings). + +After your project has been imported, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/platform/deployments#preview), and all changes made to the [Production Branch](https://vercel.com/docs/git-integrations#production-branch) (commonly "main") will result in a [Production Deployment](https://vercel.com/docs/platform/deployments#production). + +Alternatively, you can click the deploy button below to create a new project: + +[![Deploy Vercel](https://vercel.com/button)](https://vercel.com/new/hexo) + +## Bip + +[Bip](https://bip.sh) is a commercial hosting service that provides zero downtime deployment, a global CDN, SSL, unlimited bandwidth and more for static websites. Plans are available on a pay as you go, per domain basis. + +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). + +1: Initialise your project directory + +```bash +$ bip init +``` + +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. + +2: Deploy your website + +```bash +$ hexo generate —deploy && bip deploy +``` + +After a few moments, your website will be deployed. + +## Other Methods + +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-ftpsync]: https://github.com/hexojs/hexo-deployer-ftpsync +[hexo-deployer-sftp]: https://github.com/lucascaro/hexo-deployer-sftp diff --git a/source/tr/docs/permalinks.md b/source/tr/docs/permalinks.md new file mode 100644 index 0000000000..eb0074ab7a --- /dev/null +++ b/source/tr/docs/permalinks.md @@ -0,0 +1,86 @@ +--- +title: Permalinks +--- + +You can specify the permalinks for your site in `_config.yml` or in the front-matter for each post. + +### Variables + +Besides the following variables, you can use any attributes in the permalink except `:path` and `:permalink`. + +| Variable | Description | +| ------------- | ----------------------------------------------------------------------------------- | +| `:year` | Published year of posts (4-digit) | +| `:month` | Published month of posts (2-digit) | +| `:i_month` | Published month of posts (Without leading zeros) | +| `: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) | +| `:timestamp` | Timestamp of post's published [date](./front-matter#Settings-Their-Default-Values) | +| `:title` | Filename (relative to "source/\_posts/" folder) | +| `:name` | Filename | +| `:post_title` | Post title | +| `:id` | Post ID (_not persistent across [cache reset](/docs/commands#clean)_) | +| `:category` | Categories. If the post is uncategorized, it will use the `default_category` value. | +| `:hash` | SHA1 hash of filename (same as `:title`) and date (12-hexadecimal) | + +You can define the default value of each variable in the permalink through the `permalink_defaults` setting: + +```yaml +permalink_defaults: + lang: en +``` + +### Examples + +```yaml source/_posts/hello-world.md +title: Hello World +date: 2013-07-14 17:01:34 +categories: + - foo + - bar +``` + +| Setting | Result | +| ------------------------------- | --------------------------- | +| `:year/:month/:day/:title/` | 2013/07/14/hello-world/ | +| `:year-:month-:day-:title.html` | 2013-07-14-hello-world.html | +| `:category/:title/` | foo/bar/hello-world/ | +| `:title-:hash/` | hello-world-a2c8ac003b43/ | + +```yaml source/_posts/lorem/hello-world.md +title: Hello World +date: 2013-07-14 17:01:34 +categories: + - foo + - bar +``` + +| Setting | Result | +| --------------------------- | ----------------------------- | +| `:year/:month/:day/:title/` | 2013/07/14/lorem/hello-world/ | +| `:year/:month/:day/:name/` | 2013/07/14/hello-world/ | + +### Multi-language Support + +To create a multi-language site, you can modify the `new_post_name` and `permalink` settings like this: + +```yaml +new_post_name: :lang/:title.md +permalink: :lang/:title/ +``` + +When you create a new post, the post will be saved to: + +```bash +$ hexo new "Hello World" --lang tw +# => source/_posts/tw/Hello-World.md +``` + +and the URL will be: + +```plain +http://localhost:4000/tw/hello-world/ +``` diff --git a/source/tr/docs/plugins.md b/source/tr/docs/plugins.md new file mode 100644 index 0000000000..f09842b3c1 --- /dev/null +++ b/source/tr/docs/plugins.md @@ -0,0 +1,77 @@ +--- +title: Plugins +--- + +Hexo has a powerful plugin system, which makes it easy to extend functions without modifying the source code of the core module. There are two kinds of plugins in Hexo: + +### Script + +If your plugin is relatively simple, it's recommended to use a script. All you need to do is put your JavaScript files in the `scripts` folder and Hexo will load them during initialization. + +### Plugin + +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. + +Your new folder must contain at least two files: one containing the actual JavaScript code and one `package.json` file that describes the purpose of the plugin and sets its dependencies. + +```plain +. +├── index.js +└── package.json +``` + +At the very least, you should set the `name`, `version` and `main` entries in `package.json`. For example: + +```json package.json +{ + "name": "hexo-my-plugin", + "version": "0.0.1", + "main": "index" +} +``` + +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. + +### Tools + +You can make use of the official tools provided by Hexo to accelerate development: + +- [hexo-fs][]：File IO +- [hexo-util][]：Utilities +- [hexo-i18n][]：Localization (i18n) +- [hexo-pagination][]：Generate pagination data + +### Publishing + +When your plugin is ready, you may consider publishing it to the [plugin list](/plugins) to invite other people to start using it. Publishing your own plugins is very similar to [updating documentation](contributing.html#Updating_Documentation). + +1. Fork [hexojs/site][] +2. Clone the repository to your computer and install dependencies. + + ```shell + $ git clone https://github.com/<username>/site.git + $ cd site + $ npm install + ``` + +3. Create a new yaml file in `source/_data/plugins/`, use your plugin name as the file name + +4. Edit `source/_data/plugins/<your-plugin-name>.yml` and add your plugin. For example: + + ```yaml + description: Server module for Hexo. + link: https://github.com/hexojs/hexo-server + tags: + - official + - server + - console + ``` + +5. Push the branch. +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 +[hexo-i18n]: https://github.com/hexojs/hexo-i18n +[hexo-pagination]: https://github.com/hexojs/hexo-pagination +[hexojs/site]: https://github.com/hexojs/site diff --git a/source/tr/docs/server.md b/source/tr/docs/server.md new file mode 100644 index 0000000000..dead13d061 --- /dev/null +++ b/source/tr/docs/server.md @@ -0,0 +1,41 @@ +--- +title: Server +--- + +## [hexo-server][] + +With the release of Hexo 3, the server has been separated from the main module. To start using the server, you will first have to install [hexo-server][]. + +```bash +$ npm install hexo-server --save +``` + +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 +``` + +If you want to change the port or if you're encountering `EADDRINUSE` errors, use the `-p` option to set a different port. + +```bash +$ hexo server -p 5000 +``` + +### Static Mode + +In static mode, only files in the `public` folder will be served and file watching is disabled. You have to run `hexo generate` before starting the server. Usually used in production. + +```bash +$ hexo server -s +``` + +### Custom 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 +``` + +[hexo-server]: https://github.com/hexojs/hexo-server diff --git a/source/tr/docs/setup.md b/source/tr/docs/setup.md new file mode 100644 index 0000000000..6a04acd7d7 --- /dev/null +++ b/source/tr/docs/setup.md @@ -0,0 +1,69 @@ +--- +title: Setup +--- + +{% youtube 0m2HnATkHOk %} + +Once Hexo is installed, run the following commands to initialize Hexo in the target `<folder>`. + +```bash +$ hexo init <folder> +$ cd <folder> +$ npm install +``` + +Once initialized, here's what your project folder will look like: + +```plain +. +├── _config.yml +├── package.json +├── scaffolds +├── source +| ├── _drafts +| └── _posts +└── themes +``` + +### \_config.yml + +Site [configuration](configuration.html) file. You can configure most settings here. + +### package.json + +Application data. The [EJS](https://ejs.co/), [Stylus](http://learnboost.github.io/stylus/) and [Markdown](http://daringfireball.net/projects/markdown/) renderers are installed by default. If you want, you can uninstall them later. + +```json package.json +{ + "name": "hexo-site", + "version": "0.0.0", + "private": true, + "hexo": { + "version": "" + }, + "dependencies": { + "hexo": "^7.0.0", + "hexo-generator-archive": "^2.0.0", + "hexo-generator-category": "^2.0.0", + "hexo-generator-index": "^3.0.0", + "hexo-generator-tag": "^2.0.0", + "hexo-renderer-ejs": "^2.0.0", + "hexo-renderer-stylus": "^3.0.0", + "hexo-renderer-marked": "^6.0.0", + "hexo-server": "^3.0.0", + "hexo-theme-landscape": "^1.0.0" + } +} +``` + +### scaffolds + +[Scaffold](writing.html#Scaffolds) folder. When you create a new post, Hexo bases the new file on the scaffold. + +### source + +Source folder. This is where you put your site's content. Hexo ignores hidden files and files or folders whose names are prefixed with `_` (underscore) - except the `_posts` folder. Renderable files (e.g. Markdown, HTML) will be processed and put into the `public` folder, while other files will simply be copied. + +### themes + +[Theme](themes.html) folder. Hexo generates a static website by combining the site contents with the theme. diff --git a/source/tr/docs/syntax-highlight.md b/source/tr/docs/syntax-highlight.md new file mode 100644 index 0000000000..c148666117 --- /dev/null +++ b/source/tr/docs/syntax-highlight.md @@ -0,0 +1,294 @@ +--- +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. + +## How to use code block in posts + +Hexo supports two ways to write code block: [Tag Plugin - Code Block](tag-plugins#Code-Block) and [Tag Plugin - Backtick Code Block](https://hexo.io/docs/tag-plugins#Backtick-Code-Block): + +````markdown +{% codeblock [title] [lang:language] [url] [link text] [additional options] %} +code snippet +{% endcodeblock %} + +{% code [title] [lang:language] [url] [link text] [additional options] %} +code snippet +{% endcode %} + +```[language] [title] [url] [link text] [additional options] +code snippet +``` +```` +The third syntax is 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 the 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. +## Configuration +below v7.0.0: + +```yaml +# _config.yml +highlight: + enable: true + auto_detect: false + line_number: true + line_threshold: 0 + tab_replace: "" + exclude_languages: + - example + wrap: true + hljs: false +prismjs: + enable: false + preprocess: true + line_number: true + line_threshold: 0 + 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: + enable: false +prismjs: + enable: false +``` + +v7.0.0+: + +```yaml +# _config.yml +syntax_highlighter: # empty +``` + +When both `highlight.enable` and `prismjs.enable` are `false` (below v7.0.0) or `syntax_highlighter` is empty (v7.0.0+), 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>`: + +````markdown +```yaml +hello: hexo +``` +```` + +```html +<pre> + <code class="yaml">hello: hexo</code> +</pre> +``` + +When no built-in syntax highlight is enabled, you can either install third-party syntax-highlight plugin, or use a browser-side syntax highlighter (e.g. `highlight.js` and `prism.js` both support running in browser). + +## Highlight.js + +below v7.0.0: + +```yaml +# _config.yml +highlight: + enable: true + auto_detect: false + line_number: true + line_threshold: 0 + tab_replace: " " + exclude_languages: + - example + wrap: true + hljs: false +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`. + +### auto_detect + +`auto_detect` is a `highlight.js` feature that detects language of the code block automatically. + +> 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. +{% endnote %} + +### line_number + +`highlight.js` [does not](https://highlightjs.readthedocs.io/en/latest/line-numbers.html) support line number. + +Hexo adds line number by wrapping output inside `<figure>` and `<table>`: + +```html +<figure class="highlight yaml"> + <table> + <tbody> + <tr> + <td class="gutter"> + <pre><span class="line">1</span><br></pre> + </td> + <td class="code"> + <pre><span class="line"><span class="attr">hello:</span><span class="string">hexo</span></span><br></pre> + </td> + </tr> + </tbody> + </table> +</figure> +``` + +It is not the behavior of `highlight.js` and requires custom CSS for `<figure>` and `<table>` elements; some themes have built-in support. + +You might also notice that all `class` has no `hljs-` prefixed, we will revisit it [later part](#hljs). + +### 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`. + +### tab_replace + +Replace tabs inside code block with given string. By default it is 2 spaces. + +### exclude_languages (+6.1.0) + +Only wrap with `<pre><code class="lang"></code></pre>` and will not render all tags(`span`, and `br`) in content if are languages match this option. + +### 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: + +```html +<pre><code class="yaml"> +<span class="comment"># _config.yml</span> +<span class="attr">hexo:</span> <span class="string">hexo</span> +</code></pre> +``` + +{% 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 %} + +### hljs + +When `hljs` is set to `true`, all the HTML output will have `class` prefixed with `hljs-` (regardless `wrap` is enabled or not): + +```html +<pre><code class="yaml hljs"> +<span class="hljs-comment"># _config.yml</span> +<span class="hljs-attr">hexo:</span> <span class="hljs-string">hexo</span> +</code></pre> +``` + +> Tip: When `line_number` is set to `false`, `wrap` is set to false and `hljs` is set to `true`, you can then use `highlight.js` [theme](https://github.com/highlightjs/highlight.js/tree/master/src/styles) directly in your site. + +## PrismJS + +below v7.0.0: + +```yaml +# _config.yml +highlight: + enable: false +prismjs: + enable: true + preprocess: true + line_number: true + line_threshold: 0 + tab_replace: "" +``` + +v7.0.0+: + +```yaml +# _config.yml +syntax_highlighter: prismjs +prismjs: + preprocess: true + line_number: true + line_threshold: 0 + tab_replace: "" +``` + +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. + +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. +- [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: + +- [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`. +- [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_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`. + +### 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`. + +### tab_replace + +Replace `\t` inside code block with given string. By default it is 2 spaces. + +## Other useful information + +- [Highlight.js](https://highlightjs.readthedocs.io/en/latest/) +- [PrismJS](https://prismjs.com/) + +The source codes behind Hexo's syntax highlighting are available in: + +- [Highlight.js Utility Functions](https://github.com/hexojs/hexo-util/blob/master/lib/highlight.ts) +- [PrismJS Utility Functions](https://github.com/hexojs/hexo-util/blob/master/lib/prism.ts) +- [Tag Plugin - Code Block](https://github.com/hexojs/hexo/blob/master/lib/plugins/tag/code.ts) +- [Tag Plugin - Backtick Code Block](https://github.com/hexojs/hexo/blob/master/lib/plugins/filter/before_post_render/backtick_code_block.ts) diff --git a/source/tr/docs/tag-plugins.md b/source/tr/docs/tag-plugins.md new file mode 100644 index 0000000000..098e13cb20 --- /dev/null +++ b/source/tr/docs/tag-plugins.md @@ -0,0 +1,493 @@ +--- +title: Tag Plugins +--- + +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 I07XMi7MHd4 %} + +_Tag plugins should not be wrapped inside Markdown syntax, e.g. `[]({% post_path lorem-ipsum %})` is not supported._ + +## Block Quote + +Perfect for adding quotes to your post, with optional author, source and title information. + +**Alias:** quote + +``` +{% blockquote [author[, source]] [link] [source_link_title] %} +content +{% endblockquote %} +``` + +### Examples + +**No arguments. Plain blockquote.** + +``` +{% blockquote %} +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque hendrerit lacus ut purus iaculis feugiat. Sed nec tempor elit, quis aliquam neque. Curabitur sed diam eget dolor fermentum semper at eu lorem. +{% endblockquote %} +``` + +{% blockquote %} +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque hendrerit lacus ut purus iaculis feugiat. Sed nec tempor elit, quis aliquam neque. Curabitur sed diam eget dolor fermentum semper at eu lorem. +{% endblockquote %} + +**Quote from a book** + +``` +{% blockquote David Levithan, Wide Awake %} +Do not just seek happiness for yourself. 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. +{% endblockquote %} + +**Quote from Twitter** + +``` +{% blockquote @DevDocs https://twitter.com/devdocs/status/356095192085962752 %} +NEW: DevDocs now comes with syntax highlighting. http://devdocs.io +{% endblockquote %} +``` + +{% blockquote @DevDocs https://twitter.com/devdocs/status/356095192085962752 %} +NEW: DevDocs now comes with syntax highlighting. http://devdocs.io +{% endblockquote %} + +**Quote from an article on the web** + +``` +{% 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 %} +``` + +{% 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 %} + +## Code Block + +A useful feature for adding code snippets to your post. + +**Alias:** code + +``` +{% codeblock [title] [lang:language] [url] [link text] [additional options] %} +code snippet +{% endcodeblock %} +``` + +Specify additional options in `option:value` format, e.g. `line_number:false first_line:5`. + +| Extra Options | Description | Default | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `line_number` | Show 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` | Enable code highlighting | `true` | +| `first_line` | Specify the first line number | `1` | +| `mark` | Line highlight specific line(s), each value separated by a comma. Specify the number range using a dash<br>Example: `mark:1,4-7,10` will mark lines 1, 4 to 7 and 10. | | +| `wrap` | Wrap the code block in [`<table>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table) | `true` | + +### Examples + +**A plain code block** + +``` +{% codeblock %} +alert('Hello World!'); +{% endcodeblock %} +``` + +{% codeblock %} +alert('Hello World!'); +{% endcodeblock %} + +**Specifying the language** + +``` +{% codeblock lang:objc %} +[rectangle setX: 10 y: 10 width: 20 height: 20]; +{% endcodeblock %} +``` + +{% codeblock lang:objc %} +[rectangle setX: 10 y: 10 width: 20 height: 20]; +{% endcodeblock %} + +**Adding a caption to the code block** + +``` +{% codeblock Array.map %} +array.map(callback[, thisArg]) +{% endcodeblock %} +``` + +{% codeblock Array.map %} +array.map(callback[, thisArg]) +{% endcodeblock %} + +**Adding a caption and a URL** + +``` +{% codeblock _.compact http://underscorejs.org/#compact Underscore.js %} +_.compact([0, 1, false, 2, '', 3]); +=> [1, 2, 3] +{% endcodeblock %} +``` + +{% codeblock _.compact http://underscorejs.org/#compact Underscore.js %} +\_.compact([0, 1, false, 2, '', 3]); => [1, 2, 3] +{% endcodeblock %} + +## 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] +code snippet +`` +{% endraw %} + +## Pull Quote + +To add pull quotes to your posts: + +``` +{% pullquote [class] %} +content +{% endpullquote %} +``` + +## jsFiddle (deleted in `v7.0.0`) + +{% note warn %} +The tag was removed in Hexo 7.0.0. We have provided a plugin [hexo-tag-embed](https://github.com/hexojs/hexo-tag-embed) for backward compatibility with your existing posts. +{% endnote %} + +To embed a jsFiddle snippet: + +``` +{% jsfiddle shorttag [tabs] [skin] [width] [height] %} +``` + +## Gist (deleted in `v7.0.0`) + +{% note warn %} +Please use [hexo-tag-embed](https://github.com/hexojs/hexo-tag-embed) instead if you use `v7.0.0+`. +{% endnote %} + +To embed a Gist snippet: + +``` +{% gist gist_id [filename] %} +``` + +## iframe + +To embed an iframe: + +``` +{% iframe url [width] [height] %} +``` + +## Image + +Inserts an image with specified size. + +``` +{% img [class names] /path/to/image [width] [height] '"title text" "alt text"' %} +``` + +## Link + +Inserts a link with `target="_blank"` attribute. + +``` +{% link text url [external] [title] %} +``` + +## Include Code + +Inserts code snippets in `source/downloads/code` folder. The folder location can be specified through the `code_dir` option in the config. + +``` +{% include_code [title] [lang:language] [from:line] [to:line] path/to/file %} +``` + +### Examples + +**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 (deleted in `v7.0.0`) + +{% note warn %} +Please use [hexo-tag-embed](https://github.com/hexojs/hexo-tag-embed) instead if you use `v7.0.0+`. +{% endnote %} + +Inserts a YouTube video. + +``` +{% youtube video_id [type] [cookie] %} +``` + +### Examples + +**Embed a video** + +``` +{% youtube lJIrF4YjHfQ %} +``` + +**Embed a playlist** + +``` +{% youtube PL9hW1uS6HUfscJ9DHkOSoOX45MjXduUxo 'playlist' %} +``` + +**Enable privacy-enhanced mode** + +YouTube's cookie is not used in this mode. + +``` +{% youtube lJIrF4YjHfQ false %} +{% youtube PL9hW1uS6HUfscJ9DHkOSoOX45MjXduUxo 'playlist' false %} +``` + +## Vimeo (deleted in `v7.0.0`) + +{% note warn %} +Please use [hexo-tag-embed](https://github.com/hexojs/hexo-tag-embed) instead if you use `v7.0.0+`. +{% endnote %} + +Inserts a responsive or specified size Vimeo video. + +``` +{% vimeo video_id [width] [height] %} +``` + +## Include Posts + +Include links to other posts. + +``` +{% post_path filename %} +{% post_link filename [title] [escape] %} +``` + +You can ignore permalink and folder information, like languages and dates, when using this tag. + +For instance: `{% raw %}{% post_link how-to-bake-a-cake %}{% endraw %}`. + +This will work as long as the filename of the post is `how-to-bake-a-cake.md`, even if the post is located at `source/posts/2015-02-my-family-holiday` and has permalink `2018/en/how-to-bake-a-cake`. + +You can customize the text to display, instead of displaying the post's title. + +Post's title and custom text are escaped by default. You can use the `escape` option to disable escaping. + +For instance: + +**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' %} + +**Do not escape title.** + +``` +{% post_link hexo-4-released '<b>bold</b> custom title' false %} +``` + +{% 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 %} +{% asset_img [class names] slug [width] [height] [title text [alt text]] %} +{% asset_link filename [title] [escape] %} +``` + +### Embed image + +_hexo-renderer-marked 3.1.0+ can (optionally) resolves the post's path of an image automatically, refer to [this section](/docs/asset-folders#Embedding-an-image-using-markdown) on how to enable it._ + +"foo.jpg" is located at `http://example.com/2020/01/02/hello/foo.jpg`. + +**Default (no option)** + +`{% asset_img foo.jpg %}` + +```html +<img src="/2020/01/02/hello/foo.jpg" /> +``` + +**Custom class** + +`{% asset_img post-image foo.jpg %}` + +```html +<img src="/2020/01/02/hello/foo.jpg" class="post-image" /> +``` + +**Display size** + +`{% asset_img foo.jpg 500 400 %}` + +```html +<img src="/2020/01/02/hello/foo.jpg" width="500" height="400" /> +``` + +**Title & Alt** + +`{% asset_img foo.jpg "lorem ipsum'dolor'" %}` + +```html +<img src="/2020/01/02/hello/foo.jpg" title="lorem ipsum" alt="dolor" /> +``` + +## URL + +### url_for (7.0.0+) + +Returns a url with the root path prefixed. Output is encoded automatically. + +``` +{% url_for text path [relative] %} +``` + +**Examples:** + +```yml +_config.yml +root: /blog/ # example +``` + +``` +{% url_for blog index.html %} +``` + +```html +<a href="/blog/index.html">blog</a> +``` + +Relative link, follows `relative_link` option by default e.g. post/page path is '/foo/bar/index.html' + +```yml +_config.yml +relative_link: true +``` + +``` +{% url_for blog index.html %} +``` + +```html +<a href="../../index.html">blog</a> +``` + +You could also disable it to output a non-relative link, even when `relative_link` is enabled and vice versa. + +``` +{% url_for blog index.html false %} +``` + +```html +<a href="/index.html">blog</a> +``` + +### full_url_for (7.0.0+) + +Returns a url with the `config.url` prefixed. Output is encoded automatically. + +``` +{% full_url_for text path %} +``` + +**Examples:** + +```yml +_config.yml +url: https://example.com/blog # example +``` + +``` +{% full_url_for index /a/path %} +``` + +```html +<a href="https://example.com/blog/a/path">index</a> +``` + +## Raw + +If certain content is causing processing issues in your posts, wrap it with the `raw` tag to avoid rendering errors. + +``` +{% raw %} +content +{% endraw %} +``` + +## Post Excerpt + +Use text placed before the `<!-- more -->` tag as an excerpt for the post. `excerpt:` value in the [front-matter](/docs/front-matter#Settings-amp-Their-Default-Values), if specified, will take precedent. + +**Examples:** + +``` +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. +``` diff --git a/source/tr/docs/templates.md b/source/tr/docs/templates.md new file mode 100644 index 0000000000..d5385a0abd --- /dev/null +++ b/source/tr/docs/templates.md @@ -0,0 +1,110 @@ +--- +title: Templates +--- + +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. At the very least, a theme should contain an `index` template. + +{% youtube mb65bQ4iUc4 %} + +| Template | Page | Fallback | +| ---------- | ----------------- | --------- | +| `index` | Home page | | +| `post` | Posts | `index` | +| `page` | Pages | `index` | +| `archive` | Archives | `index` | +| `category` | Category archives | `archive` | +| `tag` | Tag archives | `archive` | + +## Layouts + +When pages share a similar structure - for instance, when two templates have both a header and a footer - you can consider using a `layout` to declare these structural similarities. Every layout file should contain a `body` variable to display the contents of the template in question. For example: + +```html index.ejs +index +``` + +```html layout.ejs +<!doctype html> +<html> + <body> + <%- body %> + </body> +</html> +``` + +yields: + +```html +<!doctype html> +<html> + <body> + index + </body> +</html> +``` + +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. + +## Partials + +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> +``` + +```html index.ejs +<%- partial('partial/header') %> +<div id="content">Home page</div> +``` + +yields: + +```html +<h1 id="logo">My Site</h1> +<div id="content">Home page</div> +``` + +## Local Variables + +You can define local variables in templates and use them in other templates. + +```html partial/header.ejs +<h1 id="logo"><%= title %></h1> +``` + +```html index.ejs +<%- partial('partial/header', {title: 'Hello World'}) %> +<div id="content">Home page</div> +``` + +yields: + +```html +<h1 id="logo">Hello World</h1> +<div id="content">Home page</div> +``` + +## Optimization + +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. Aside from simplifying your theme, you may also try Fragment Caching, which was introduced in Hexo 2.7. + +This feature was borrowed from [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. + +Fragment caching is best used for headers, footers, sidebars or other static content that is unlikely to change from template to template. For example: + +```js +<%- fragment_cache('header', function(){ + return '<header></header>'; +}); +``` + +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. +{% endnote %} diff --git a/source/tr/docs/themes.md b/source/tr/docs/themes.md new file mode 100644 index 0000000000..c142ebf49d --- /dev/null +++ b/source/tr/docs/themes.md @@ -0,0 +1,83 @@ +--- +title: Themes +--- + +{% youtube 5ROIU_9dYe4 %} + +It's easy to build a Hexo theme - you just have to create a new folder. To start using your theme, modify the `theme` setting in your site's `_config.yml`. A theme should have the following structure: + +```plain +. +├── _config.yml +├── languages +├── layout +├── scripts +└── source +``` + +### \_config.yml + +Theme configuration file. Unlike the site's primary configuration file, modifying this doesn't require a server restart. + +### languages + +Language folder. See [internationalization (i18n)](internationalization.html) for more info. + +### layout + +Layout folder. This folder contains the theme's template files, which define the appearance of your website. Hexo provides the [Nunjucks][] template engine by default, but you can easily install additional plugins to support alternative engines such as [EJS][] or [Pug][]. Hexo chooses the template engine based on the file extension of the template (just like the posts). For example: + +```plain +layout.ejs - uses EJS +layout.njk - uses Nunjucks +``` + +See [templates](templates.html) for more info. + +### scripts + +Script folder. Hexo will automatically load all JavaScript files in this folder during initialization. For more info, see [plugins](plugins.html). + +### source + +Source folder. Place your assets (e.g. CSS and JavaScript files) here. Hexo ignores hidden files and files or folders prefixed with `_` (underscore). + +Hexo will process and save all renderable files to the `public` folder. Non-renderable files will be copied to the `public` folder directly. + +### Publishing + +When you have finished building your theme, you can publish it to the [theme list](/themes). Before doing so, you should run the [theme unit test](https://github.com/hexojs/hexo-theme-unit-test) to ensure that everything works. The steps for publishing a theme are very similar to those for [updating documentation](contributing.html#Updating_Documentation). + +1. Fork [hexojs/site][] +2. Clone the repository to your computer and install dependencies. + + ```shell + $ git clone https://github.com/<username>/site.git + $ cd site + $ npm install + ``` + +3. Create a new yaml file in `source/_data/themes/`, use your theme name as the file name + +4. Edit `source/_data/themes/<your-theme-name>.yml` and add your theme. For example: + + ```yaml + 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 + ``` + +5. Add a screenshot (with the same name as the theme) to `source/themes/screenshots`. It must be a 800\*500px PNG. +6. Push the branch. +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 +[hexojs/site]: https://github.com/hexojs/site +[Nunjucks]: https://mozilla.github.io/nunjucks/ diff --git a/source/tr/docs/troubleshooting.md b/source/tr/docs/troubleshooting.md new file mode 100644 index 0000000000..19a5ef2632 --- /dev/null +++ b/source/tr/docs/troubleshooting.md @@ -0,0 +1,294 @@ +--- +title: Troubleshooting +--- + +In case you're experiencing problems with using Hexo, here is a list of solutions to some frequently encountered issues. If this page doesn't help you solve your problem, try doing a search on [GitHub](https://github.com/hexojs/hexo/issues) or our [Google Group](https://groups.google.com/group/hexo). + +## YAML Parsing Error + +```plain +JS-YAML: incomplete explicit mapping pair; a key node is missed at line 18, column 29: + last_updated: Last updated: %s +``` + +Wrap the string with quotations if it contains colons. + +```plain +JS-YAML: bad indentation of a mapping entry at line 18, column 31: + last_updated:"Last updated: %s" +``` + +Make sure you are using soft tabs and add a space after colons. + +You can see [YAML Spec](http://www.yaml.org/spec/1.2/spec.html) for more info. + +## EMFILE Error + +```plain +Error: EMFILE, too many open files +``` + +Though Node.js has non-blocking I/O, the maximum number of synchronous I/O is still limited by the system. 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 +``` + +**Error: cannot modify limit** + +If you encounter the following error: + +```bash +$ ulimit -n 10000 +ulimit: open files: cannot modify limit: Operation not permitted +``` + +It means some system-wide configurations are preventing `ulimit` to being increased to a certain limit. + +To override the limit: + +1. Add the following line to "/etc/security/limits.conf": + +``` +* - nofile 10000 + +# '*' 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) + +``` +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": + +``` +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 Deployment Problems + +### RPC failed + +```plain +error: RPC failed; result=22, HTTP code = 403 + +fatal: 'username.github.io' does not appear to be a git repository +``` + +Make sure you have [set up git](https://help.github.com/articles/set-up-git) on your computer properly or try to use HTTPS repository URL instead. + +### 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` + +## Server Problems + +```plain +Error: listen EADDRINUSE +``` + +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 +``` + +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 +$ npm install hexo --no-optional +``` + +See [#1326](https://github.com/hexojs/hexo/issues/1326#issuecomment-113871796) + +## Iterate Data Model on Jade or Swig + +Hexo uses [Warehouse][] for its data model. It's not an array so you may have to transform objects into iterables. + +``` +{% for post in site.posts.toArray() %} +{% endfor %} +``` + +## Data Not Updated + +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 +``` + +## 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 uses [Nunjucks][] to render posts ([Swig][] was used in the older version, which shares a similar syntax). 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 %} +Hello {{ world }} +{% endraw %} +``` + +```` +``` +Hello {{ world }} +``` +```` + +## ENOSPC Error (Linux) + +Sometimes when running the command `$ hexo server` it returns an error: + +``` +Error: watch ENOSPC ... +``` + +It can be fixed by running `$ npm dedupe` or, if that doesn't help, try the following in the Linux console: + +``` +$ echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p +``` + +This will increase the limit for the number of files you can watch. + +## EMPERM Error (Windows Subsystem for Linux) + +When running `$ hexo server` in a BashOnWindows environment, it returns the following error: + +``` +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: + +```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). + +## 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 +Template render error: (unknown path) +``` + +Possible cause: + +- 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. [`{% raw %} {# {% endraw %}`](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 install js-yaml@latest +``` + +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/ +[Nunjucks]: https://mozilla.github.io/nunjucks/ diff --git a/source/tr/docs/variables.md b/source/tr/docs/variables.md new file mode 100644 index 0000000000..ee076a0858 --- /dev/null +++ b/source/tr/docs/variables.md @@ -0,0 +1,103 @@ +--- +title: Variables +--- + +{% youtube T9oAax-IRw0 %} + +### Global Variables + +| Variable | Description | Type | +| -------- | ------------------------------------------------------------------- | --------------------------------------- | +| `site` | Sitewide information. | `object`; see [Site Variables][] | +| `page` | Page specific information and custom variables set in front-matter. | `object`; see [Page Variables][] | +| `config` | Site configuration. | `object` (your site's \_config file) | +| `theme` | Theme configuration. Inherits from site configuration. | `object` (your theme's \_config file) | +| `path` | Path of current page | `string` | +| `url` | Full URL of current page | `string` | +| `env` | Environment variables | ??? | + +{% 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 + +| Variable | Description | Type | +| ----------------- | -------------- | ---------------------- | +| `site.posts` | All posts | [Query][queryo] object | +| `site.pages` | All pages | [Query][queryo] object | +| `site.categories` | All categories | [Query][queryo] object | +| `site.tags` | All tags | [Query][queryo] object | + +### Page Variables + +**Article (`page`)** + +| Variable | Description | Type | +| ------------------ | -------------------------------------------------------------------------------------- | -------------------- | +| `page.title` | Article title | `string` | +| `page.date` | Article created date | [Moment.js][] object | +| `page.updated` | Article last updated date | [Moment.js][] object | +| `page.comments` | Comment enabled or not | `boolean` | +| `page.layout` | Layout name | `string` | +| `page.content` | The full processed content of the article | `string` | +| `page.excerpt` | Article excerpt | `string` | +| `page.more` | Contents except article excerpt | `string` | +| `page.source` | The path of the source file | `string` | +| `page.full_source` | Full path of the source file | `string` | +| `page.path` | The URL of the article without root URL. We usually use `url_for(page.path)` in theme. | `string` | +| `page.permalink` | Full (encoded) URL of the article | `string` | +| `page.prev` | The previous post, `null` if the post is the first post | ??? | +| `page.next` | The next post, `null` if the post is the last post | ??? | +| `page.raw` | The raw data of the article | ??? | +| `page.photos` | The photos of the article (Used in gallery posts) | array of ??? | +| `page.link` | The external link of the article (Used in link posts) | `string` | + +**Post (`post`):** Same as `page` layout but add the following variables. + +| Variable | Description | Type | +| ----------------- | ------------------------------- | -------------- | +| `page.published` | 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 ??? | + +**Home (`index`)** + +| Variable | Description | Type | +| ------------------ | --------------------------------------------------------------------------------------- | -------- | +| `page.per_page` | Posts displayed per page | `number` | +| `page.total` | Total number of pages | `number` | +| `page.current` | Current page number | `number` | +| `page.current_url` | The URL of current page | `string` | +| `page.posts` | Posts in this page ([Data Model](https://hexojs.github.io/warehouse/)) | `object` | +| `page.prev` | Previous page number. `0` if the current page is the first. | `number` | +| `page.prev_link` | The URL of previous page. `''` if the current page is the first. | `string` | +| `page.next` | Next page number. `0` if the current page is the last. | `number` | +| `page.next_link` | The URL of next page. `''` if the current page is the last. | `string` | +| `page.path` | The URL of current page without root URL. We usually use `url_for(page.path)` in theme. | `string` | + +**Archive (`archive`):** Same as `index` layout but add the following variables. + +| Variable | Description | Type | +| -------------- | --------------------------------------------- | --------- | +| `page.archive` | Equals `true` | `boolean` | +| `page.year` | Archive year (4-digit) | `number` | +| `page.month` | Archive month (2-digit without leading zeros) | `number` | + +**Category (`category`):** Same as `index` layout but add the following variables. + +| Variable | Description | Type | +| --------------- | ------------- | -------- | +| `page.category` | Category name | `string` | + +**Tag (`tag`):** Same as `index` layout but add the following variables. + +| Variable | Description | Type | +| ---------- | ----------- | -------- | +| `page.tag` | Tag name | `string` | + +[queryo]: https://hexojs.github.io/warehouse/classes/query.default.html + +[Moment.js]: http://momentjs.com/ +[Site Variables]: #Site-Variables +[Page Variables]: #Page-Variables diff --git a/source/tr/docs/writing.md b/source/tr/docs/writing.md new file mode 100644 index 0000000000..14ad1e780b --- /dev/null +++ b/source/tr/docs/writing.md @@ -0,0 +1,74 @@ +--- +title: Writing +--- + +{% youtube AIqBubK6ZLc %} + +To create a new post or a new page, you can run the following command: + +```bash +$ hexo new [layout] <title> +``` + +`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 + +There are three default layouts in Hexo: `post`, `page` and `draft`. Files created by each of them is saved to a different path. Newly created posts are saved to the `source/_posts` folder. + +| Layout | Path | +| ------- | ---------------- | +| `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](/docs/front-matter#Layout) for more details. +{% endnote %} + +## Filename + +By default, Hexo uses the post title as its filename. You can edit the `new_post_name` setting in `_config.yml` to change the default filename. For example, `:year-:month-:day-:title.md` will prefix filenames with the post creation date. You can use the following placeholders: + +| Placeholder | Description | +| ----------- | -------------------------------------------------------- | +| `: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` | + +## Drafts + +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> +``` + +Drafts are not displayed by default. You can add the `--draft` option when running Hexo or enable the `render_drafts` setting in `_config.yml` to render drafts. + +## Scaffolds + +When creating posts, Hexo will build files based on the corresponding file in `scaffolds` folder. For example: + +```bash +$ hexo new photo "My Gallery" +``` + +When you run this command, Hexo will try to find `photo.md` in the `scaffolds` folder and build the post based on it. The following placeholders are available in scaffolds: + +| Placeholder | Description | +| ----------- | ----------------- | +| `layout` | Layout | +| `title` | Title | +| `date` | File created date | + +## Supported Formats + +Hexo supports 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. + +You can rename your posts and change the file extension from `.md` to `.ejs`, then Hexo will use `hexo-renderer-ejs` to render that file, and so do the other formats. diff --git a/source/tr/index.md b/source/tr/index.md new file mode 100644 index 0000000000..e5f4469e1a --- /dev/null +++ b/source/tr/index.md @@ -0,0 +1,41 @@ +--- +layout: index +description: Hexo is a fast, simple & powerful blog framework powered by Node.js. +subtitle: A fast, simple & powerful blog framework +comments: false +--- + +<ul id="intro-feature-list"> + <li class="intro-feature-wrap"> + <div class="intro-feature"> + <div class="intro-feature-icon"> + <i class="fa fa-bolt"></i> + </div> + <h3 class="intro-feature-title">Blazing Fast</h3> + <p class="intro-feature-desc">Incredible generating speed powered by Node.js. Hundreds of files take only seconds to build.</p> + </div> + </li> + <li class="intro-feature-wrap"> + <div class="intro-feature"> + <div class="intro-feature-icon"> + <i class="fa fa-pencil"></i> + </div> + <h3 class="intro-feature-title">Markdown Support</h3> + <p class="intro-feature-desc">All features of GitHub Flavored Markdown are supported, including most Octopress plugins.</p> + </div></li><li class="intro-feature-wrap"> + <div class="intro-feature"> + <div class="intro-feature-icon"> + <i class="fa fa-cloud-upload"></i> + </div> + <h3 class="intro-feature-title">One-Command Deployment</h3> + <p class="intro-feature-desc">You only need one command to deploy your site to GitHub Pages, Heroku or other platforms.</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">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> diff --git a/source/zh-cn/docs/one-command-deployment.md b/source/zh-cn/docs/one-command-deployment.md index f48c23ee38..4ce3c71d7c 100644 --- a/source/zh-cn/docs/one-command-deployment.md +++ b/source/zh-cn/docs/one-command-deployment.md @@ -127,7 +127,7 @@ deploy: ## FTPSync -Install [hexo-deployer-ftpsync][]. +安装 [hexo-deployer-ftpsync][]。 ```bash $ npm install hexo-deployer-ftpsync --save