Hexo 写作速查手册

写博客时最烦的不是内容，而是「那个字段名叫什么来着」「标签外挂怎么写的」。这篇把常用语法、Front-matter 字段和命令整理成一页速查表，写文章时打开复制即可。

一、写文章的完整流程

npx hexo new "文章标题"        # 新建文章 → source/_posts/文章标题.md
# 编辑 Markdown 内容
npx hexo server                # 本地预览 http://localhost:4000，保存即刷新
npx hexo clean && npx hexo g && npx hexo d    # 生成并部署

想先写不发布：

1
2
3

npx hexo new draft "草稿标题"  # 到 source/_drafts/
npx hexo server --draft        # 预览草稿
npx hexo publish "草稿标题"    # 正式发布

二、Front-matter 字段速查

文件顶部 --- 之间的是 Front-matter，决定文章的元信息。

---
title: 文章标题
date: 2024-01-05 16:09:01     # 发布时间
updated: 2024-02-01 10:00:00  # 更新时间（可省略）
categories:
  - 前端开发                   # 只能有一个层级时写单个；支持多级
tags:
  - React
  - 前端
cover: /img/cover.jpg          # 封面图
description: 一句话摘要         # SEO 与列表页显示，很重要
slug: react-study-notes        # 自定义 URL 片段
abbrlink: 7b2d9f36             # 短链接（需 hexo-abbrlink）
sticky: 1                      # 置顶，数字越大越靠前
swiper_index: 1                # 出现在首页轮播（需 butterfly-swiper）
comments: true                 # 单篇开关评论
toc: true                      # 显示目录
top_img: false                 # 关闭头图
keywords: React, Hooks         # 关键词（部分主题/SEO 插件用）
---

categories 与 tags 的写法区别：一篇文章通常只有一个分类，但可以有多个标签。Butterfly 里分类写多个会形成层级（父分类 → 子分类），不是并列关系。

三、Markdown 语法速查

效果	语法
标题	`# 一级` `## 二级` … `###### 六级`
加粗 / 斜体	`粗体` / `斜体`
删除线	`~~删除~~`
行内代码	`code`
代码块	三个反引号 + 语言名（如 ```js）
链接	`[文字](https://url)`
图片	`![说明](/img/a.png)`
引用	`> 内容`
无序列表	`- 项`
有序列表	`1. 项`
任务列表	`- [x] 已完成` / `- [ ] 未完成`
表格	`
分割线	`---`
脚注	`正文[^1]` + `[^1]: 注释内容`
转义	`\#` 输出 # 而不是标题

代码块示例（务必标注语言，才有语法高亮）：

1
2
3

```js
const a = 1
```

四、Butterfly 专属标签外挂

这是 Butterfly 比普通 Markdown 好看的关键，写在正文里即可。

提示框 note

{% note info %}普通提示{% endnote %}
{% note success %}成功 / 推荐做法{% endnote %}
{% note warning %}注意事项{% endnote %}
{% note danger %}危险操作警告{% endnote %}

样式（可选，加在类型后面）：simple / modern / flat / disabled，还可加图标：

1
2
3

{% note success flat %}
支持多行内容与 **Markdown** 语法
{% endnote %}

折叠块 hide

{% hideInline 被隐藏的内容, 点击显示 %}
{% hideBlock 折叠标题 %}
里面可以是任意 Markdown
{% endhideBlock %}

标签页 tabs

{% tabs 标签组名 %}
<!-- tab macOS@fab fa-apple -->
内容一
<!-- endtab -->
<!-- tab Windows@fab fa-windows -->
内容二
<!-- endtab -->
{% endtabs %}

第二个参数是默认激活第几个（从 0 开始）。

彩色标签 label

{% label 文字 default %}   {% label 蓝色 blue %}
{% label 粉色 pink %}       {% label 红色 red %}
{% label 紫色 purple %}     {% label 橙色 orange %}
{% label 绿色 green %}

按钮 btn

1	{% btn https://example.com, 按钮文字, fas fa-download, outline orange center %}

参数依次是：链接、文字、图标、样式（颜色 + outline / center / block / larger）。

时间线 timeline

{% timeline 标题 %}
<!-- timeline 2024-01-01 -->
第一件事
<!-- endtimeline -->
<!-- timeline 2024-06-01 -->
第二件事
<!-- endtimeline -->
{% endtimeline %}

其它

{% mermaid %}...{% endmermaid %} —— 流程图 / 时序图（需在主题配置里启用 mermaid）
{% gallery %} —— 图片画廊
{% flink %} —— 友情链接卡片

五、图片怎么插

方式	写法	适用
本地相对路径	`![](/img/a.png)`	放 `source/img/`，最稳
文章同目录	`![](a.png)`	需开启 `post_asset_folder`
图床	`![](https://cdn.../a.png)`	推荐，本站用的 PicGo + GitHub

用图床时建议顺手压缩：照片转 WebP、图标用 SVG。一张 1MB 的图会让首屏明显变慢。

六、命令速查

命令	作用
`hexo new "标题"`	新建文章
`hexo new page "xxx"`	新建页面（tags / categories / about）
`hexo clean`（`hexo cl`）	清除缓存，改配置后必做
`hexo generate`（`hexo g`）	生成静态文件到 `public/`
`hexo server`（`hexo s`）	本地预览
`hexo deploy`（`hexo d`）	部署
`hexo g -d`	生成并部署（合并两步）
`hexo list`	列出所有文章/页面
`hexo --draft`	显示草稿