本文主要对 Hexo 创建的 blog 目录结构以及部分配置文件进行说明。
hexo version 5.0.0
更多信息可阅读官方 Hexo 文档。

# 目录结构

在初始化 hexo 后，根目录结构如下

.

├── _config.yml

├── package.json

├── scaffolds

├── source

|   ├── _drafts

|   └── _posts

└── themes

# _config.yml

网站的配置信息，在此配置大部分的参数，也可使用代替文件。

# 网站

其中， description 主要用于 SEO，告诉搜索引擎一个关于您站点的简单描述，通常建议在其中包含您网站的关键词。 author 参数用于主题显示文章的作者。

# 网址

网站存放在子目录
如果您的网站存放在子目录中，例如 http://example.com/blog，则请将您的 url 设为 http://example.com/blog 并把 root 设为 /blog/ 。
例如：
一个页面的永久链接是 http://example.com/foo/bar/index.html
pretty_urls:
trailing_index: false
此时页面的永久链接会变为 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' 的渲染

# 文章

相对地址
默认情况下，Hexo 生成的超链接都是绝对地址。例如，如果您的网站域名为 example.com，您有一篇文章名为 hello，那么绝对链接可能像这样：http://example.com/hello.html，它是绝对于域名的。相对链接像这样：/hello.html，也就是说，无论用什么域名访问该站点，都没有关系，这在进行反向代理时可能用到。通常情况下，建议使用绝对地址。

# 分类 & 标签

# 日期 / 时间格式

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

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' 。

# 分页

# 例如：

pagination_dir: 'page'        

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

pagination_dir: 'awesome-page'        

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

# 扩展

# 包括或不包括目录和文件

在 Hexo 配置文件中，通过设置 include/exclude 可以让 Hexo 进行处理或忽略某些目录和文件夹。你可以使用 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 文件的路径。例如：

# 用 'custom.yml' 代替 '_config.yml'

$ hexo server --config custom.yml

# 使用 'custom.yml' 和 'custom2.json'，优先使用 'custom3.yml'，然后是 'custom2.json'

$ hexo generate --config custom.yml,custom2.json,custom3.yml

当你指定了多个配置文件以后，Hexo 会按顺序将这部分配置文件合并成一个 _multiconfig.yml 。如果遇到重复的配置，排在后面的文件的配置会覆盖排在前面的文件的配置。这个原则适用于任意数量、任意深度的 YAML 和 JSON 文件。

例如，使用 --config 指定了两个自定义配置文件：

$ hexo generate --config custom.yml,custom2.json

如果 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 起提供

# _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"

  }

}

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

# package.json

应用程序的信息。EJS , Stylus 和 Markdown 渲染引擎 已默认安装，您可以自由移除。

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

模版 文件夹。当您新建文章时，Hexo 会根据 scaffold 来创建文件。

Hexo 的模板是指在新建的文章文件中默认填充的内容。例如，如果您修改 scaffold/post.md 中的 Front-matter 内容，那么每次新建一篇文章时都会包含这个修改。

# source

资源文件夹是存放用户资源的地方。除 _posts 文件夹之外，开头命名为 _ (下划线) 的文件 / 文件夹和隐藏的文件将会被忽略。Markdown 和 HTML 文件会被解析并放到 public 文件夹，而其他文件会被拷贝过去。

# themes

主题 文件夹。Hexo 会根据主题来生成静态页面。

# 基本操作

# 写作

你可以执行下列命令来创建一篇新文章或者新的页面。

$ hexo new [layout] <title>

您可以在命令中指定文章的布局（layout），默认为 post ，可以通过修改 _config.yml 中的 default_layout 参数来指定默认布局。

# 布局（Layout）

Hexo 有三种默认布局： post 、 page 和 draft 。在创建这三种不同类型的文件时，它们将会被保存到不同的路径；而您自定义的其他布局和 post 相同，都将储存到 source/_posts 文件夹。

禁用布局
如果你不希望一篇文章（post/page）使用主题处理，请在它的 front-matter 中设置 layout: false 。

# 文件名称

Hexo 默认以标题做为文件名称，但您可编辑 new_post_name 参数来改变默认的文件名称，举例来说，设为 :year-:month-:day-:title.md 可让您更方便的通过日期来管理文章。你可以使用以下占位符：

# 草稿

刚刚提到了 Hexo 的一种特殊布局： draft ，这种布局在建立时会被保存到 source/_drafts 文件夹，您可通过 publish 命令将草稿移动到 source/_posts 文件夹，该命令的使用方式与 new 十分类似，您也可在命令中指定 layout 来指定布局。

$ hexo publish [layout] <title>

草稿默认不会显示在页面中，您可在执行时加上 --draft 参数，或是在 _config.yml 中把 render_drafts 参数设为 true 来预览草稿。

# 模版（Scaffold）

在新建文章时，Hexo 会根据 scaffolds 文件夹内相对应的文件来建立文件，例如：

$ hexo new photo "My Gallery"

在执行这行指令时，Hexo 会尝试在 scaffolds 文件夹中寻找 photo.md ，并根据其内容建立文章，以下是您可以在模版中使用的变量：

# 支持的格式

Hexo 支持以任何格式书写文章，只要安装了相应的渲染插件。

例如，Hexo 默认安装了 hexo-renderer-marked 和 hexo-renderer-ejs ，因此你不仅可以用 Markdown 写作，你还可以用 EJS 写作。如果你安装了 hexo-renderer-pug ，你甚至可以用 Pug 模板语言书写文章。

只需要将文章的扩展名从 md 改成 ejs ，Hexo 就会使用 hexo-renderer-ejs 渲染这个文件，其他格式同。

# Front-matter

Front-matter 是文件最上方以 --- 分隔的区域，用于指定个别文件的变量，举例来说：

---

title: Hello World

date: 2023/12/13 20:46:25

---

以下是预先定义的参数，您可在模板中使用这些参数值并加以利用。

# 布局

根据 _config.yml 中 default_layout 的设置，默认布局是 post 。当文章中的布局被禁用 (layout: false) ，它将不会使用主题处理。然而，它仍然会被任何可用的渲染引擎渲染：如果一篇文章是用 Markdown 写的，并且安装了 Markdown 渲染引擎（比如默认的 hexo-renderer-marked )，它将被渲染成 HTML。

除非通过 disableNunjucks 设置或渲染引擎禁用，否则无论布局如何，标签插件总是被处理。

# 分类和标签

只有文章支持分类和标签，您可以在 Front-matter 中设置。在其他系统中，分类和标签听起来很接近，但是在 Hexo 中两者有着明显的差别：分类具有顺序性和层次性，也就是说 Foo , Bar 不等于 Bar , Foo ；而标签没有顺序和层次。

categories:

- Diary

tags:

- PS3

- Games

分类方法的分歧
如果您有过使用 WordPress 的经验，就很容易误解 Hexo 的分类方式。WordPress 支持对一篇文章设置多个分类，而且这些分类可以是同级的，也可以是父子分类。但是 Hexo 不支持指定多个同级分类。下面的指定方法：

categories:

  - Diary

  - Life

会使分类 Life 成为 Diary 的子分类，而不是并列分类。因此，有必要为您的文章选择尽可能准确的分类。

如果你需要为文章添加多个分类，可以尝试以下 list 中的方法。

categories:

- [Diary, PlayStation]

- [Diary, Games]

- [Life]

此时这篇文章同时包括三个分类： PlayStation 和 Games 分别都是父分类 Diary 的子分类，同时 Life 是一个没有子分类的分类。

# JSON Front-matter

除了 YAML 外，你也可以使用 JSON 来编写 Front-matter，只要将 --- 代换成 ;;; 即可。

"title": "Hello World",

"date": "2013/7/13 20:46:25"

;;;

# 标签插件（Tag Plugins）

标签插件和 Front-matter 中的标签不同，它们是用于在文章中快速插入特定内容的插件。
虽然你可以使用任何格式书写你的文章，但是标签插件永远可用，且语法也都是一致的。
标签插件不应该被包裹在 Markdown 语法中，例如： []({% post_path lorem-ipsum %}) 是不被支持的。

# 引用资源

引用文章的资源，与 资源文件夹 一起使用。

<!--swig3-->

<!--swig4-->

<!--swig5-->

# 嵌入图片

hexo-renderer-marked 3.1.0+ 可以（可选）自动解析图片的文章路径，参考 资源文件夹 章节。

“foo.jpg” 位于 http://example.com/2020/01/02/hello/foo.jpg 。

# 默认（无选项）

{% asset_img foo.jpg %}

<img src="/2020/01/02/hello/foo.jpg">

# 自定义 class 属性

{% asset_img post-image foo.jpg %}

<img src="/2020/01/02/hello/foo.jpg" class="post-image">

# 展示尺寸

{% asset_img foo.jpg 500 400 %}

<img src="/2020/01/02/hello/foo.jpg" width="500" height="400">

# title 和 alt 属性

{% asset_img logo.svg"lorem ipsum'dolor'"%}

<img src="/2020/01/02/hello/foo.jpg" title="lorem ipsum" alt="dolor">

# 文章摘要和截断

在文章中使用 <!-- more --> ，那么 <!-- more --> 之前的文字将会被视为摘要。首页中将只出现这部分文字，同时这部分文字也会出现在正文之中。

例如：

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.

首页中将只会出现

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

正文中则会出现

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

注意，摘要可能会被 Front Matter 中的 excerpt 覆盖。

# iframe

在文章中插入 iframe。

<!--swig10-->

# Image

在文章中插入指定大小的图片。

<!--swig11-->

# Link

在文章中插入链接，并自动给外部链接添加 target="_blank" 属性。

<!--swig12-->

# 资源文件夹

# 全局资源文件夹

资源（Asset）代表・・文件夹中除了文章以外的所有文件，例如图片、CSS、JS 文件等。比方说，如果你的 Hexo 项目中只有少量图片，那最简单的方法就是将它们放在 source/images 文件夹中。然后通过类似于 ![](/images/image.jpg) 的方法访问它们。

# 文章资源文件夹

对于那些想要更有规律地提供图片和其他资源以及想要将他们的资源分布在各个文章上的人来说，Hexo 也提供了更组织化的方式来管理资源。这个稍微有些复杂但是管理资源非常方便的功能可以通过将 config.yml 文件中的 post_asset_folder 选项设为 true 来打开。

#_config.yml

post_asset_folder: true

当资源文件管理功能打开后，Hexo 将会在你每一次通过 hexo new [layout] <title> 命令创建新文章时自动创建一个文件夹。这个资源文件夹将会有与这个文章文件一样的名字。将所有与你的文章有关的资源放在这个关联文件夹中之后，你可以通过相对路径来引用它们，这样你就得到了一个更简单而且方便得多的工作流。

# 相对路径引用的标签插件

通过常规的 markdown 语法和相对路径来引用图片和其它资源可能会导致它们在存档页或者主页上显示不正确。在 Hexo 2 时代，社区创建了很多插件来解决这个问题。但是，随着 Hexo 3 的发布，许多新的标签插件被加入到了核心代码中。这使得你可以更简单地在文章中引用你的资源。

<!--swig13-->

<!--swig14-->

<!--swig15-->

比如说：当你打开文章资源文件夹功能后，你把一个 example.jpg 图片放在了你的资源文件夹中，如果通过使用相对路径的常规 markdown 语法 ![](example.jpg) ，它将 不会 出现在首页上。（但是它会在文章中按你期待的方式工作）

正确的引用图片方式是使用下列的标签插件而不是 markdown ：

<!--swig16-->

通过这种方式，图片将会同时出现在文章和主页以及归档页中。

# 使用 Markdown 嵌入图片

hexo-renderer-marked 3.1.0 引入了一个新的选项，其允许你无需使用 asset_img 标签插件就可以在 markdown 中嵌入图片

如需启用：

_config.yml

post_asset_folder: true

marked:

  prependRoot: true

  postAsset: true

启用后，资源图片将会被自动解析为其对应文章的路径。
例如： image.jpg 位置为 /2020/01/02/foo/image.jpg ，这表示它是 /2020/01/02/foo/ 文章的一张资源图片， ![](image.jpg) 将会被解析为 <img src="/2020/01/02/foo/image.jpg"> 。

# 数据文件夹

有时您可能需要在主题中使用某些数据，而这些数据并不在文章内，并且是需要重复使用的，那么您可以考虑使用 Hexo 3.0 新增的「数据文件」功能。此功能会加载 source/_data 内的 YAML 或 JSON 文件，如此一来您便能在网站中复用这些文件了。

举例来说，在 source/_data 文件夹中新建 menu.yml 文件：

Home: /

Gallery: /gallery/

Archives: /archives/

您就能在模板中使用这些数据：

<% for (var link in site.data.menu) { %>

  <a href="<%= site.data.menu [link] %>"> <%= link %> </a>

<% } %>

渲染结果如下 :

<a href="/"> Home </a>

<a href="/gallery/"> Gallery </a>

<a href="/archives/"> Archives </a>

# 自定义

# 永久链接（Permalinks）

您可以在 _config.yml 配置中调整网站的永久链接或者在每篇文章的 Front-matter 中指定。

# 变量

除了下列变量外，您还可使用除了 :path 和 :permalink 之外 Front-matter 中的所有属性。

您可在 permalink_defaults 参数下调整永久链接中各变量的默认值：

permalink_defaults:

  lang: en

# 示例

# source/_posts/hello-world.md

title: Hello World

date: 2013-07-14 17:01:34

categories:

- foo

- bar

# source/_posts/lorem/hello-world.md

title: Hello World

date: 2013-07-14 17:01:34

categories:

- foo

- bar

# 多语种支持

若要建立一个多语种的网站，您可修改 new_post_name 和 permalink 参数，如下：

new_post_name: :lang/:title.md

permalink: :lang/:title/

当您建立新文章时，文章会被储存到：

$ hexo new "Hello World" --lang tw

# => source/_posts/tw/Hello-World.md

而网址会是 http://localhost:4000/tw/hello-world/

# 国际化（i18n）

若要让您的网站以不同语言呈现，您可使用国际化（internationalization）功能。请先在 _config.yml 中调整 language 设定，这代表的是预设语言，您也可设定多个语言来调整预设语言的顺位。

language: zh-tw

language: 

- zh-tw

- en

# 语言文件

语言文件可以使用 YAML 或 JSON 编写，并放在主题文件夹中的 languages 文件夹。您可以在语言文件中使用 printf 格式。

# 模板

在模板中，通过 __ 或 _p 辅助函数，即可取得翻译后的字符串，前者用于一般使用；而后者用于复数字符串。例如：

en.yml

index:

  title: Home

  add: Add

  video:

    zero: No videos

    one: One video

    other: % d videos

<%= __('index.title') %>

// Home

<%= _p ('index.video', 3) %>

// 3 videos

# 路径

您可在 front-matter 中指定该页面的语言，也可在 _config.yml 中修改 i18n_dir 设定，让 Hexo 自动侦测。

i18n_dir: :lang

i18n_dir 的预设值是 :lang ，也就是说 Hexo 会捕获网址中的第一段以检测语言，举例来说：

/index.html => en

/archives/index.html => en

/zh-tw/index.html => zh-tw

捕获到的字符串唯有在语言文件存在的情况下，才会被当作是语言，因此例二 /archives/index.html 中的 archives 就不被当成是语言。