Markdown 增强

语法支持

GitHub Flavored Markdown (GFM)
- 表格
- 任务列表
- 删除线
- 自动链接

Mermaid 图表

支持在 Markdown 中使用 Mermaid 语法绘制流程图、时序图、架构图等。

```mermaid
flowchart LR
    A[构建时脚本] --> B[JSON 数据文件] --> C[运行时工具函数]
```

flowchart LR
    A[构建时脚本] --> B[JSON 数据文件] --> C[运行时工具函数]

支持的图表类型：

flowchart / graph - 流程图
sequenceDiagram - 时序图
classDiagram - 类图
stateDiagram - 状态图
erDiagram - ER 图
gantt - 甘特图
pie - 饼图
mindmap - 思维导图

图表会自动跟随深色/浅色主题切换。更多语法参考 Mermaid 官方文档。

Infographic 信息图

支持使用 @antv/infographic 在 Markdown 中绘制精美的信息图表，适合展示流程、对比、层级、统计等数据。

使用方式：在代码块中使用 infographic 标记，第一行指定模板名称，然后使用类似 YAML 的语法定义数据：

```infographic
infographic list-grid-badge-card
data
  title 技术栈
  desc 我的常用技术栈
  items
    - label TypeScript
      desc 类型安全的 JavaScript
      icon mdi/language-typescript
    - label React
      desc 用户界面库
      icon mdi/react
    - label Astro
      desc 现代化静态站点生成器
      icon mdi/rocket-launch
```

infographic list-grid-badge-card
data
  title 技术栈
  desc 我的常用技术栈
  items
    - label TypeScript
      desc 类型安全的 JavaScript
      icon mdi/language-typescript
    - label React
      desc 用户界面库
      icon mdi/react
    - label Astro
      desc 现代化静态站点生成器
      icon mdi/rocket-launch

可用模板类型：

列表类 (list-*)：展示信息列表
- list-grid-badge-card - 卡片网格布局
- list-grid-candy-card-lite - 糖果风格卡片
- list-row-horizontal-icon-arrow - 水平图标箭头列表
流程/顺序类 (sequence-*)：展示步骤、流程或阶段
- sequence-zigzag-steps-underline-text - 之字形步骤
- sequence-circular-simple - 圆形流程
- sequence-roadmap-vertical-simple - 垂直路线图
- sequence-pyramid-simple - 金字塔结构
对比类 (compare-*)：二元或多元对比
- compare-binary-horizontal-simple-fold - 水平二元对比
- compare-swot - SWOT 分析
- compare-hierarchy-left-right-circle-node-pill-badge - 层级左右对比
层级类 (hierarchy-*)：展示树形结构
- hierarchy-tree-tech-style-capsule-item - 科技风格树形图
- hierarchy-tree-curved-line-rounded-rect-node - 曲线连接树形图
图表类 (chart-*)：数据可视化
- chart-column-simple - 柱状图
- chart-bar-plain-text - 条形图
- chart-pie-plain-text - 饼图
- chart-line-plain-text - 折线图
其他
- quadrant-* - 象限分析图
- relation-* - 关系图

数据字段说明：

title - 标题（可选）
desc - 描述文本（可选）
items - 条目数组，每个条目可包含：
- label - 主标签文本
- value - 数值（用于图表类模板）
- desc - 描述文本
- icon - 图标名称（格式：mdi/icon-name）
- children - 子条目（用于层级结构）

主题定制：

可以在数据后添加 theme 块自定义颜色：

```infographic
infographic sequence-pyramid-simple
data
  items
    - label 基础层
    - label 中间层
    - label 顶层
theme
  palette
    - #3b82f6
    - #8b5cf6
    - #f97316
```

信息图会自动跟随深色/浅色主题切换，并使用项目的寒蝉全圆体字体渲染。更多模板和语法参考 Infographic 官方文档。

代码高亮

基于 Shiki
支持双主题（深色/浅色）
支持语言标注
行号显示

示例：

```javascript
function hello() {
  console.log("Hello, world!");
}
```

function hello() {
  console.log("Hello, world!");
}

标题自动链接

所有标题自动生成可点击的锚点链接。

链接自动嵌入

独行的特殊链接会自动转换为嵌入组件：

Twitter/X 链接：自动嵌入 Tweet 组件
CodePen 链接：自动嵌入交互式 CodePen 演示
其他链接：显示 OG 预览卡片（包含标题、描述、图片等）

示例：

<!-- 独行链接会被嵌入 -->

https://x.com/vercel_dev/status/1997059920936775706

https://codepen.io/botteu/pen/YPKBrJX/

https://github.com/vercel/react-tweet

反爬严格，获取不到元信息的链接

https://zhuanlan.zhihu.com/p/1900483903984243480

<!-- 段落中的链接保持不变 -->

这是一个 [普通链接](https://example.com)，不会被嵌入。

See the Pen YPKBrJX by botteu (@botteu) on CodePen.

github.com

GitHub - vercel/react-tweet: Embed tweets in your React application.

Embed tweets in your React application. Contribute to vercel/react-tweet development by creating an account on GitHub.

https://github.com/vercel/react-tweet

GitHub - vercel/react-tweet: Embed tweets in your React application.

反爬严格，获取不到元信息的链接

https://zhuanlan.zhihu.com/p/1900483903984243480

zhuanlan.zhihu.com

这是一个普通链接，不会被嵌入。

Shoka 兼容 Markdown 语法

astro-koharu 从 Hexo Shoka 主题迁移了一套丰富的 Markdown 扩展语法，所有功能均可通过 config/site.yaml 的 content 配置项独立开关。

文字特效（`enableShokaEffects`）

支持多种行内文字装饰效果：

语法	效果	说明
`++文字++`	下划线	`<ins>` 标签
`++文字++{.wavy}`	波浪下划线	支持 `.wavy` 修饰符
`++文字++{.dot}`	着重点	支持 `.dot` 修饰符
`++文字++{.primary}`	彩色下划线	支持 `.primary` `.success` `.warning` `.danger` `.info`
`==文字==`	高亮	`<mark>` 标签
`~文字~`	下标	`<sub>` 标签，如 H₂O
`^文字^`	上标	`<sup>` 标签，如 E=mc²

示例效果：

这是下划线文字波浪下划线着重点标记

主色调成功警告危险信息

这是高亮文字

H₂O 是水的化学式，E = mc² 是质能方程

颜色文字与特殊样式（`enableShokaAttrs`）

使用 文字 语法为文字添加颜色和样式：

[红色]{.red} [粉色]{.pink} [橙色]{.orange} [黄色]{.yellow}
[绿色]{.green} [水色]{.aqua} [蓝色]{.blue} [紫色]{.purple} [灰色]{.grey}

[这段文字会有彩虹渐变效果]{.rainbow}

[Ctrl]{.kbd} + [C]{.kbd} 复制，[Ctrl]{.kbd} + [V]{.kbd} 粘贴

[默认]{.label .default} [主要]{.label .primary} [信息]{.label .info}
[成功]{.label .success} [警告]{.label .warning} [危险]{.label .danger}

示例效果：

红色粉色橙色黄色绿色水色蓝色紫色灰色

这段文字会有彩虹渐变效果

Ctrl + C 复制，Ctrl + V 粘贴

默认主要信息成功警告危险

隐藏文字 / Spoiler（`enableShokaSpoiler`）

这里有一段!!隐藏文字，点击显示!!

这里有一段!!模糊文字，鼠标悬停显示!!{.blur}

示例效果：

这里有一段隐藏文字，点击显示

这里有一段模糊文字，鼠标悬停显示

默认模式：点击后粒子消散动画揭示文字（基于 spoilerjs Web Component）
.blur 模式：鼠标悬停时模糊消失

注音标注 / Ruby（`enableShokaRuby`）

为 CJK 文字添加注音，适用于日语假名、汉语拼音等：

{漢字^かんじ}的注音示例

{取り返す^とりかえす}是日语中"取回"的意思

示例效果：

{漢字^{かんじ}的注音示例。{取り返す}とりかえす}是日语中"取回"的意思。

渲染为 HTML <ruby> 标签，浏览器原生支持。

提醒块 / Note Blocks（`enableShokaContainers`）

使用 ::: 语法创建不同样式的提醒块：

:::default
这是默认提醒块
:::

:::primary
这是主要提醒块，用于重要提示
:::

:::info
这是信息提醒块
:::

:::success
这是成功提醒块
:::

:::warning
这是警告提醒块
:::

:::danger
这是危险提醒块
:::

:::info no-icon
这是没有图标的信息块
:::

示例效果：

这是信息提醒块，用于提供额外信息

这是警告提醒块，请注意

这是危险提醒块，务必谨慎

支持的样式：default、primary、info、success、warning、danger。添加 no-icon 可隐藏图标。提醒块内部支持嵌套 Markdown 语法。

折叠块 / Collapse（`enableShokaContainers`）

使用 +++ 语法创建可折叠内容（渲染为 <details> + <summary>）：

+++primary 点击展开详细内容
折叠的内容，支持 **Markdown** 格式化。

- 列表项 1
- 列表项 2
+++

+++warning 注意事项
需要注意的内容
+++

+++danger 危险操作
请确保你知道自己在做什么！
+++

示例效果：

点击展开详细内容

折叠的内容，支持 Markdown 格式化。

列表项 1
列表项 2

注意事项

需要注意的内容

支持的样式：primary、info、success、warning、danger。

标签卡 / Tabs（`enableShokaContainers`）

使用 ;;; 语法创建标签页切换，同一组 ID 的标签卡会自动组合：

;;;mygroup JavaScript
```js
console.log('Hello, World!');
```
;;;

;;;mygroup Python
```python
print('Hello, World!')
```
;;;

;;;mygroup Rust
```rust
fn main() {
    println!("Hello, World!");
}
```
;;;

示例效果：

console.log('Hello, World!');

print('Hello, World!')

fn main() {
    println!("Hello, World!");
}

;;;groupId 标签名 定义一个标签页，同一 groupId 的标签自动组合
第一个标签默认激活
标签内支持任意 Markdown 内容

友链卡片（`enableShokaHexoTags`）

使用 {% links %} 标签在文章中插入友链卡片网格：

{% links %}
- site: 博客名称
  url: https://example.com
  owner: 站长昵称
  desc: 站点描述
  image: https://example.com/avatar.png
  color: '#ed788b'
- site: 另一个博客
  url: https://example2.com
  owner: Alice
  desc: 一个热爱技术的博客
  image: https://api.dicebear.com/7.x/avataaars/svg?seed=Alice
  color: '#BEDCFF'
{% endlinks %}

示例效果：

卡片数据使用 YAML 格式，支持 site、url、owner、desc、image、color 字段。

音频播放器（`enableShokaHexoTags`）

使用 {% media audio %} 标签嵌入音频播放器，支持网易云音乐、QQ 音乐等平台（通过 Meting API 解析）。

默认使用 https://163.hyc.moe/ 作为 Meting API，可在 config/site.yaml 的 bgm.metingApi 中自定义，推荐自部署以获得更稳定的服务。

{% media audio %}
- name: 歌曲名称
  url: https://music.163.com/#/song?id=3339210292
{% endmedia %}

示例效果：

支持歌单模式，可配置多个分组：

{% media audio %}
- title: 歌单名称 1
  list:
    - https://music.163.com/#/playlist?id=8676645748
- title: 歌单名称 2
  list:
    - https://music.163.com/#/playlist?id=17606384886
{% endmedia %}

视频播放器（`enableShokaHexoTags`）

使用 {% media video %} 标签嵌入视频播放器：

{% media video %}
- name: 视频 1
  url: https://example.com/video1.mp4
- name: 视频 2
  url: https://example.com/video2.mp4
{% endmedia %}

多个视频时自动显示播放列表。

练习题系统（`enableQuiz`）

支持四种交互式题型，适合教程和学习笔记。需在文章 frontmatter 中设置 quiz: true。

单选题：

- 下列哪个是 JavaScript 的基本数据类型？{.quiz}
  - Object{.options}
  - Array{.options}
  - Symbol{.correct}
  - Function{.options}

> 解析：Symbol 是 ES6 引入的基本数据类型。

示例效果：

下列哪个是 JavaScript 的基本数据类型？
- Object
- Array
- Symbol
- Function

解析：Symbol 是 ES6 引入的基本数据类型，而 Object、Array、Function 都是引用类型。

选项标记为正确答案，{.options} 为干扰项

多选题：

- 以下哪些是 CSS 布局方式？{.quiz .multi}
  - Flexbox{.correct}
  - jQuery{.options}
  - Grid{.correct}
  - Float{.correct}

> 解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。

示例效果：

以下哪些是 CSS 布局方式？
- Flexbox
- jQuery
- Grid
- Float

解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。jQuery 是一个 JavaScript 库。

添加 .multi 标记启用多选模式

判断题：

- `const` 声明的变量不能重新赋值，但可以修改其属性。{.quiz .true}

> 解析：`const` 只保证变量绑定不可变。

- HTML 是一种编程语言。{.quiz}

> 解析：HTML 是标记语言，不是编程语言。

示例效果：

const 声明的变量不能重新赋值，但可以修改其属性。

解析：const 只保证变量绑定不可变，如果变量指向一个对象，其属性仍然可以修改。

HTML 是一种编程语言。

解析：HTML（超文本标记语言）是一种标记语言，不是编程语言。

添加 .true 表示陈述正确，不添加 .true 则表示错误

填空题：

- CSS 中，[Flexbox]{.gap} 适合一维布局，[Grid]{.gap} 适合二维布局。{.quiz .fill}

> 常见错误：[Float]{.mistake}

示例效果：

CSS 中，Flexbox 适合一维布局，Grid 适合二维布局。

常见错误：Float

[答案] 标记正确答案（支持多个空）
[错误答案] 标记常见错误（首次答错时提示）
> 引用块内容为解析说明

数学公式（`enableMath`）

基于 KaTeX 渲染数学公式。需在文章 frontmatter 中设置 math: true：

行内公式：$E = mc^2$

块级公式：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

示例效果：

行内公式： $E = mc^2$

块级公式：

\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}

代码块增强（`enableCodeMeta`）

代码块支持额外的元数据标注：

```js title="hello.js" url="https://example.com" linkText="查看源码" mark:1,3
const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);
```

```bash command:("$":1-3)
npm install astro
npm run dev
npm run build
```

元数据	说明
`title="文件名"`	显示代码块标题
`url="链接"`	添加外部源码链接
`linkText="文字"`	自定义链接文字（默认为 URL）
`mark:1,3`	高亮指定行
`command:("$":1-3)`	标记 shell 命令行（显示 `$` 前缀）

示例效果：

const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);

npm install astro
npm run dev
npm run build

Shoka 功能配置总览：

所有 Shoka 兼容功能均可在 config/site.yaml 的 content 部分独立开关：

content:
  # Shoka 兼容功能（默认全部启用，设为 false 可关闭）
  enableShokaContainers: true   # :::提醒块 ;;;标签卡 +++折叠块
  enableShokaAttrs: true        # text 属性语法
  enableShokaEffects: true      # ++下划线++ ==高亮== ~下标~ ^上标^
  enableShokaSpoiler: true      # !!隐藏文字!!
  enableShokaRuby: true         # {文字^注音} 注音标注
  enableShokaHexoTags: true     # {% links %} {% media %} Hexo 标签
  enableMath: true              # $数学公式$ KaTeX 渲染
  enableCodeMeta: true          # 代码块增强 (title, mark, command)
  enableQuiz: true              # 练习题交互功能
  enableEncryptedBlock: true    # :::encrypted{password="..."} 加密内容块

内容加密（`enableEncryptedBlock`）

博客支持两种加密方式，满足不同的内容保护需求：

1. 加密块 —— 文章局部加密

在文章中使用 :::encrypted{password="..."} 语法包裹需要加密的内容：

这部分内容公开可见。

:::encrypted{password="demo"}
这段内容需要输入密码 "demo" 才能查看。

支持完整的 Markdown 语法，包括代码块、列表、图片等。
:::

这部分也是公开的。

加密块适合在一篇文章中部分隐藏敏感内容（如答案、剧透、私密笔记），其余内容正常展示。需要在 config/site.yaml 中启用 enableEncryptedBlock: true。

2. 加密文章 —— 整篇文章加密

在文章的 frontmatter 中添加 password 字段即可加密整篇文章：

---
title: 我的私密文章
date: 2026-01-01
password: mySecretPassword
categories:
  - 笔记
---

这里的所有内容都会被加密...

加密文章会显示一个全屏的解锁界面，输入正确密码后才能查看内容。解锁后代码高亮、目录导航、Mermaid 图表等增强功能会自动重新初始化。

安全模型说明：

加密功能使用 AES-256-GCM 算法，安全模型如下：

构建时加密：密码仅在 pnpm build 时用于加密，生成的 HTML 中不包含密码明文
客户端解密：读者在浏览器中输入密码后，通过 Web Crypto API 在本地解密，密码不会发送到任何服务器
密钥派生：使用 PBKDF2（100,000 次迭代）从密码派生加密密钥，提高暴力破解成本
搜索排除：加密内容自动添加 data-pagefind-ignore，不会被 Pagefind 搜索索引

⚠️ 注意：此加密设计的主要目的是防止搜索引擎和爬虫索引加密内容，而非抵御针对性攻击。密文和盐值嵌入在公开的 HTML 中，理论上可被离线暴力破解。请使用强密码，不要用于保护高度敏感的信息。

加密文章的特殊行为：

方面	行为
RSS 订阅	标题前加 🔒 前缀，内容替换为"此文章已加密"提示
SEO / meta	description 使用 frontmatter 中的 `description`（若未设置则显示通用加密提示）
搜索索引	加密内容不会被 Pagefind 索引
目录导航	解锁前不显示，解锁后自动重建
AI 摘要	基于加密前的原文生成（构建时可访问明文）

其他增强

自动目录生成
阅读时间计算
外部链接自动添加 target="_blank"

Markdown 增强语法

Markdown 增强

语法支持

Mermaid 图表

Infographic 信息图

代码高亮

标题自动链接

链接自动嵌入

GitHub - vercel/react-tweet: Embed tweets in your React application.

Shoka 兼容 Markdown 语法

文字特效（enableShokaEffects）

颜色文字与特殊样式（enableShokaAttrs）

隐藏文字 / Spoiler（enableShokaSpoiler）

注音标注 / Ruby（enableShokaRuby）

提醒块 / Note Blocks（enableShokaContainers）

折叠块 / Collapse（enableShokaContainers）

标签卡 / Tabs（enableShokaContainers）

友链卡片（enableShokaHexoTags）

音频播放器（enableShokaHexoTags）

视频播放器（enableShokaHexoTags）

练习题系统（enableQuiz）

数学公式（enableMath）

代码块增强（enableCodeMeta）

内容加密（enableEncryptedBlock）

其他增强

文字特效（`enableShokaEffects`）

颜色文字与特殊样式（`enableShokaAttrs`）

隐藏文字 / Spoiler（`enableShokaSpoiler`）

注音标注 / Ruby（`enableShokaRuby`）

提醒块 / Note Blocks（`enableShokaContainers`）

折叠块 / Collapse（`enableShokaContainers`）

标签卡 / Tabs（`enableShokaContainers`）

友链卡片（`enableShokaHexoTags`）

音频播放器（`enableShokaHexoTags`）

视频播放器（`enableShokaHexoTags`）

练习题系统（`enableQuiz`）

数学公式（`enableMath`）

代码块增强（`enableCodeMeta`）

内容加密（`enableEncryptedBlock`）