AI-reviewed An AI proof-read this post, but it still deserves a careful read.

Markdown enhancements

syntax support

GitHub Flavored Markdown (GFM)
- form
- task list
- strikethrough
- automatically linked

Mermaid chart

Support using Mermaid syntax to draw flow charts, timing charts, architecture charts, etc. in Markdown.

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

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

Supported chart types:

flowchart / graph - flowchart
sequenceDiagram - timing diagram
classDiagram - class diagram
stateDiagram - state diagram
erDiagram - ER diagram
gantt - Gantt chart
pie - pie chart
mindmap - mind map

The chart automatically follows the dark/light theme switch. More grammatical references Mermaid official documents。

Infographic

support the use of @antv/infographic Draw beautiful infographics in Markdown, suitable for displaying process, comparison, hierarchy, statistics and other data.

How to use: Use in code blocks infographic Tag, the first line specifies the template name, and then defines the data using YAML-like syntax:

```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

Available template types:

list class (list-*): Display information list
- list-grid-badge-card - card grid layout
- list-grid-candy-card-lite - Candy Style Card
- list-row-horizontal-icon-arrow - Horizontal icon arrow list
Process/Sequence Class (sequence-*): Demonstrate steps, processes or stages
- sequence-zigzag-steps-underline-text - zigzag step
- sequence-circular-simple - circular flow
- sequence-roadmap-vertical-simple - Vertical roadmap
- sequence-pyramid-simple - pyramid structure
comparative class (compare-*): Binary or multiple comparisons
- compare-binary-horizontal-simple-fold - Horizontal binary contrast
- compare-swot - SWOT analysis
- compare-hierarchy-left-right-circle-node-pill-badge - Comparison between left and right levels
hierarchical class (hierarchy-*): Display the tree structure
- hierarchy-tree-tech-style-capsule-item - Technological style tree diagram
- hierarchy-tree-curved-line-rounded-rect-node - Curve connection tree
Chart category (chart-*): Data visualization
- chart-column-simple - histogram
- chart-bar-plain-text - bar graph
- chart-pie-plain-text - pie chart
- chart-line-plain-text - line chart
other
- quadrant-* - quadrant analysis chart
- relation-* - diagram

Data field descriptions:

title - Title (optional)
desc - Description text (optional)
items - An array of entries, each entry can contain:
- label - Main Label Text
- value - Values (for chart templates)
- desc - description text
- icon - Icon name (format:mdi/icon-name）
- children - Sub-articles (for hierarchical structure)

Theme customization:

Can be added after the data theme Block custom color:

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

The infographic automatically follows the dark/light theme switch and is rendered using the project's chilling full-circle font. More templates and syntax references Infographic official document。

code highlighting

Based on Shiki
Support dual themes (dark/light)
Support language annotation
Line number display

Example:

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

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

Automatic title linking

Clickable anchor links are automatically generated for all titles.

Automatic link embedding

Unique unique links will automatically be converted into embedded components:

Twitter/X Link: Automatic embedding of Tweet components
CodePen Link: Automatically embed interactive CodePen demos
other links: Display OG preview card (including title, description, pictures, etc.)

Example:

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

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.

Anti-crawling is strict, and links with meta information cannot be obtained

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

zhuanlan.zhihu.com

this is a generic link, will not be embedded.

Shoka is compatible with Markdown syntax

Astro-koharu has migrated a rich set of Markdown extended syntax from the Hexo Shoka theme, and all functions can be accessed through config/site.yaml the content Configuration items are switched independently.

Text effects (`enableShokaEffects`）

Support multiple inline text decoration effects:

syntax	effect	description
`++文字++`	underlined	`<ins>` label
`++文字++{.wavy}`	wavy underline	support `.wavy` modifier
`++文字++{.dot}`	focus	support `.dot` modifier
`++文字++{.primary}`	colored underline	support `.primary` `.success` `.warning` `.danger` `.info`
`==文字==`	highlight	`<mark>` label
`~文字~`	subscript	`<sub>` Labels, such as H2O
`^文字^`	superscript	`<sup>` Labels, such as E=mc²

Example effect:

++ This is underlined text ++ ++ Wave underline ++{.wavy} ++ Emphasis mark ++{.dot}

++ Dominance ++{.primary} ++ Success ++{.success} ++ Warning ++{.warning} ++ Danger ++{.danger} ++ Information ++{.info}

== This is highlighted text ==

H2O is the chemical formula of water, and E = mc²is the mass-energy equation

Color text and special styles (`enableShokaAttrs`）

use 文字 Grammar adds color and style to text:

[红色]{.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}

Example effect:

red pink orange yellow green water color blue purple gray

This text will have a rainbow gradient effect

Ctrl + C Copy,Ctrl + V Paste

Default Primary Information Success Warning Danger

Hidden text/ Spoiler (`enableShokaSpoiler`）

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

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

Example effect:

Here is a paragraph!! Hide the text and click to display!!

Here is a paragraph!! Fuzzy text, hover over the mouse to display it!! {.blur}

Default mode: After clicking, particle dissipation animation reveals text (based on spoilerjs Web Component)
.blur Mode: The blur disappears when the mouse is hovering

Phonetic annotation/ Ruby (`enableShokaRuby`）

Add phonetic notation to CJK characters, suitable for Japanese kana, Chinese Pinyin, etc.:

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

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

Example effect:

Example of phonetic notation for {Chinese character}. {Take} means "take back" in Japanese.

Render to HTML <ruby> Tags, browser native support.

Note Blocks (`enableShokaContainers`）

use ::: Syntax Create alert blocks of different styles:

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

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

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

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

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

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

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

Example effect:

This is an information reminder block used to provide additional information

This is a warning reminder block, please pay attention

This is a danger warning block, be careful

Supported styles:default、primary、info、success、warning、danger。added no-icon Icons can be hidden. Nested Markdown syntax is supported internally in the reminder block.

Collapse (`enableShokaContainers`）

use +++ Grammar creates collapsible content (rendered as <details> + <summary>）：

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

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

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

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

Example effect:

Click to expand the details

Folded content, support Markdown Format.

List item 1
List item 2 +++

precautions

What needs to be noted

Supported styles:primary、info、success、warning、danger。

Label cards/ Tabs (`enableShokaContainers`）

use ;;; The syntax creation tab page is switched, and the tab cards of the same group ID will be automatically combined:

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

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

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

Example effect:

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

print('Hello, World!')

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

;;;groupId 标签名 Define a tab, the same groupId Automatic combination of tags
The first tab is activated by default
Any Markdown content is supported in the tag

Friend Chain Card (`enableShokaHexoTags`）

use {% links %} Tag Insert a friend chain card grid in the article:

{% 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 %}

Example effect:

Card data uses YAML format and supports site、url、owner、desc、image、color Field.

Audio player (`enableShokaHexoTags`）

use {% media audio %} Tags are embedded in audio players and support Netease Cloud Music, QQ Music and other platforms (through Meting API analysis).

used by default https://163.hyc.moe/ As a Meting API, it can be found in config/site.yaml the bgm.metingApi Customized in, self-deployment is recommended to obtain more stable services.

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

Example effect:

Support song mode, multiple groups can be configured:

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

Video player (`enableShokaHexoTags`）

use {% media video %} Tag embedded in video player:

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

The playlist is automatically displayed when there are multiple videos.

Exercise Question System (`enableQuiz`）

Supports four interactive question types, suitable for tutorials and study notes. Need to be set in the article frontmatter quiz: true。

Single choice question:

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

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

Example effect:

Which of the following is the basic data type of JavaScript?
- Object
- Array
- Symbol
- Function

Resolution: Symbol is the basic data type introduced by ES6, while Object, Array, and Function are all reference types.

option flag For the correct answer,{.options} is a disturbance

Multiple choice questions:

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

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

Example effect:

Which of the following are CSS layout methods?
- Flexbox
- jQuery
- Grid
- Float

Analysis: Flexbox, Grid and Float are all CSS layout methods. jQuery is a JavaScript library.

added .multi Mark enables multi-selection mode

Judgment question:

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

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

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

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

Example effect:

const A declared variable cannot be reassigned, but its properties can be modified.

Analysis:const Only the variable binding is guaranteed to be immutable. If the variable points to an object, its properties can still be modified.

HTML is a programming language.

Parsing: HTML (Hypertext Markup Language) is a markup language, not a programming language.

added .true Indicates that the statement is correct and does not add .true then it means an error

Fill in the blanks:

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

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

Example effect:

In CSS,Flexbox is suitable for one-dimensional layout, and Grid is suitable for two-dimensional layout.

Common mistakes: Float

[答案] Mark the correct answer (support multiple nulls)
[错误答案] Mark common mistakes (prompt when you answer wrong for the first time)
> Reference block content as parsing instructions

Mathematical formula (`enableMath`）

Render mathematical formulas based on KaTeX. Need to be set in the article frontmatter math: true：

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

块级公式：

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

Example effect:

Intra-line formula: $E = mc^2$

Block level formula:

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

Code block enhancement (`enableCodeMeta`）

Code blocks support additional metadata annotations:

```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
```

metadata	description
`title="文件名"`	Display code block title
`url="链接"`	Add external source code links
`linkText="文字"`	Customize link text (default is URL)
`mark:1,3`	Highlight the specified line
`command:("$":1-3)`	Mark the shell command line (display `$` prefix)

Example effect:

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

npm install astro
npm run dev
npm run build

Overview of Shoka functional configuration:

All Shoka-compatible features are available at config/site.yaml the content Partial independent switches:

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="..."} 加密内容块

Content encryption (`enableEncryptedBlock`）

Blogs support two encryption methods to meet different content protection needs:

1. Encryption block--local encryption of the article

Use in articles :::encrypted{password="..."} Grammar wraps content that needs to be encrypted:

这部分内容公开可见。

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

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

这部分也是公开的。

Encryption blocks fit in an articlepartially hiddenSensitive content (such as answers, spoilers, private notes), the rest of the content will be displayed normally. need config/site.yaml enabled in enableEncryptedBlock: true。

2. Encrypt the article-Encrypt the entire article

Add in the frontmatter of the article password Fields can encrypt the entire article:

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

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

Encrypted articles will display a full-screen unlock interface, and you can only view the content after entering the correct password. Enhancements such as code highlighting, directory navigation, and Mermaid charts are automatically reinitialized after unlocking.

Security model description:

Use of encryption functions AES-256-GCM Algorithm and security model are as follows:

Build time encryption: Passwords are only available in pnpm build is used for encryption, and the generated HTMLDoes not contain password plaintext
Client decryption: After readers enter the password in the browser, they decrypt it locally through the Web Crypto API, and the password will not be sent to any server
key derivation: Use PBKDF2 (100,000 iterations) to derive encryption keys from passwords, increasing the cost of brute force cracking
search exclusion: Encrypted content is automatically added data-pagefind-ignore, will not be indexed by Pagefind search

⚠️ note: The main purpose of this encryption design isPrevent search engines and crawlers from indexing encrypted content, rather than defending against targeted attacks. Cryptotext and salt values are embedded in public HTML and can theoretically be brute-force offline. Please use strong passwords and do not use them to protect highly sensitive information.

Special behaviors for encrypting articles:

aspects	behavior
RSS feeds	Prefix the title with, and replace the content with the prompt "This article is encrypted"
SEO / meta	description Use the `description`(If not set, a general encryption prompt will be displayed)
search index	Encrypted content will not be indexed by Pagefind
directory navigation	Does not display before unlocking, automatically rebuild after unlocking
AI Summary	Based on original text generation before encryption (plaintext can be accessed during construction)

other reinforcing

Automatic catalog generation
Reading time calculation
External links are automatically added target="_blank"

Markdown enhances syntax

Markdown enhancements

syntax support

Mermaid chart

Infographic

code highlighting

Automatic title linking

Automatic link embedding

Shoka is compatible with Markdown syntax

Text effects (`enableShokaEffects`）

Color text and special styles (`enableShokaAttrs`）

Hidden text/ Spoiler (`enableShokaSpoiler`）

Phonetic annotation/ Ruby (`enableShokaRuby`）

Note Blocks (`enableShokaContainers`）

Collapse (`enableShokaContainers`）

Label cards/ Tabs (`enableShokaContainers`）

Friend Chain Card (`enableShokaHexoTags`）

Audio player (`enableShokaHexoTags`）

Video player (`enableShokaHexoTags`）

Exercise Question System (`enableQuiz`）

Mathematical formula (`enableMath`）

Code block enhancement (`enableCodeMeta`）

Content encryption (`enableEncryptedBlock`）

other reinforcing

Random Posts

Related Posts

Markdown enhances syntax

Markdown enhancements

syntax support

Mermaid chart

Infographic

code highlighting

Automatic title linking

Automatic link embedding

Shoka is compatible with Markdown syntax

Text effects (enableShokaEffects）

Color text and special styles (enableShokaAttrs）

Hidden text/ Spoiler (enableShokaSpoiler）

Phonetic annotation/ Ruby (enableShokaRuby）

Note Blocks (enableShokaContainers）

Collapse (enableShokaContainers）

Label cards/ Tabs (enableShokaContainers）

Friend Chain Card (enableShokaHexoTags）

Audio player (enableShokaHexoTags）

Video player (enableShokaHexoTags）

Exercise Question System (enableQuiz）

Mathematical formula (enableMath）

Code block enhancement (enableCodeMeta）

Content encryption (enableEncryptedBlock）

other reinforcing

Random Posts

Related Posts

Text effects (`enableShokaEffects`）

Color text and special styles (`enableShokaAttrs`）

Hidden text/ Spoiler (`enableShokaSpoiler`）

Phonetic annotation/ Ruby (`enableShokaRuby`）

Note Blocks (`enableShokaContainers`）

Collapse (`enableShokaContainers`）

Label cards/ Tabs (`enableShokaContainers`）

Friend Chain Card (`enableShokaHexoTags`）

Audio player (`enableShokaHexoTags`）

Video player (`enableShokaHexoTags`）

Exercise Question System (`enableQuiz`）

Mathematical formula (`enableMath`）

Code block enhancement (`enableCodeMeta`）

Content encryption (`enableEncryptedBlock`）