Hexo-Fluid写作指南

引言

本文记录Hexo-Fluid主题的写作技巧，内容包含了Markdown、HTML和IMG三个大类。需要注意因为主题转变的原因部分标签无法使用，但对于博客写作仍有共同之处和参考价值。

MarkDown

文章在首页的封面图

对于单篇文章，在文章开头 Front-matter (opens new window)中配置 index_img 属性。

---
title: 文章标题
tags: [Hexo, Fluid]
index_img: /img/example.jpg
date: 2019-10-10 10:00:00
---
以下是文章内容

和 Banner 配置相同，/img/example.jpg 对应的是存放在 /source/img/example.jpg 目录下的图片（目录也可自定义，但必须在 source 目录下）。

也可以使用外链 Url 的绝对路径。

如果想统一给文章设置一个默认图片（文章不设置 index_img 则默认使用这张图片），可在主题配置中设置：

post:
  default_index_img: /img/example.jpg

当 default_index_img 和 index_img 都为空时，该文章在首页将不显示图片。

文章页顶部大图

默认显示主题配置中的 post.banner_img，如需要设置单个文章的 Banner，在 Front-matter (opens new window)中指定 banner_img 属性。

本地图片存放位置同上。

---
title: 文章标题
tags: [Hexo, Fluid]
index_img: /img/example.jpg
banner_img: /img/post_banner.jpg
date: 2019-10-10 10:00:00
---
以下是文章内容

文章内容图片

本地图片存放位置同上。

![](/img/example.jpg)

日期/字数/阅读时长/阅读数

显示在文章页大标题下的文章信息，除了作者和阅读次数，其他功能都是默认开启的。

post:
  meta:
    author:  # 作者，优先根据 front-matter 里 author 字段，其次是 hexo 配置中 author 值
      enable: false
    date:  # 文章日期，优先根据 front-matter 里 date 字段，其次是 md 文件日期
      enable: true
      format: "dddd, MMMM Do YYYY, h:mm a"  # 格式参照 ISO-8601 日期格式化
    wordcount:  # 字数统计
      enable: true
      format: "{} 字"  # 显示的文本，{}是数字的占位符（必须包含)，下同
    min2read:  # 阅读时间
      enable: true
      format: "{} 分钟"
    views:  # 阅读次数
      enable: false
      source: "leancloud"  # 统计数据来源，可选：leancloud | busuanzi   注意不蒜子会间歇抽风
      format: "{} 次"

TIP

日期格式必须遵循 ISO-8601 规范，否则无法正常显示；

其他格式必须包括 {} 符号代替数字，文字可自由设置。

代码块

code:
  copy_btn: true
  highlight:
    enable: true
    lib: "highlightjs"
    highlightjs:
      style: 'Github Gist'
      bg_color: false
    prismjs:
      style: "default"
      preprocess: true

copy_btn: 是否开启复制代码的按钮

highlight: 是否开启代码高亮

lib: 选择生成高亮的库，可选项: highlightjs、prismjs，对应下面两组配置，高亮的配置说明具体见主题配置中的注释

WARNING

高亮暂不支持行号

评论

开启评论需要在主题配置中开启并指定评论模块：

post:
  comments:
    enable: true
    type: disqus

然后在下方还要设置对应评论模块的参数，比如 disqus 对应设置：

disqus:
  shortname: fluid

当前支持 Valine、Disqus、Gitalk、Utterances、畅言、来必力(livere)、Remark42、twikoo，使用和参数设置需要自行查询各自的文档（文档地址在配置注释里）。

若需要自定义添加其他评论系统，请自行在 fluid/layout/_partial/comments/ 目录内创建 ejs 文件，参照自带的 ejs 填入评论服务商提供的代码，再修改 post.comments.type 为对应文件名。

TIP

国内用户推荐使用 Valine 或者 Utterances

如果设置后评论模块没有显示，说明配置没有完成，或者配置有误出现报错（请在浏览器控制台查看具体报错）

如果想在某个文章页关闭评论，或者想在某个自定义页面开启评论，可以通过在 Front-matter (opens new window)设置 comment: bool 来控制，例如在关于页开启评论：

---
title: 关于页
layout: about
index_img: /img/example.jpg
date: 2019-10-10 10:00:00
comment: true
---
以下是正文内容

脚注

主题内置了脚注语法支持，可以在文章末尾自动生成带有锚点的脚注，该功能在主题配置中默认开启：

post:
  footnote:
    enable: true
    header: ''

脚注语法如下：

这是一句话[^1]
[^1]: 这是对应的脚注

更优雅的使用方式，是将脚注写在文末，比如：

正文

## 参考
[^1]: 参考资料1
[^2]: 参考资料2

当然你也可以通过修改上方配置项 header 来自动加入节标题，如下所示：

post:
  footnote:
    enable: true
    header: '<h2>参考</h2>'  # 等同于手动写 `## 参考`

Tag 插件

WARNING

所有 Tag 仍在测试中，后续版本可能会修改

便签

在 markdown 中加入如下的代码来使用便签：

{% note success %}
文字 或者 `markdown` 均可
{% endnote %}

或者使用 HTML 形式：

<p class="note note-primary">标签</p>

可选便签：

primary

secondary

success

danger

warning

info

light

WARNING

使用时 {% note primary %}` 和 `{% endnote %} 需单独一行，否则会出现问题

行内标签

在 markdown 中加入如下的代码来使用 Label：

{% label primary @text %}

或者使用 HTML 形式：

<span class="label label-primary">Label</span>

可选 Label：

primary default info success warning danger

WARNING

若使用 {% label primary @text %}，text 不能以 @ 开头

勾选框

在 markdown 中加入如下的代码来使用 Checkbox：

{% cb text, checked?, incline? %}

text：显示的文字
checked：默认是否已勾选，默认 false
incline: 是否内联（可以理解为后面的文字是否换行），默认 false

按钮

你可以在 markdown 中加入如下的代码来使用 Button：

{% btn url, text, title %}

或者使用 HTML 形式：

<a class="btn" href="url" title="title">text</a>

url：跳转链接
text：显示的文字
title：鼠标悬停时显示的文字（可选）

text

组图

如果想把多张图片按一定布局组合显示，你可以在 markdown 中按如下格式：

{% gi total n1-n2-... %}
  ![](url)
  ![](url)
  ![](url)
  ![](url)
  ![](url)
{% endgi %}

total：图片总数量，对应中间包含的图片 url 数量
n1-n2-…：每行的图片数量，可以省略，默认单行最多 3 张图，求和必须相等于 total，否则按默认样式

如下图为 {% gi 5 3-2 %} 示例，代表共 5 张图，第一行 3 张图，第二行 2 张图。

LaTeX 数学公式

Hexo 5.0 以上，可尝试 Hexo 官方的 [hexo-math](https://github.com/hexojs/hexo-math) 插件，支持更多定制化参数，使用方式参照仓库内的文档，以下介绍的是主题内置的 LaTeX 功能。

当需要使用 LaTeX (opens new window)语法的数学公式时，可手动开启本功能，需要完成三步操作：

1. 设置主题配置

post:
  math:
    enable: true
    specific: false
    engine: mathjax

specific: 建议开启。当为 true 时，只有在文章 Front-matter (opens new window)里指定 math: true 才会在文章页启动公式转换，以便在页面不包含公式时提高加载速度。

engine: 公式渲染引擎，目前支持 mathjax 或 katex。

2. 更换 Markdown 渲染器

由于 Hexo 默认的 Markdown 渲染器不支持复杂公式，所以必须更换渲染器。

先卸载原有渲染器：

npm uninstall hexo-renderer-marked --save

然后根据上方配置不同的 engine，推荐更换如下渲染器：

mathjax: npm install hexo-renderer-kramed --save

katex: npm install @upupming/hexo-renderer-markdown-it-plus --save

3. 安装完成后执行 hexo clean

WARNING

不可同时安装多个渲染器，如果更换公式引擎，对应渲染器也要一并更换。

如果公式没有被正确渲染，请仔细检查是否符合上面三步操作。

另外不同的渲染器，可能会导致一些 Markdown 语法不支持。

自定义页面默认不加载渲染，如需使用，需在 Front-matter 中指定 math: true

TIP

不同的公式引擎有不同的优缺点。

MathJax

优点

• 对 LaTeX 语法支持全面
• 右键点击公式有扩展功能

缺点

• 需要加载 JS，页面加载会比较慢，并且有渲染变化
• kramed 渲染器对内联公式的转义字符 \ 支持不足

KaTeX

优点

• 没有 JS 不会影响页面加载
• 渲染器效果好 (相对 kramed 对 MathJax 的内联公式)

缺点

• 小部分 LaTeX 不支持

Mermaid 流程图

当需要使用 Mermaid (opens new window)渲染流程图时，可手动开启本功能：

post:
  mermaid:
    enable: true
    specific: false
    options:

specific: 建议开启。当为 true 时，只有在文章 Front-matter (opens new window)里指定 mermaid: true 才会在文章页启动流程图渲染，以便在页面不包含流程图时提高加载速度。

options: 官方 API 的配置项，具体可见 mermaidAPI.js(opens new window)

TIP

自定义页面默认不加载，如需使用，需在 Front-matter 中指定 mermaid: true

使用 Mermaid 可以通过内置的 Tag 书写：

{% mermaid %}
gantt
dateFormat  YYYY-MM-DD
title Adding GANTT diagram to mermaid

section A section
Completed task            :done,    des1, 2014-01-06,2014-01-08
Active task               :active,  des2, 2014-01-09, 3d
Future task               :         des3, after des2, 5d
Future task2               :         des4, after des3, 5d
{% endmermaid %}

也可以通过代码块书写：

```mermaid
classDiagram
Class01 <|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label

HTML

我们可以在 Markdown 中插入一些简单的 HTML 代码或 CSS 片段来获得更多扩展，使得文章内容更具有多样性。以下演示几个简单功能。

跳转位置演示（跳转位置设置点）

文字颜色

#519D9E颜色演示

<span  style="color: #519D9E; ">#519D9E颜色演示</span>

文字大小

0.7em 文字大小演示

<span  style="font-size:0.7em;">0.7em 文字大小演示</span>

文字位置

内容居中演示

<p style="text-align:center">内容居中演示</p> # 可以修改 text-align 参数来设置文字位置。

页内跳转

点击到达跳转位置演示
跳转位置演示（跳转位置设置点）

<a href="#demo">点击到达跳转位置演示</a> # 在需要跳转的地方添加此代码。
<a id="demo">跳转位置演示（跳转位置设置点）</a> # 在跳转位置添加次代码。

综合演示

综合演示
优雅使用 Fluid 写文章

<p style="text-align:center;color:#8EC0E4;font-size:1.5em;font-weight: bold;">
综合演示
<br>
优雅使用 Fluid 写文章
</p>

iframe 页面镶套

iframe 页面镶套可以帮助我们更好的展示一个页面。比如以下演示页面。

<iframe src="https://hexo.fluid-dev.com/" width="100%" height="500" name="topFrame" scrolling="yes"  noresize="noresize" frameborder="0" id="topFrame"></iframe>

一些参数说明，width="100%" 为宽度自适应，高度请根据实际需求跳转，注意移动端页面是否匹配。 scrolling 为滚动条参数。frameborder 为边框参数。noresize 属性规定用户无法调整框架的大小。

details 标签

用于展示代码较多需要折叠或折叠相关内容，以下为演示。summary 填写显示名称。

Demo

<details>
<summary>Demo</summary>
<p><b>好友申请备注：fluid</b></p>
<p><b>提问之前请先仔细查阅用户文档</b></p>
<img width="200" src="https://cdn.jsdelivr.net/gh/fluid-dev/static@master/hexo-theme-fluid/wechat.png" alt="wechat">
</details>

善用 Tag 组件

Fluid 内置了许多 Tag 组件，包含便签、行内标签（已知不会出现间隔，谨慎使用）、勾选框、按钮和组图，可以使用这些组件来丰富文章内容，具体点击查看官方文档查看，**点击跳转到 Fluid Doc**。

IMG

众所周知，博客好不好看，配图占一半。这里给大家推荐几个我常用找配图的地方。另外，请遵循相关网站的版权协议。

Wallpaper Hub

点击跳转到 Wallpaper Hub

Wallhaven

点击跳转到 Wallhaven

Unsplash

点击跳转到 Unsplash