Hexo写作基本说明

内容参考 文档 | Hexo

文件布局

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

$ hexo new [layout] <title>

布局 (Layout)

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

布局	路径
post	source/_posts
page	source
draft	source/_drafts

禁用布局

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

文件名称

• 默认以标题做为文件名称

• 可编辑 new_post_name 参数来改变默认的文件名称

  • 举例来说，设为 :year-:month-:day-:title.md 可更方便的通过日期来管理文章

  • 可以使用以下占位符

变量	描述
:title	标题（小写，空格将会被替换为短杠）
:year	建立的年份，比如， 2015
:month	建立的月份（有前导零），比如， 04
:i_month	建立的月份（无前导零），比如， 4
:day	建立的日期（有前导零），比如， 07
:i_day	建立的日期（无前导零），比如， 7

草稿

• 特殊布局：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，并根据其内容建立文章

• 可以在模版中使用的变量

变量	描述
layout	布局
title	标题
date	文件建立日期

Front-matter

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

---
title: Hello World
date: 2013/7/13 20:46:25
---

Post Front-matter

---
title:
date:
updated:
tags:
categories:
keywords:
description:
top_img:
comments:
cover:
toc:
toc_number:
toc_style_simple:
copyright:
copyright_author:
copyright_author_href:
copyright_url:
copyright_info:
mathjax:
katex:
aplayer:
highlight_shrink:
aside:
abcjs:
---

写法	解释
title	==【必需】== 文章标题
date	==【必需】== 文章创建日期
updated	【可选】文章更新日期
tags	【可选】文章标签
categories	【可选】文章分类
keywords	【可选】文章关键字
description	【可选】文章描述
top_img	【可选】文章顶部图片
cover	【可选】文章缩略图(如果没有设置 top_img, 文章页顶部将显示缩略图，可设为 false/图片地址/留空)
comments	【可选】显示文章评论模块(默认 true)
toc	【可选】显示文章 TOC(默认为设置中 toc 的 enable 配置)
toc_number	【可选】显示 toc_number(默认为设置中 toc 的 number 配置)
toc_style_simple	【可选】显示 toc 简洁模式
copyright	【可选】显示文章版权模块(默认为设置中 post_copyright 的 enable 配置)
copyright_author	【可选】文章版权模块的 文章作者
copyright_author_href	【可选】文章版权模块的 文章作者 链接
copyright_url	【可选】文章版权模块的 文章连结 链接
copyright_info	【可选】文章版权模块的 版权声明 文字
mathjax	【可选】显示 mathjax(当设置 mathjax 的 per_page: false 时，才需要配置，默认 false )
katex	【可选】显示 katex (当设置 katex 的 per_page: false 时，才需要配置，默认 false )
aplayer	【可选】在需要的页面加载 aplayer 的 js 和 css, 请参考文章下面的 音乐 配置
highlight_shrink	【可选】配置代码框是否展开(true/false)(默认为设置中 highlight_shrink 的配置)
aside	【可选】显示侧边栏 (默认 true)
abcjs	【可选】加载 abcjs (当设置 abcjs 的 per_page: false 时，才需要配置，默认 false )

Page Front-matter

---
title:
date:
updated:
type:
comments:
description:
keywords:
top_img:
mathjax:
katex:
aside:
aplayer:
highlight_shrink:
random:
---

写法	解释
title	==【必需】== 页面标题
date	==【必需】== 页面创建日期
type	==【必需】== 标签、分类和友情链接三个页面需要配置
updated	【可选】页面更新日期
description	【可选】页面描述
keywords	【可选】页面关键字
comments	【可选】显示页面评论模块 (默认 true)
top_img	【可选】页面顶部图片
mathjax	【可选】显示 mathjax (当设置 mathjax 的 per_page: false 时，才需要配置，默认 false)
katex	【可选】显示 katex (当设置 katex 的 per_page: false 时，才需要配置，默认 false)
aside	【可选】显示侧边栏 (默认 true)
aplayer	【可选】在需要的页面加载 aplayer 的 js 和 css, 请参考文章下面的 音乐 配置
highlight_shrink	【可选】配置代码框是否展开 (true/false) (默认为设置中 highlight_shrink 的配置)
random	【可选】配置友情链接是否随机排序（默认为 false)

预定义参数

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

参数	描述	默认值
layout	布局	config.default_layout
title	标题	文章的文件名
date	建立日期	文件建立日期
updated	更新日期	文件更新日期
comments	开启文章的评论功能	true
tags	标签（不适用于分页）
categories	分类（不适用于分页）
permalink	覆盖文章的永久链接，永久链接应该以 / 或 .html 结尾	null
excerpt	纯文本的页面摘要。使用 该插件 来格式化文本
disableNunjucks	启用时禁用 Nunjucks 标签 {{ }}/{% %} 和 标签插件 的渲染功能	false
lang	设置语言以覆盖 自动检测	继承自 _config.yml
published	文章是否发布	对于 _posts 下的文章为 true，对于 _draft 下的文章为 false

布局

• 根据 _config.yml 中 default_layout 的设置，默认布局是 post 。当文章中的布局被禁用(layout: false)，它将不会使用主题处理

  • 然而，它仍然会被任何可用的渲染引擎渲染：

    • 如果一篇文章是用 Markdown 写的，并且安装了 Markdown 渲染引擎（比如默认的 hexo-renderer-marked)，它将被渲染成 HTML。

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

分类和标签

只有文章支持分类和标签

• 分类具有顺序性和层次性
  • 也就是说 Foo, Bar 不等于 Bar, Foo

• 标签没有顺序和层次

• 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"
  ;;;

主题页面

分类

只有文章支持分类和标签

• 分类具有顺序性和层次性

  • 也就是说 Foo, Bar 不等于 Bar, Foo

  ---
  title: 分类
  date: 2018-01-05 00:00:00
  type: "categories"
  ---

标签

• 标签没有顺序和层次

  ---
  title: 标签
  date: 2018-01-05 00:00:00
  type: "tags"
  orderby: random
  order: 1
  ---

参数	解释
type	【必须】页面类型，必须为 tags
orderby	【可选】排序方式 ：random/name/length
order	【可选】排序次序： 1, asc for ascending; -1, desc for descending

友情链接

创建

• hexo new page link

  • 生成 source/link/index.md 文件

    ---
    title: 友情链接
    date: 2018-06-07 22:17:49
    type: "link"
    ---

添加

本地生成

• 在 Hexo 博客目录中的 source/_data（如果没有 _data 文件夹，请自行创建），创建一个文件 link.yml

  - class_name: 友情链接
    class_desc: 那些人，那些事
    link_list:
      - name: Hexo
        link: https://hexo.io/zh-tw/
        avatar: https://d33wubrfki0l68.cloudfront.net/6657ba50e702d84afb32fe846bed54fba1a77add/827ae/logo.svg
        descr: 快速、简单且强大的网志框架
  
  - class_name: 网站
    class_desc: 值得推荐的网站
    link_list:
      - name: Youtube
        link: https://www.youtube.com/
        avatar: https://i.loli.net/2020/05/14/9ZkGg8v3azHJfM1.png
        descr: 视频网站
      - name: Weibo
        link: https://www.weibo.com/
        avatar: https://i.loli.net/2020/05/14/TLJBum386vcnI1P.png
        descr: 中国最大社交分享平台
      - name: Twitter
        link: https://twitter.com/
        avatar: https://i.loli.net/2020/05/14/5VyHPQqR6LWF39a.png
        descr: 社交分享平台

• class_name 和 class_desc 支持 html 格式书写，如不需要，也可以留空。

远程拉取

从 4.0.0 开始，支持从远程加载友情链接，远程拉取只支持 json。

注意： 选择远程加载后，本地生成的方法会无效。

• source/link/index.md 这个文件的 front-matter 添加远程链接

  flink_url: xxxxx

• Json 格式示例

  [
    {
      "class_name": "友情链接",
      "class_desc": "那些人，那些事",
      "link_list": [
        {
          "name": "Hexo",
          "link": "https://hexo.io/zh-tw/",
          "avatar": "https://d33wubrfki0l68.cloudfront.net/6657ba50e702d84afb32fe846bed54fba1a77add/827ae/logo.svg",
          "descr": "快速、简单且强大的网志框架"
        }
      ]
    },
    {
      "class_name": "网站",
      "class_desc": "值得推荐的网站",
      "link_list": [
        {
          "name": "Youtube",
          "link": "https://www.youtube.com/",
          "avatar": "https://i.loli.net/2020/05/14/9ZkGg8v3azHJfM1.png",
          "descr": "视频网站"
        },
        {
          "name": "Weibo",
          "link": "https://www.weibo.com/",
          "avatar": "https://i.loli.net/2020/05/14/TLJBum386vcnI1P.png",
          "descr": "中国最大社交分享平台"
        },
        {
          "name": "Twitter",
          "link": "https://twitter.com/",
          "avatar": "https://i.loli.net/2020/05/14/5VyHPQqR6LWF39a.png",
          "descr": "社交分享平台"
        }
      ]
    }
  ]

随机排序

• 主题支持友情链接随机排序，只需要在顶部 front-matter 添加 random: true

界面设置

• 由 2.2.0 起，友情链接界面可以由用户自己自定义，只需要在友情链接的 md 档设置就行，以普通的 Markdown 格式书写。

图库

• 创建： hexo n page xxxxx 创建页面

• 使用 galleryGroup 外挂标签

  <div class="gallery-group-main">
  {% galleryGroup '壁纸' '收藏的一些壁纸' '/Gallery/wallpaper' https://i.loli.net/2019/11/10/T7Mu8Aod3egmC4Q.png %}
  {% galleryGroup '漫威' '关于漫威的图片' '/Gallery/marvel' https://i.loli.net/2019/12/25/8t97aVlp4hgyBGu.jpg %}
  {% galleryGroup 'OH MY GIRL' '关于OH MY GIRL的图片' '/Gallery/ohmygirl' https://i.loli.net/2019/12/25/hOqbQ3BIwa6KWpo.jpg %}
  </div>

子页面

• 子页面是普通的页面，只需要 hexo n page xxxxx 创建页面即可

  {% gallery %}
  ![](https://i.loli.net/2019/12/25/Fze9jchtnyJXMHN.jpg)
  ![](https://i.loli.net/2019/12/25/ryLVePaqkYm4TEK.jpg)
  ![](https://i.loli.net/2019/12/25/gEy5Zc1Ai6VuO4N.jpg)
  ![](https://i.loli.net/2019/12/25/d6QHbytlSYO4FBG.jpg)
  ![](https://i.loli.net/2019/12/25/6nepIJ1xTgufatZ.jpg)
  ![](https://i.loli.net/2019/12/25/E7Jvr4eIPwUNmzq.jpg)
  ![](https://i.loli.net/2019/12/25/mh19anwBSWIkGlH.jpg)
  ![](https://i.loli.net/2019/12/25/2tu9JC8ewpBFagv.jpg)
  {% endgallery %}

404 页面

# A simple 404 page
# ./config.yml
error_404:
  enable: true
  subtitle: "页面没有找到"
  background:

标签插件

标签插件和 Front-matter 中的标签不同，它们是用于在文章中快速插入特定内容的插件

• 标签插件不应该被包裹在 Markdown 语法中，例如： []({% post_path lorem-ipsum %}) 是不被支持的

引用块 quote

在文章中插入引言，可包含作者、来源和标题

{% blockquote [author[, source]] [link] [source_link_title] %}
content
{% endblockquote %}

无参数

• 只输出普通的 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 David Levithan, Wide Awake %}
  Do not just seek happiness for yourself. Seek happiness for all. Through kindness. Through mercy.
  {% endblockquote %}

  

Twitter

• 附加来源链接

  {% blockquote @DevDocs https://twitter.com/devdocs/status/356095192085962752 %}
  NEW: DevDocs now comes with syntax highlighting. http://devdocs.io
  {% 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

在文章中插入代码

{% codeblock [title] [lang:language] [url] [link text] [additional options] %}
code snippet
{% endcodeblock %}

以 option:value 的格式指定额外选项，例如：line_number:false first_line:5

额外选项	描述	默认值
line_number	显示行号	true
line_threshold	只有代码块的行数超过该阈值，才显示行数	0
highlight	启用代码高亮	true
first_line	指定第一个行号	1
mark	突出显示特定的行，每个值用逗号分隔。 使用破折号指定数字范围 例如： mark:1,4-7,10 将标记第 1、4 至 7 和 10 行
wrap	用 <table> 包裹代码块	true

普通代码块

{% codeblock %}
alert('Hello World!');
{% endcodeblock %}

指定语言

{% codeblock lang:objc %}
[rectangle setX: 10 y: 10 width: 20 height: 20];
{% endcodeblock %}

附加说明

{% codeblock Array.map %}
array.map(callback[, thisArg])
{% endcodeblock %}

附加说明和网址

{% codeblock _.compact http://underscorejs.org/#compact Underscore.js %}
\_.compact([0, 1, false, 2, '', 3]);
=> [1, 2, 3]
{% endcodeblock %}

反引号代码块

另一种形式的代码块，不同的是它使用三个反引号来包裹。

`[language] [title] [url] [link text] code snippet`

iframe

在文章中插入 iframe

{% iframe url [width] [height] %}

Image

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

{% img [class names] /path/to/image [width] [height] '"title text" "alt text"' %}

Link

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

{% link text url [external] [title] %}

Include Code

插入 source/downloads/code 文件夹内的代码文件

source/downloads/code 不是固定的，取决于你在配置文件中 code_dir 的配置

全文

• 嵌入 test.js 文件全文

{% include_code lang: javascript test.js %}

指定行

• 只嵌入第 3 行

  {% include_code lang: javascript from: 3 to: 3 test.js %}

• 嵌入第 5 行至第 8 行

  {% include_code lang: javascript from: 5 to: 8 test.js %}

• 嵌入第 5 行至文件结束

  {% include_code lang: javascript from: 5 test.js %}

• 嵌入第 1 行至第 8 行

  {% include_code lang: javascript to: 8 test.js %}

引用文章

引用其他文章的链接

{% post_path filename %}
{% post_link filename [title] [escape] %}

在使用此标签时可以忽略文章文件所在的 路径 或者文章的 永久链接信息、如 语言、日期

例如，在文章中使用 {% post_link how-to-bake-a-cake %} 时，只需有一个名为 how-to-bake-a-cake.md 的文章文件即可。即使这个文件位于站点文件夹的 source/posts/2015-02-my-family-holiday 目录下、或者文章的永久链接是 2018/en/how-to-bake-a-cake，都没有影响

• 链接使用文章的标题

  {% post_link hexo-3-8-released %}

  • 

• 链接使用自定义文字

  {% post_link hexo-3-8-released '通往文章的链接' %}

  • 

• 对标题的特殊字符进行转义

  {% post_link hexo-4-released 'How to use <b> tag in title' %}

  • 

• 禁止对标题的特殊字符进行转义

  {% post_link hexo-4-released '<b> bold </b> custom title' false %}

  • 

引用资源

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

{% asset_path filename %}
{% asset_img [class names] slug [width] [height] [title text [alt text]] %}
{% asset_link filename [title] [escape] %}

嵌入图片

• 默认（无选项）

  {% 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="do

URL

url_for (7.0.0+)

返回一个带有根路径前缀的 URL。输出将会自动编码。

{% url_for text path [relative] %}

示例

• 基本路径

  \_config.yml
  root: /blog/ # example

  {% url_for blog index.html %}
  
  渲染为
  
  <a href="/blog/index.html">blog</a>

• 是否输出相对链接，默认遵循配置文件中 relative_link 的值

  • 例如， post/page 的路径值可能是 /foo/bar/index.html

    \_config.yml
    relative_link: true

    {% url_for blog index.html %}
    
    渲染为
    
    <a href="../../index.html">blog</a>

• 即使配置文件中启用了 relative_link，你也可以使用 relative 参数禁用相对链接输出，反之亦然

  {% url_for blog index.html false %}
  
  渲染为
  
  <a href="/index.html">blog</a>

full_url_for (7.0.0+)

返回一个以 config.url 为前缀的 URL。输出将会自动编码。

{% full_url_for text path %}

• 示例：

  \_config.yml
  url: https://example.com/blog # example

  {% full_url_for index /a/path %}
  
  渲染为
  
  <a href="https://example.com/blog/a/path">index</a>

Raw

在文章中插入 Swig 标签，以免发生解析异常

{% raw %}
content
{% endraw %}

文章摘要和截断

在文章中使用 <!-- 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. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

• 首页中将只会出现

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

• 正文中则会出现

  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  
  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

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

资源文件夹

全局资源文件夹

• 资源（Asset）代表 source 文件夹中除了文章以外的所有文件，例如图片、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> 命令创建新文章时自动创建一个文件夹。这个资源文件夹将会有与这个文章文件一样的名字。将所有与你的文章有关的资源放在这个关联文件夹中之后，你可以通过相对路径来引用它们，这样你就得到了一个更简单而且方便得多的工作流。

相对路径引用的标签插件

{% asset_path slug %}
{% asset_img slug [title] %}
{% asset_link slug [title] %}

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

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

{% asset_img example.jpg This is an example image %}

使用 Markdown 嵌入图片

• 无需使用 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>