Hexo Theme Feature Test - Markdown Syntax

This article covers all 16 markdown-it plugins enabled by the theme. Each item includes purpose, syntax, example and effect, for automated test assertions.

1. emoji (markdown-it-emoji)

Purpose

Use emoji shortcodes directly in Markdown.

Syntax

:smile: :heart: :rocket:

Example

😄 smile ｜ ❤️ heart ｜ 🚀 rocket ｜ 👍 thumbs up

Effect

Shortcodes render as colorful emoji characters.

Test assertion: the page contains emoji rendering markers (<span class="emoji"> or direct emoji characters).

2. abbr (markdown-it-abbr)

Purpose

Define abbreviations; hovering shows the full name.

Syntax

*[HTML]: Hyper Text Markup Language
HTML 是网页的标准语言。

Example

W3C 制定 Web 标准。

Effect

Abbreviations get a dotted underline; hovering shows the full name.

Test assertion: the page contains the <abbr marker.

3. footnote (markdown-it-footnote)

Purpose

Footnote references at the end of the article.

Syntax

这里是正文[^1]。

[^1]: 这是脚注内容。

Example

Hexo is a fast static blog framework^[1].

Effect

Superscript numbers in the body; clicking jumps to the footnote at the end.

Test assertion: the page contains footnote-related markers (<sup or footnotes).

4. ins (markdown-it-ins)

Purpose

++inserted text++ renders as underlined inserted text.

Syntax

这是 ++插入的内容++。

Example

This update adds dark mode support.

Effect

Inserted text gets an underline (like a revision marker).

Test assertion: the page contains the <ins marker.

5. sub (markdown-it-sub)

Purpose

~subscript~ renders as subscript.

Syntax

H~2~O 是水的化学式。

Example

CO₂ is carbon dioxide.

Effect

Text renders as subscript.

Test assertion: the page contains the <sub marker.

6. sup (markdown-it-sup)

Purpose

^superscript^ renders as superscript.

Syntax

E=mc^2^ 是质能方程。

Example

2¹⁰ = 1024.

Effect

Text renders as superscript.

Test assertion: the page contains the <sup marker.

7. mark (markdown-it-mark)

Purpose

==highlight== renders as highlighter highlight.

Syntax

这是 ==重点内容==。

Example

Pay special attention to password security.

Effect

Text gets a highlight background color.

Test assertion: the page contains the <mark marker.

8. task-checkbox (markdown-it-task-checkbox)

Purpose

Render checkable task lists.

Syntax

- [x] 已完成任务
- [ ] 未完成任务

Example

Theme test article created
Automated test scripts
Visual regression verification

Effect

Checkboxes; completed tasks get a strikethrough.

Test assertion: the page contains task-list-item or checkbox markers.

9. multimd-table (markdown-it-multimd-table)

Purpose

Enhanced table syntax: cell merging, multi-line headers, alignment, etc.

Syntax

| 左对齐 | 居中 | 右对齐 |
| :----- | :--: | -----: |
| a | b | c |

Example

Feature	Status	Priority
Basic	✅	High
Advanced	✅	Medium
Experimental	⚠️	Low

Effect

Tables render correctly with alignment applied.

Test assertion: the page contains the <table marker.

10. imsize (markdown-it-imsize)

Purpose

Control image display size with =widthxheight.

Syntax

![图片](url =300x200)

Example

cover

Effect

Images display at the specified size.

Difference from imgsize.js: markdown-it-imsize is a Markdown rendering plugin that processes the =widthxheight syntax at compile time and writes width/height attributes into <img> tags; the theme also has scripts/events/lib/imgsize.js, which at runtime injects real dimensions into <img> elements without manually specified sizes (synchronous read for local images / asynchronous fetch for remote), preventing CLS. The two work together: manually specified sizes are handled by the imsize plugin, unspecified ones are filled in by imgsize.js as a fallback.

Test assertion: the page contains an img with size attributes.

11. container (markdown-it-container)

Purpose

::: type renders custom containers.

Syntax

::: warning
警示内容
:::

Example

This is a warning container.

This is a tip container.

Effect

Containers get a colored bar and a light background (mapped to the note style).

Test assertion: the page contains the note warning container marker.

12. deflist (markdown-it-deflist)

Purpose

Render definition lists (term + description).

Syntax

术语
: 定义描述

Example

Hexo: A fast, simple and powerful blog framework.; Written in Node.js.

Effect

Terms are bold; descriptions are indented.

Test assertion: the page contains <dl / <dt / <dd markers.

13. mathjax3 (markdown-it-mathjax3)

Purpose

Render LaTeX math formulas (inline + block).

Syntax

内联：$E=mc^2$
块级：
$$
\int_0^1 x^2 dx = \frac{1}{3}
$$

Example

Inline formula: $E = m c^{2}$

Block formula:

\int_{0}^{\infty} e^{- x^{2}} d x = \frac{\sqrt{π}}{2}

Effect

Formulas render as SVG math symbols.

Test assertion: the page contains math rendering markers (SVG or math container).

Dual Math Engines (mathjax / katex, added 2026-09-10)

The theme post.math.engine supports picking one of two (the root _config.yml markdown plugin switches in tandem):

Engine	Delimiters	Rendering
`mathjax` (default)	$...$ inline / `$$...$$` block (mathjax3 5.x hardcodes them, `$...$` not supported)	Node-side SSR outputs MathJax SVG (`<mjx-container>`), no frontend JS needed
`katex`	$...$ / `$$...$$` + `$...$` / `\[...\]` (brackets must be standalone blocks)	SSR rendering + frontend loads KaTeX CSS (`static_prefix.katex`)

Switching to katex: comment out markdown-it-mathjax3 in markdown.plugins, enable texmath, set post.math.engine: katex. Mind map (markmap) embedded formulas always use KaTeX (.katex), coexisting with body MathJax (dual channel).

14. cjk-breaks (markdown-it-cjk-breaks)

Purpose

CJK inline line-break optimization (avoids wrong line breaks between Chinese and English).

Syntax

这是中文测试内容，混合English和中文。

Effect

Mixed Chinese-English inline text does not break incorrectly.

Test assertion: Chinese text renders normally.

15. Combined task list / table (multimd-table enhancement)

Purpose

Advanced tables: multi-line headers, cell merging, etc.

Syntax

| 表头1 | 表头2 |
| ----- | ----- |
| 单元格 | 单元格 |

Example

Plugin	Type	Status
emoji	inline	✅
footnote	inline	✅
mathjax3	block	✅

Effect

Enhanced tables render correctly.

Test assertion: the page contains the <table marker (2+ tables).

16. Combined test (multiple plugins)

Example

Task list (task-checkbox):

emoji works: ✅
abbr works: [API]: Application Programming Interface API
math works: $a^{2} + b^{2} = c^{2}$

Definition list (deflist):
Markdown
: A lightweight markup language.
: Invented by John Gruber.

Footnote (footnote): the theme test series has 4 articles in total^[2].

Effect

Multiple plugins work together on the same page.

Test assertion: the page contains a combination of multiple markers.

17. Inline Attributes attrs (markdown-it-attrs)

Purpose

Add class / id / custom attributes to elements ({#id .class key=val}), used for style targeting and anchors.

Syntax

Paragraph {.text-center #intro}
[Link](url){target="_blank"}

Example

This is a centered paragraph (class targeting).

Implementation Effects

Elements carry the specified class / id / attributes, available to CSS / JS selectors.

Test assertion: the page contains an element with the text-center class.

18. External Link Attributes link-attributes (markdown-it-link-attributes)

Purpose

Links automatically get target="_blank" + rel="noopener noreferrer" (open in new window + prevent reverse tabnabbing).

Syntax

[External link](https://hexo.io)
[Internal link](/posts/8a11fe0a/)

Example

Hexo official site ｜ Internal article

Implementation Effects

External links open in a new window + prevent reverse tabnabbing (rel noopener noreferrer)
Note: the current config pattern: ^https?:// does not take effect (markdown-it-link-attributes only recognizes the matcher function, not the pattern string) — body links (including internal ones) uniformly get target; template-generated links (prev/next, etc.) are unaffected

Test assertion: external <a> contains target="_blank" + rel="noopener noreferrer".

19. admon Callout Blocks (markdown-it-admon)

Purpose

!!! type syntax renders callout blocks (complementary to the ::: syntax of §11 container, python-markdown style).

Syntax

!!! warning
    Warning content (indented 4 spaces)

Example

Warning

This is a warning admon — pay attention to the content.

Tip

This is a tip admon — a small trick.

Implementation Effects

Callout blocks with icon + color bar (supports note/info/tip/warning/danger/error types, etc.).

Test assertion: the page contains admon rendering markers.

⚠️ Known Pitfalls

Pitfall 1: Double Section Numbering

Symptom: Headings render as “1. 1. Overview” (two numbers).

Cause: Theme CSS auto-adds numbers to h2–h6 by default; hand-written numbers (e.g. ## 1. Overview) stack on top.

Fix: Pages with hand-written numbering add closeAutoTocNum: true in front-matter; pages without hand-written numbering must not add this field.

This article already correctly sets closeAutoTocNum: true.

Pitfall 5: Config Changes Require Clean Build

Symptom: After modifying markdown.plugins in the root _config.yml (e.g. switching mathjax/katex engine), the page doesn’t update.

Cause: Hexo’s caching mechanism doesn’t auto-detect configuration changes.

Fix: After changing markdown plugin configuration, you must npm run clean && npm run build.

Appendix: markdown-it plugin quick reference

Plugin	Syntax	Render	Test marker
emoji	`:smile:`	emoji character	emoji
abbr	`*[ABBR]: 全称`	`<abbr>`	abbr
footnote	`[^1]`	footnote	footnote
ins	`++文本++`	`<ins>`	ins
sub	`~文本~`	`<sub>`	sub
sup	`^文本^`	`<sup>`	sup
mark	`==文本==`	`<mark>`	mark
task-checkbox	`- [x]`	checkbox	task-list-item
multimd-table	table	`<table>`	table
imsize	`=200x100`	sized image	img
container	`::: type`	note container	note
deflist	`术语: 定义`	`<dl>`	dl
mathjax3	$公式$	SVG	math
attrs	`{#id .class key=val}`	element attributes	class/id
link-attributes	external links auto	target=_blank + rel	target
admon	`!!! type`	callout block	admon
cjk-breaks	automatic	CJK optimization	-