Markdown Syntax Extensions

This page summarizes the 17 markdown-it plugins enabled by the theme via hexo-renderer-markdown-it (emoji / attrs / link-attributes / abbr / footnote / ins / sub / sup / mark / task-checkbox / multimd-table / imsize / container / admon / deflist / mathjax3 / cjk-breaks; config in the root _config.yml), plus a combined example and a quick reference. Each plugin lists its purpose, syntax, example and effect — examples can be copied directly into a post for testing.

Unlike the inline bold-label style of the “Layout & Pages” chapter, this page uses third-level subheadings (purpose/syntax/example/effect) because it needs to host code blocks and live rendering examples.
Note: code blocks that demonstrate syntax are always wrapped with raw tags (raw paired with endraw) to prevent nunjucks from mishandling them or swallowing following content during pre-rendering.
Note: this page contains real math formula examples (item 16), so front-matter declares mathjax: true — whenever a post body contains $...$ / $$...$$ formulas you MUST declare it, otherwise formulas display literally.

1. emoji (markdown-it-emoji)

Purpose

Use emoji shortcodes directly in Markdown, no need to copy Unicode characters.

Syntax

:smile: :heart: :rocket:

Example

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

Effect

Shortcodes render as colorful emoji characters.

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

Purpose

Append {#id .class key=val} after an element to add id / class / custom attributes — handy for fine-tuning styles or anchor targets.

Syntax

[link](https://example.com){.external #link1 data-x="1"}

Example

link

Effect

{.class} adds a class, {#id} adds an id, key=val adds a custom attribute (e.g. data-*).

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

Purpose

External links (http(s)://) automatically get target="_blank" + rel="noopener noreferrer" — open in a new tab and prevent reverse tabnabbing.

Syntax

[external link](https://example.com)

Example

external link

Effect

External links open in a new tab (target="_blank"); internal links are untouched (only the ^https?:// pattern matches).

4. abbr (markdown-it-abbr)

Purpose

Define abbreviations; hovering shows the full name (generates an <abbr> tag).

Syntax

*[HTML]: Hyper Text Markup Language
HTML is the standard language of web pages.

The definition line *[abbr]: full-name must come before the first use in the text.

Example

W3C defines Web standards.

Effect

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

5. footnote (markdown-it-footnote)

Purpose

Show notes/sources collectively at the end of the post, referenced by superscript numbers in the body.

Syntax

Here is the body text[^1].

[^1]: This is the footnote content.

Example

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

Effect

Superscript numbers appear in the body; clicking jumps to the footnote area at the end (footnote numbers must be unique per post, no duplicates).

6. ins (markdown-it-ins)

Purpose

++text++ renders as underlined inserted text (like a revision mark).

Syntax

This is ++inserted content++.

Example

This update added dark mode support.

Effect

Inserted text gets an underline (<ins> tag).

7. sub (markdown-it-sub)

Purpose

~text~ renders as subscript.

Syntax

H~2~O is the chemical formula of water.

Example

CO₂ is carbon dioxide.

Effect

Text renders as subscript (<sub> tag).

8. sup (markdown-it-sup)

Purpose

^text^ renders as superscript.

Syntax

E=mc^2^ is the mass-energy equivalence equation.

Example

2¹⁰ = 1024.

Effect

Text renders as superscript (<sup> tag).

9. mark (markdown-it-mark)

Purpose

==text== renders as highlighter emphasis.

Syntax

This is ==key content==.

Example

Pay special attention to password security.

Effect

Text gets a highlight background (<mark> tag), adapting to light/dark mode.

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

Purpose

Render task lists with checkboxes.

Syntax

- [x] completed task
- [ ] uncompleted task

x inside the brackets means done, a space means not done.

Example

Theme test post created
Automated test scripts
Visual regression verification

Effect

Checkboxes with strikethrough style on completed tasks.

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

Purpose

Standard GFM tables + alignment control (left / center / right).

Syntax

| left | center | right |
| :----- | :--: | -----: |
| a | b | c |

The colon position in the separator row determines alignment: :--- left, :--: center, ---: right.

Example

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

Effect

Tables render correctly with alignment applied (light/dark mode adaptive).

12. imsize (markdown-it-imsize)

Purpose

Append =widthxheight after the image URL to control the display size, no CSS needed.

Syntax

![image description](image-URL =300x200)

Example

cover

Effect

Images display at the specified size (display size only, original image untouched).

13. container (markdown-it-container)

Purpose

::: type renders a callout container with a color bar + light background. The theme registers 7 types: warning / note / info / attention / error / tip / hint.

Syntax

::: warning
warning content
:::

Example

This is a warning container — content that needs attention!

This is a note container — supplementary info.

This is an info container — informational.

This is an attention container — caution.

This is an error container — serious error.

Effect

Callout containers with a left color bar + light background (mapped to note styles), adapting to light/dark mode. The 7 types above are registered; ::: tip / ::: hint render as info-blue callouts.

14. Admonition admon (markdown-it-admon)

Purpose

!!! type renders a callout with a colored side bar + tinted background, rendered as a .admonition structure. It is a separate plugin from section 13’s container: different marker (!!! vs :::), different output (<div class="admonition tip"> vs <div class="tip">).

Syntax

!!! tip
    tip content here

Example

Tip

This is a tip container — a hint.

Effect

A callout with a left color bar + tinted background (.admonition + .admonition-title), adaptive to light/dark mode. Types are not restricted (validate only checks the tag is non-empty); common ones: warning/note/info/attention/error/tip/hint. The block closes after two consecutive empty lines.

15. deflist (markdown-it-deflist)

Purpose

Render definition lists (term + multiple descriptions).

Syntax

Term
: definition description

Example

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

Effect

Terms bold, descriptions indented (<dl> / <dt> / <dd> structure).

16. mathjax3 (markdown-it-mathjax3)

Purpose

Render LaTeX math formulas: $...$ inline, $$...$$ block (requires mathjax: true in front-matter).

Syntax

Inline: $E=mc^2$
Block:
$$
\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 (MathJax rendering, LaTeX syntax supported). Escape with \$ when you need a literal $.

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

Purpose

Optimize CJK typesetting: avoid line breaks in wrong places in mixed Chinese/English text.

Syntax

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

Effect

Applies automatically, no markers needed — inline line breaks in mixed CJK/Latin text follow Chinese reading habits.

18. Combined Example (Multiple Plugins)

Example

Task list (task-checkbox):

emoji works: ✅
abbr works: API
math works: $a^{2} + b^{2} = c^{2}$

Definition list (deflist):

Markdown: A lightweight markup language.; Invented by John Gruber.

Footnote (footnote): the tutorial wiki has 4 chapters in total^[2].

Effect: multiple plugins work together on the same page without interfering.

Appendix: markdown-it Plugin Quick Reference

Plugin	Syntax	Renders	Notes
emoji	`:smile:`	emoji character	shortcode, ready to use
attrs	`{...}` after element	inline attributes	`{#id .class key=val}`
link-attributes	external links	`target="_blank"`	only matches `^https?://`
abbr	`*[ABBR]: full-name`	`<abbr>` hover tooltip	definition must precede use
footnote	`[^1]` + `[^1]: content`	end-of-post footnote	numbers unique per post
ins	`++text++`	`<ins>` underline	revision mark
sub	`~text~`	`<sub>` subscript	chemical formulas etc.
sup	`^text^`	`<sup>` superscript	powers etc.
mark	`==text==`	`<mark>` highlight	highlighter effect
task-checkbox	`- [x]` / `- [ ]`	checkbox list	space after `[x]`
multimd-table	GFM table	`<table>`	`:--:` controls alignment
imsize	`![img](url =300x200)`	sized image	display size only
container	`::: warning`	note container	7 types registered
admon	`!!! tip` + blank-line close	`.admonition` callout	types unrestricted
deflist	`Term` + `: definition`	`<dl>` list	multi-line descriptions
mathjax3	$formula$ / `$$formula$$`	SVG formula	needs `mathjax: true`
cjk-breaks	none	auto	CJK typesetting optimization

Common pitfalls:

Code blocks that demonstrate syntax MUST be wrapped with raw tags (raw/endraw paired), preventing nunjucks pre-render errors or swallowed content
When a post body contains $...$ / $$...$$ formulas, front-matter MUST declare mathjax: true, otherwise formulas display literally
Leave a blank line above and below block formulas $$...$$; escape literal $ with \$
Task list - [x] needs a space after the brackets; - [x]xxx won’t render as a task
The abbr definition line *[abbr]: full-name must precede the first use, otherwise it won’t take effect
container registers warning/note/info/attention/error/tip/hint; ::: tip / ::: hint render as info-blue callouts

Hexo official site: https://hexo.io ↩︎
Layout, Tag plugins, Interactions, Markdown syntax. ↩︎