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 Chart
• erDiagram- ER diagram
• gantt-Gantt Chart
• pie -Pie Chart
• mindmap -Mind Map

The chart automatically follows the dark/light theme switch. Refer to Mermaid 官方文档 for more syntax.

Infographic

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

How to use it: Use the infographic tag in the code block, specify the template name on the first line, and then use YAML-like syntax to define the data:

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

• List(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-*): Display steps, processes, or stages

  • sequence-zigzag-steps-underline-text-Zigzag Step
  • sequence-circular-simple-Circular Process
  • sequence-roadmap-vertical-simple-Vertical Roadmap
  • sequence-pyramid-simple-Pyramid Structure

• Comparison class(compare-*): binary or multivariate comparison

  • compare-binary-horizontal-simple-fold-Level Binary Comparison
  • compare-swot- SWOT Analysis
  • compare-hierarchy-left-right-circle-node-pill-badge-Level left and right comparison

• Hierarchy class(hierarchy-*): Display tree structure

  • hierarchy-tree-tech-style-capsule-item-Technology Style Tree Diagram
  • hierarchy-tree-curved-line-rounded-rect-node-Curve Connection Tree Diagram

• Chart Class(chart-*): Data Visualization

  • chart-column-simple-Histogram
  • chart-bar-plain-text-Bar Chart
  • chart-pie-plain-text-Pie Chart
  • chart-line-plain-text-Line Chart

• Other- quadrant-* -Quadrant Analysis Chart

  • relation-*-Relationship Diagram

Data field description:

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

Theme customization:

You can add custom colors for theme blocks after the data:

```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. Refer to Infographic 官方文档 for more templates and syntax.

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: Automatic embedding of 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

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

This is a 普通链接 and will not be embedded.

Shoka is compatible with Markdown syntax

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

Text effects (enableShokaEffects)

Support multiple inline text decoration effects:

Example effect:

This is the underlined text wavy underlined {.wavy} accent mark {.dot}

Main color Success Warning Danger Information

This is the highlighted text

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

Color text and special styles (enableShokaAttrs)

Use 文字 syntax to add 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] {.red} [Pink] {.pink} [Orange] {.orange} [Yellow] {.yellow} [Green] {.green} [Water Color] {.aqua} [Blue] {.blue} [Purple] {.purple} [Gray] {.grey}

This text will have a rainbow gradient effect

[Ctrl] {.kbd} + [C] {.kbd} copy,[Ctrl] {.kbd} + [V] {.kbd} paste

[Default] {.label .default} [Main] {.label .primary} [Information] {.label .info} [Success] {.label .success} [Warning] {.label .warning} [Danger] {.label .danger}

Hidden text/ Spoiler (enableShokaSpoiler)

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

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

Example effect:

There is a hidden text for . Click to display

There is a paragraph of fuzzy text here, and the mouse hover displays {.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 漢字(かんじ). 取り返す(とりかえす) means "retrieve" in Japanese.

Render to HTML <ruby> tags, which is natively supported by the browser.

Reminder Blocks/ Note Blocks (enableShokaContainers)

Use ::: syntax to create different styles of reminder blocks:

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

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

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

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

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

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

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

Example effect:

Supported styles: default, primary, info, success, warning, danger. Add no-icon to hide the icon. Nested Markdown syntax is supported internally in the reminder block.

Folding block/ Collapse (enableShokaContainers)

Use +++ syntax to create collapsible content (rendered as <details> + <summary>):

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

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

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

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

Example effect:

Supported styles: primary, info, success, warning, danger.

Label Cards/ Tabs (enableShokaContainers)

Use ;;; syntax to create tab switching, and 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 标签名 defines a tab page, and tags of the same groupId are automatically combined
• The first tab is activated by default
• Any Markdown content is supported in the tag

Friend Chain Card (enableShokaHexoTags)

Use the {% links %} tag to insert a grid of friend chain cards 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:

余弦の博客

FE / ACG / 手工

示例博客

一个热爱技术的博客

Card data uses YAML format and supports site, url, owner, desc, image, and color fields.

Audio player (enableShokaHexoTags)

Use the {% media audio %} tag to embed the audio player and support Netease Cloud Music, QQ Music and other platforms (parsed through Meting API).

https://163.hyc.moe/ is used as the Metating API by default, which can be customized in bgm.metingApi of config/site.yaml. 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 the {% media video %} tag to embed the 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. You need to set quiz: true in the article frontmatter.

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.

• The option marks as the correct answer and {.options} as the interference term

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.

• Add .multi flag to enable multi-selection mode

Judgment question:

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

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

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

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

Example effect:

• Variables declared by const cannot be reassigned, but their properties can be modified.

Resolution: const only ensures that variable binding is immutable. If a 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.

• Adding .true means the statement is correct, and not adding .true means error

Fill in the blanks:

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

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

Example effect:

• In CSS,[Flexbox] {.gap} is suitable for one-dimensional layout, and [Grid] {.gap} is suitable for two-dimensional layout.

Common error: Float

• [答案] marks the correct answer (multiple nulls are supported)
• Common errors in [错误答案] marking (prompt when answering incorrectly for the first time)
• The content of the > reference block is an analysis explanation

Mathematical formula (enableMath)

Render mathematical formulas based on KaTeX. You need to set math: true in the article frontmatter:

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

块级公式：

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

Example effect:

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

Block level formula:

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

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 functions can be switched independently in the content part of config/site.yaml:

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. Encrypt block--Article local encryption

Use :::encrypted{password="..."} syntax in the article to wrap the content that needs to be encrypted:

这部分内容公开可见。

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

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

这部分也是公开的。

The encryption block is suitable for hiding sensitive content (such as answers, spoilers, and private notes) in the part of an article, and displaying the rest normally. enableEncryptedBlock: true needs to be enabled in config/site.yaml.

2. Encrypt the article--Encrypt the entire article

Add the password field to the frontmatter of the article to 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.

Safety model description:

The encryption function uses the AES-256-GCM algorithm, and the security model is as follows:

• Encryptduring construction: Password is only used for encryption when pnpm build, andin the generated HTML does not contain the password plaintext-Client-side decryption: After readers enter the password in the browser, they decrypt it locally through the Web Crypto API. The password will not be sent to any server
• Key derivation: Use PBKDF2 (100,000 iterations) to derive encryption keys from passwords, increasing brute-force cracking costs
• Search Exclusion: Encrypted content is automatically added to data-pagefind-ignore and will not be indexed by Pagefind search

Note: The main purpose of this encryption design is forto prevent search engines and crawlers from indexing encrypted content, rather than to defend 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 behavior of encrypting articles:

other reinforcing

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