基础篇

Front-matter 说明（简体中文版）

Front-matter 是 Markdown 文件最上方以 --- 分隔的区域，用于指定单个文件的变量。

  • Page Front-matter：用于页面配置
  • Post Front-matter：用于文章页配置

标注为可选的参数可根据自身需求添加，无需全部写在 Markdown 中。

页面 (Page) Front-matter

参数必填 / 可选说明
title必填页面标题
date必填页面创建日期
updated可选页面更新日期
type必填标签、分类和友情链接这三个页面需配置该参数
comments可选显示页面评论模块（默认 true）
description可选页面描述
keywords可选页面关键词
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）
limit.type可选配置说说显示数量的类型（date 或 num）
limit.value可选配置说说显示数量的数值

文章 (Post) Front-matter

参数必填 / 可选说明
title必填文章标题
date必填文章创建日期
updated可选文章更新日期
tags可选文章标签
categories可选文章分类
keywords可选文章关键词
description可选文章描述
top_img可选文章顶部图片
cover可选文章缩略图（未设置 top_img 时，文章页顶部显示该缩略图；可设为 false/ 图片地址 / 留空）
comments可选显示文章评论模块（默认 true）
toc可选显示文章目录（默认沿用主题配置中 toc 的 enable 设置）
toc_number可选显示目录编号（默认沿用主题配置中 toc 的 number 设置）
toc_style_simple可选启用目录简洁模式
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）
noticeOutdate可选启用文章过期提醒（默认沿用主题配置中 noticeOutdate 的 enable 设置）
swiper_index可选置顶优先级，数字越大优先级越高

Hexo 外挂标签汇总表格

标签类型标签名称 / 核心语法功能说明可直接使用的示例备注 / 前置要求
内置（无需安装）代码块 code增强原生 Markdown 代码块，支持指定语言、显示行号、隐藏代码语言标识{% code javascript [1,3] %}
const a = 10;
console.log(a);
function fn() {}
{% endcode %}		[1,3] 表示仅显示第 1、3 行（也可写 1-5 显示第 1 到 5 行），不写则显示全部行
内置（无需安装）图片 img增强原生 Markdown 图片语法，支持指定宽高、自定义 alt 文本{% img https://xxx/photo.jpg 400 300 "这是一张示例图片" "图片描述" %}语法格式：{% img 图片链接 宽度 高度 "alt文本" "标题文本" %}，宽高可省略（自适应）
内置（无需安装）链接 link增强原生 Markdown 链接，支持指定新窗口打开、添加额外属性{% link 我的博客 https://xxx.com _blank "noopener noreferrer" %}_blank 表示新窗口打开，后续属性为安全优化，可省略；格式：{% link 链接文本 链接地址 额外属性 %}
第三方（需安装）音乐嵌入 aplayer（hexo-tag-aplayer）嵌入网易云音乐、QQ 音乐、本地音频，支持自定义播放器样式{% aplayer "花海" "周杰伦" "https://xxx/huahai.mp3" "https://xxx/cover.jpg" %}1. 安装命令：npm install hexo-tag-aplayer --save2. 支持批量添加歌曲，兼容主流主题
第三方（需安装）视频嵌入 video（hexo-tag-video）嵌入本地视频或在线视频（MP4/WEBM 等格式），支持指定宽高{% video https://xxx/video.mp4 640 480 %}` | 1. 安装命令：`npm install hexo-tag-video --save`2. 本地视频放入 `source/images` 目录 | | 第三方（需安装） | 流程图 `mermaid`（hexo-filter-mermaid-diagrams） | 嵌入流程图、时序图、饼图等，无需外部截图，支持实时渲染 | `{% mermaid %}
flowchart LR
A[开始] --> B[执行操作]
B --> C[结束]
{% endmermaid %}` | 1. 安装命令：`npm install hexo-filter-mermaid-diagrams --save`2. 需在 Hexo 配置文件开启 mermaid 支持 | | 第三方（需安装） | 待办清单 `todo`（hexo-tag-todo） | 添加可勾选的待办事项，支持「已完成」和「未完成」两种状态 | `{% todo %} 未完成的待办事项1
{% todo done %} 已完成的待办事项2{% endtodo %}` | 1. 安装命令：`npm install hexo-tag-todo --save`2. 生成的清单自带勾选样式，主题兼容度高 | | 第三方（需安装） | 简洁卡片 `card`（hexo-tag-bootstrap-cards） | 制作带标题、内容、按钮的 Bootstrap 风格卡片，提升页面美观度 | `{% card "卡片标题" "卡片正文内容，支持简单 Markdown" "https://xxx.com" "按钮文本" %}` | 1. 安装命令：`npm install hexo-tag-bootstrap-cards --save`2. 依赖 Bootstrap 样式，部分主题需额外引入 | ### 一、行内文本标签（Inline Tags） | 标签名称 | 语法格式 | 功能说明 | 示例 | | -------- | --------------------- | ------------------------------------ | ------------------------------- | | **u** | `{% u 文本内容 %}` | 添加下划线文本 | `{% u 这是带下划线的文本 %}` | | **emp** | `{% emp 文本内容 %}` | 添加着重号（底纹）文本 | `{% emp 这是带着重号的文本 %}` | | **wavy** | `{% wavy 文本内容 %}` | 添加波浪线文本 | `{% wavy 这是带波浪线的文本 %}` | | **del** | `{% del 文本内容 %}` | 添加删除线文本 | `{% del 这是带删除线的文本 %}` | | **kbd** | `{% kbd 文本内容 %}` | 添加键盘按键样式文本 | `{% kbd Ctrl+C %}` | | **psw** | `{% psw 文本内容 %}` | 添加密码隐藏效果文本（鼠标悬浮显示） | `{% psw 这是隐藏的密码 %}` | ------ ### 二、块级容器标签（Block Containers） | 标签名称 | 语法格式 | 功能说明 | 示例 | | -------- | ------------------------------------------------------------ | --------------------------------------- | ------------------------------------------------------------ | | **note** | `{% note [class] [no-icon] [style] %} 内容 {% endnote %}` | 提示块容器，支持 6 种预设样式 | `{% note success %} 操作成功提示 {% endnote %}` | | **tabs** | `{% tabs [分组名] [index] %}
内容1
内容2
{% endtabs %}` | 选项卡切换面板，`index`指定默认激活标签 | `{% tabs test1 %}

**This is Tab 1.**



**This is Tab 2.**



**This is Tab 3.**

{% endtabs %}` | ------ ### 三、媒体内容标签（Media Tags） | 标签名称 | 语法格式 | 功能说明 | 示例 | | ----------- | ------------------------------------------------------------ | ------------------------------------- | ------------------------------------------------------------ | | **gallery** | `{% gallery %}
![图片1](url1)
![图片2](url2)
{% endgallery %}` | 图片相册，自动排版，支持灯箱效果 | `{% gallery %}
![风景](https://example.com/1.jpg)
![人物](https://example.com/2.jpg)
{% endgallery %}` | | **video** | `{% video [width] [height] [poster] %} 视频URL {% endvideo %}		视频播放器，支持自定义尺寸和封面
audio{% audio [autoplay] [loop] [controls] %} 音频URL {% endaudio %}音频播放器，支持自动播放和循环{% audio autoplay loop %} https://example.com/music.mp3 {% endaudio %}
aplayer{% aplayer 标题, 歌手, 音频URL, 封面URL, [lrc] %}高级音频播放器，支持歌词显示{% aplayer 七里香, 周杰伦, https://example.com/qlx.mp3, https://example.com/cover.jpg, https://example.com/qlx.lrc %}
meting{% meting [type], [id], [server], [option] %}音乐 API 播放器（网易云 / QQ 音乐等）{% meting song, 123456, netease, "autoplay: true" %}

四、功能组件标签（Functional Components）

标签名称语法格式功能说明示例
progress{% progress [百分比] [颜色] [文字] %}进度条组件，支持自定义颜色和显示文本{% progress 75 #3eb8be 完成75% %}
button{% button [text] [url] [type] [icon] %}按钮组件，支持 6 种预设样式和自定义图标{% button 点击跳转 https://example.com primary fa-solid fa-arrow-right %}
badge{% badge [text] [type] [icon] %}徽章组件，用于标记状态或分类{% badge 新 primary fa-solid fa-star %}
bilibili{% bilibili [av号/bv号] [width] [height] %}嵌入 B 站视频{% bilibili BV1xx411c7m9 640 360 %}
youtube{% youtube [视频ID] [width] [height] %}嵌入 YouTube 视频{% youtube dQw4w9WgXcQ 640 360 %}
abcjs{% abcjs %} 乐谱代码 {% endabcjs %}渲染 ABC 乐谱{% abcjs %}X:1
T:Simple Song
M:4/4
L:1/8
K:C
C D E F G A B c{% endabcjs %}
note（补充）支持的 class 参数：default/primary/success/info/warning/danger提示块颜色样式预设{% note danger %} 错误警告 {% endnote %}
collapse（补充）open参数控制默认展开状态折叠面板初始状态设置{% collapse 默认展开 open %} 内容 {% endcollapse %}

五、特殊内容标签（Special Content）

标签名称语法格式功能说明示例
center{% center 文本内容 %}居中对齐文本{% center 这是居中显示的文本 %}
right{% right 文本内容 %}右对齐文本{% right 这是右对齐显示的文本 %}
quote{% quote [作者] [来源] [标题] %} 引用内容 {% endquote %}带引用信息的块引用{% quote 鲁迅 狂人日记 经典名言 %} 救救孩子！ {% endquote %}
code{% code [语言] [标题] %} 代码内容 {% endcode %}代码块，支持语法高亮和标题{% code javascript 示例代码 %}
console.log("Hello World");
{% endcode %}