配置

Hexo 的配置文件 _config.yml 是一个非常重要的文件，用于自定义网站的各种设置。下面是一个基本的 _config.yml 文件示例，并附带一些常用的配置选项说明：

# Hexo Configuration
## Docs: https://hexo.io/docs/configuration.html
## Source: https://github.com/hexojs/hexo/

# Site
title: Your Blog Title          # 博客标题
subtitle: A simple blog       # 博客副标题
description: ""                 # 描述信息
author: Your Name             # 作者名字
language: zh-CN               # 设置语言，默认是zh-CN（简体中文）
timezone: Asia/Shanghai       # 时区

# URL
url: http://yourdomain.com    # 您的博客网址
root: /                       # 根目录
permalink: :year/:month/:day/:title/   # 文章永久链接格式
permalink_defaults:

# Directory
source_dir: source            # 资源文件夹，这个文件夹用来存放文章和其他资源
public_dir: public            # 公共文件夹，这个文件夹用于存放生成的静态页面
tag_dir: tags                 # 标签文件夹
archive_dir: archives         # 归档文件夹
category_dir: categories      # 分类文件夹
code_dir: downloads/code      # Include code 文件夹，保存 include 代码
i18n_dir: :lang               # 国际化文件夹
skip_render:

# Writing
new_post_name: :title.md      # 新建文章的默认文件名
default_layout: post          # 默认布局
titlecase: false              # 是否将标题转换为 title case
external_link:
  enable: true                # 是否开启外链跳转提示
  field: site                 # 对整个站点生效还是仅对文章生效
  exclude:                    #
  hostname_skip:              #
filename_case: 0              # 处理文件名大小写的方式
render_drafts: false          # 显示草稿
post_asset_folder: false      # 启用 Asset 文件夹
relative_link: false          # 将链接改为相对路径
future: true                  # 显示未来的文章
highlight:
  enable: true                # 开启代码高亮
  line_number: true           # 显示行号
  auto_detect: false          # 自动检测语言类型
  tab_replace: ""
  wrap: true
  hljs: false

# Home page setting
pagination_dir: page          # 分页目录
per_page: 10                  # 每页显示的文章数量
pagination_dir: page          # 分页目录

# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: landscape              # 主题名称

# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
  type: git                   # 部署方式
  repo: https://github.com/user/repo.git # 远程仓库地址
  branch: master              # 分支名

常见配置项解释：

• Site: 包含了网站的基本信息，如标题、描述等。
• URL: 定义了网站的根URL和永久链接格式。
• Directory: 指定了各个目录的位置，包括资源文件夹、公共文件夹等。
• Writing: 提供了一些写作相关的配置，比如新建文章的命名规则、是否启用代码高亮等。
• Home page setting: 控制首页分页的相关设置。
• Extensions: 可以在这里添加插件和主题的信息。
• Deployment: 定义了如何部署您的网站，比如通过Git推送至GitHub Pages。
  您可以根据自己的需求调整这些配置项，以定制出符合自己风格的博客。

英文版

You can modify site settings in _config.yml or in an alternate config file.

Site

URL

{% 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:

# e.g. page.permalink is http://example.com/foo/bar/index.html
pretty_urls:
  trailing_index: false
# becomes http://example.com/foo/bar/

Directory

Examples:

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

Home page setting

Category & Tag

Examples:

category_map:
  "yesterday's thoughts": yesterdays-thoughts
  "C++": c-plus-plus

Date / Time format

Hexo uses Moment.js to process dates.

{% 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

Examples:

pagination_dir: 'page'
# http://example.com/page/2

pagination_dir: 'awesome-page'
# http://example.com/awesome-page/2

Extensions

Include/Exclude Files or Folders

Use the following options to explicitly process or ignore certain files/folders. Support glob expressions for path matching.

include and exclude options only apply to the source/ folder, whereas ignore option applies to all folders.

Examples:

# 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.

# 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

# _config.yml
theme: "my-theme"
theme_config:
  bio: "My awesome bio"
  foo:
    bar: "a"

# themes/my-theme/_config.yml
bio: "Some generic bio"
logo: "a-cool-image.png"
  foo:
    baz: 'b'

Resulting in theme configuration:

{
  "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

# _config.yml
theme: "my-theme"

# _config.my-theme.yml
bio: "My awesome bio"
foo:
  bar: "a"

# themes/my-theme/_config.yml
bio: "Some generic bio"
logo: "a-cool-image.png"
  foo:
    baz: 'b'

Resulting in theme configuration:

{
  "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 %}

中文版

您可以在 _config.yml 或 代替配置文件 中修改大部分的配置。

网站

网址

{% note info 网站存放在子目录 %}
如果您的网站存放在子目录中，例如 http://example.com/blog，则请将您的 url 设为 http://example.com/blog 并把 root 设为 /blog/。
{% endnote %}

例如：

# e.g. page.permalink is http://example.com/foo/bar/index.html
pretty_urls:
  trailing_index: false
# becomes http://example.com/foo/bar/

目录

例如：

skip_render: "mypage/**/*"
# 将会直接将 `source/mypage/index.html` 和 `source/mypage/code.js` 不做改动地输出到 'public' 目录
# 你也可以用这种方法来跳过对指定文章文件的渲染
skip_render: "_posts/test-post.md"
# 这将会忽略对 'test-post.md' 的渲染

## This also can be used to exclude posts,
skip_render: "_posts/test-post.md"
# will ignore the `source/_posts/test-post.md`.

文章

首页设置

分类 & 标签

例如：

category_map:
  "yesterday's thoughts": yesterdays-thoughts
  "C++": c-plus-plus

日期 / 时间格式

Hexo 使用 Moment.js 来解析和显示时间。

{% note info updated_option %}
updated_option 控制了当 Front Matter 中没有指定 updated 时，updated 如何取值：

• mtime: 使用文件的最后修改时间。 这是从 Hexo 3.0.0 开始的默认行为。
• date: 使用 date 作为 updated 的值。 可被用于 Git 工作流之中，因为使用 Git 管理站点时，文件的最后修改日期常常会发生改变
• empty: 直接删除 updated。 使用这一选项可能会导致大部分主题和插件无法正常工作。

use_date_for_updated 选项已经在 v7.0.0+ 中被移除。 请改为使用 updated_option: 'date'。
{% endnote %}

分页

例如：

pagination_dir: 'page'
# http://example.com/page/2

pagination_dir: 'awesome-page'
# http://example.com/awesome-page/2

扩展

包括或不包括目录和文件

使用以下选项可明确处理或忽略某些文件/文件夹。 可以使用 glob 表达式 进行路径匹配。

include 和 exclude 选项只会应用到 source/ ，而 ignore 选项会应用到所有文件夹.

例如：

# 处理或不处理目录或文件
include:
  - ".nojekyll"
  # 处理 'source/css/_typing.css'
  - "css/_typing.css"
  # 处理 'source/_css/' 中的任何文件，但不包括子目录及其其中的文件。
  - "_css/*"
  # 处理 'source/_css/' 中的任何文件和子目录下的任何文件。
  - "_css/**/*"

exclude:
  # 不处理 'source/js/test.js'。
  - "js/test.js"
  # 不处理 'source/js/' 中的文件、但包括子目录下的所有目录和文件。
  - "js/*"
  # 不处理 'source/js/' 中的文件和子目录下的任何文件。
  - "js/**/*"
  # 不处理 'source/js/' 目录下的所有文件名以 'test' 开头的文件，但包括其它文件和子目录下的单文件。
  - "js/test*"
  # 不处理 'source/js/' 及其子目录中任何以 'test' 开头的文件。
  - "js/**/test*"
  # 不要用 exclude 来忽略 'source/_posts/' 中的文件。
  # 你应该使用 'skip_render'。 或者在要忽略的文件的文件名之前加一个下划线 '_'。
  # - "_posts/hello-world.md" # 在这里配置是没有用的。

ignore:
  # 忽略任何一个名叫 'foo' 的文件夹。
  - "**/foo"
  # 只忽略 'themes/' 下的 'foo' 文件夹。
  - "**/themes/*/foo"
  # 对 'themes/' 目录下的每个文件夹中忽略名叫 'foo' 的子文件夹。
  - "**/themes/**/foo"

列表中的每一项都必须用单引号或双引号包裹起来。

include 和 exclude 并不适用于 themes/ 目录下的文件。 如果需要忽略 themes/ 目录下的部分文件或文件夹，可以使用 ignore 或在文件名之前添加下划线 _。

source/_posts 文件夹是一个例外，但该文件夹下任何名称以 _ 开头的文件或文件夹仍会被忽略。 不建议在该文件夹中使用 include 规则。

使用代替配置文件

可以在 hexo-cli 中使用 --config 参数来指定自定义配置文件的路径。 你可以使用一个 YAML 或 JSON 文件的路径，也可以使用逗号分隔（无空格）的多个 YAML 或 JSON 文件的路径。

# 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

当你指定了多个配置文件以后，Hexo 会按顺序将这部分配置文件合并成一个 _multiconfig.yml。 后面的值优先。 这个原则适用于任意数量、任意深度的 YAML 和 JSON 文件。 请注意，列表中不允许有空格。

如果 custom.yml 中指定了 foo: bar，在 custom2.json 中指定了 "foo": "dinosaur"，那么在 _multiconfig.yml 中你会得到 foo: dinosaur。

使用代替主题配置文件

通常情况下，Hexo 主题是一个独立的项目，并拥有一个独立的 _config.yml 配置文件。

除了自行维护独立的主题配置文件，你也可以在其它地方对主题进行配置。

配置文件中的 theme_config

该特性自 Hexo 2.8.2 起提供

# _config.yml
theme: "my-theme"
theme_config:
  bio: "My awesome bio"
  foo:
    bar: "a"

# themes/my-theme/_config.yml
bio: "Some generic bio"
logo: "a-cool-image.png"
  foo:
    baz: 'b'

最终主题配置的输出是：

{
  "bio": "My awesome bio",
  "logo": "a-cool-image.png",
  "foo": {
    "bar": "a",
    "baz": "b"
  }
}

独立的 _config.[theme].yml 文件

该特性自 Hexo 5.0.0 起提供

独立的主题配置文件应放置于站点根目录下，支持 yml 或 json 格式。 需要配置站点 _config.yml 文件中的 theme 以供 Hexo 寻找 _config.[theme].yml 文件。

# _config.yml
theme: "my-theme"

# _config.my-theme.yml
bio: "My awesome bio"
foo:
  bar: "a"

# themes/my-theme/_config.yml
bio: "Some generic bio"
logo: "a-cool-image.png"
  foo:
    baz: 'b'

最终主题配置的输出是：

{
  "bio": "My awesome bio",
  "logo": "a-cool-image.png",
  "foo": {
    "bar": "a",
    "baz": "b"
  }
}

{% note %}
我们强烈建议你将所有的主题配置集中在一处。 如果你不得不在多处配置你的主题，那么这些信息对你将会非常有用：Hexo 在合并主题配置时，Hexo 配置文件中的 theme_config 的优先级最高，其次是 _config.[theme].yml 文件。 最后是位于主题目录下的 _config.yml 文件。
{% endnote %}