Content Tag Plugins

This page summarizes the 14 content tag plugins of the matery theme: note, timeline, tabs, label, button, githubCard, mermaid, pdf, insertmd, wechat_dialog, groupimage, cardurl, admonition, encrypt. 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.
The first 12 are native theme tags (registered uniformly in themes/matery/scripts/tags/index.js); admonition is provided by the markdown-it-container plugin (7 container types registered in the root _config.yml: warning/note/info/attention/error/tip/hint).
Note: when showing {% xxx %} tag syntax inside a Markdown code block, you MUST wrap it with raw tags (raw paired with endraw), otherwise nunjucks pre-renders it and the build fails with unknown block tag.

Basic Tag Plugins

1. note

Purpose

Colored callout blocks inside posts, for warning / success / info / danger emphasis.

Syntax

{% note color %}content{% endnote %}

• Color (optional; when omitted no default class is added and the default icon/color-bar style does not apply): default / primary / success / info / warning / danger — 6 colors
• Alias: {% subnote %}
• Advanced: add no-icon after the color to hide the left icon; add @summary title to make a collapsible block

Example

Collapsible version:

Effect

Colored rounded cards with a left color bar + icon (success ✓ / warning ⚠ / danger − (minus-circle)), adapting to light/dark mode.

2. timeline

Purpose

Show events / version logs / growth history in time order.

Syntax

{% timeline title,color %}
<!-- timeline time-node -->
- event content (Markdown supported)
<!-- endtimeline -->
{% endtimeline %}

• Title: overall timeline title (Markdown supported)
• Color (optional): green / blue / red / orange etc., appended as a class name to .timeline
• Time nodes: <!-- timeline date --> separates each event; node titles also support Markdown

Example

Effect

Vertical timeline with dot markers, color themes supported, titles rendered with Markdown.

3. tabs

Purpose

Multi-tab content switching, great for categorized display / step-by-step instructions / comparisons.

Syntax

{% tabs unique-name,active-index %}
<!-- tab tab-title -->
content (Markdown and inline tags supported)
<!-- endtab -->
{% endtabs %}

• Unique name: required, used to generate ids (spaces become -)
• Active index: optional; omit or 0 activates the first; N activates the Nth
• Tab titles: <!-- tab title --> defines each tab; append @icon to add a Font Awesome icon (e.g. @fas:home; prefix supports fas/far/fal/fad/fab)

Example

Effect

Materialize tabs style, click to switch, active tab highlighted, each content area renders Markdown independently.

4. label

Purpose

Inline colored mini labels for keywords / status / category annotations.

Syntax

{% label color@text %}

• Color (optional, default default): default / primary / success / info / warning / danger
• ★ Note the parameter order: color BEFORE @, text AFTER @ (the source parses with split('@'), opposite to intuition)

Example

Effect

Inline rounded colored labels, text on white or colored background.

5. button

Purpose

CTA buttons inside posts, for links / downloads / action entries.

Syntax

{% button link,text,icon,title %}

• ★ Link is the FIRST argument (source: url=args[0], text=args[1])
• Link: required, target URL (relative path / allowed)
• Text: button label
• Icon (optional): Font Awesome icon name (e.g. home, github; fa fa- prefix auto-added; or write fa fa-home directly)
• title (optional): hover tooltip text (not a color!)
• Alias: {% btn %}

Example

Effect

Materialize-style buttons with icon + ripple click effect.

6. githubCard

Purpose

Show a GitHub repo info card (repo name / description / stars / forks).

Syntax

{% githubCard user:username repo:repo-name %}

• user: required, GitHub username (error message if missing)
• repo: repo name
• Optional params: width / height (size, px suffix stripped automatically), theme (only effective when not default), target (only effective when not blank), client_id (GitHub OAuth client_id; for security reasons no client_secret support)

Example

Effect

Repo card: name + description + stars / forks, click to visit the repo. Depends on the GitHub API with lazy loading (noscript hint without JS, falls back to a link on failure).

Media & Content Tags

7. mermaid

Purpose

Render Mermaid diagrams (flowcharts / sequence diagrams / class diagrams etc.).

Front-matter Config (important)

You must declare it in the post front-matter before use, otherwise the Mermaid JS won’t load and diagrams won’t render:

mermaid: true

(Theme post.mermaid.enable: true is on by default; in specific: true mode only posts declaring mermaid: true load the Mermaid JS. Dark mode adapts automatically.)

Syntax

{% mermaid %}
graph TD
    A --> B
{% endmermaid %}

Example: flowchart (graph)

graph TD
    A[Build] --> B{Test}
    B -->|Pass| C[Deploy]
    B -->|Fail| D[Fix]
    D --> B
    C --> E[Monitor]

Example: sequence diagram (sequenceDiagram)

sequenceDiagram
    participant U as User
    participant S as Server
    participant D as Database
    U->>S: Send request
    S->>D: Query data
    D-->>S: Return result
    S-->>U: Respond with page

Example: class diagram (classDiagram)

classDiagram
    class User {
        +String name
        +login()
    }
    class Blog {
        +String title
        +publish()
    }
    User --> Blog

Effect

Mermaid renders to SVG diagrams, adapting to dark mode (the theme already handles it).

8. pdf

Purpose

Embed a PDF file viewer inside a post.

Syntax

{% pdf file-URL %}

• File URL: PDF address (local or remote)
• Auto type detection: drive.google.com → Google Docs preview; slideshare.net → Slideshare embed; otherwise → <embed> browser-native PDF viewer

Example

{% pdf /doc/Linux学习笔记.pdf %}

The example uses a real PDF already on the site (/doc/Linux学习笔记.pdf); replace it with any local or remote PDF URL.

Effect

Browser-native PDF viewer (<embed type="application/pdf">; the object_url PDF.js mode is not enabled), default height 550px, responsive.

9. insertmd

Purpose

Insert Markdown template fragments from source/ for content reuse (async rendering, recursive subdirectory support).

Syntax

{% insertmd 'path/filename.md' %}

• Path: relative to the source/ directory (e.g. _template/disclaimer.md)
• Directory: passing a directory recursively collects all .md files (alphabetical) and merges them
• Separator: optional second argument, rendered as a Markdown separator
• Missing path → build log error + empty output

Example

{% insertmd '_template/disclaimer.md' %}

Effect

The fragment content renders at the current position (content can nest other tag plugins).

10. wechat_dialog

Purpose

Render a WeChat chat interface card, for dialog examples / support scenarios.

Syntax (★ must be User: / Assistant: line format)

{% wechat_dialog %}
User: what the user says
Assistant: the AI/support reply
{% endwechat_dialog %}

• Line format: lines starting with User: = right-side user bubble (green); Assistant: = left-side assistant bubble (grey)
• Supports: multi-line content, Markdown rendering (bold / lists etc.)
• Alias: {% wd %} equals {% wechat_dialog %}

Example

Hi, I'd like to learn about the matery theme

Sure, how can I help?

What features does the theme support?

Content tags, galleries, search, comments and 20+ more features

Effect

WeChat-style chat bubbles, left/right split, avatar + bubble (avatar path hardcoded in the theme).

11. groupimage

Purpose

Display multiple images in a row/column grid layout (auto column splitting).

Syntax

{% groupimage count layout %}
![caption 1](image-URL-1)
![caption 2](image-URL-2)
{% endgroupimage %}

• Count: number of images (2–10; over 10 falls back to 3 per row)
• Layout (optional): images per row, - separated (e.g. 2-1 = 2 on the first row, 1 on the second; the sum must equal the count, otherwise it falls back to the default layout)
• Images: standard Markdown image syntax inside the tag body
• Alias: {% gi %} equals {% groupimage %}

Default layouts: 2→1,1 3→2,1 4→2,2 5→3,2 6→3,3 7→3,2,2 8→3,2,3 9→3,3,3 10→3,2,2,3

Example (3 images, 2+1 layout)

Effect

Image grid layout (columns per the layout), zoom on hover.

12. cardurl

Purpose

Show a summary card for a link (title, description, icon) for recommended links / cited resources.

Syntax

{% cardurl [url=target-link] [title=title] [desc=description] [avatar=icon-URL] %}

• Params: bracket [key=value] format
  • url required, target link (title falls back to url when missing)
  • title optional, card title
  • desc optional, description
  • avatar optional, icon image URL (shows a left icon when present)

Example

Effect

Link card: site icon + title + description, click to jump.

Advanced Tag Plugins

13. admonition (markdown-it-container)

Purpose

Render callout containers with the ::: type syntax (warning / note / info / attention / error), distinct from the note tag — implemented by the markdown-it-container plugin (registered in the root _config.yml, no front-matter needed).

Syntax

::: warning
*put warning content here*
:::

• Types: warning / note / info / attention / error / tip / hint — 7 types with semantic colors (warning/attention=amber #ffc107 / note=green / info=blue / error=red / tip=hint=blue)

Example

Effect

Callout containers with a left color bar + light background (div.warning etc. classes), adapting to light/dark mode.

14. Built-in Plugin Config (tag_tabs)

Purpose: CDN and layout config for the theme’s built-in tag plugins (reference: hexo-tag-common).

Config (theme config):

tag_tabs:
  cdn: https://fastly.jsdelivr.net/npm/   # CDN address (default jsdelivr)
  layout:                                  # layouts where it applies (currently unused)
    - post
    # - page
    # - home

Notes: neither cdn nor layout is actually consumed (tabs.js requires tag_tabs once and never references it afterwards); changing them has no effect — keep the defaults.

15. Content Encryption encrypt (added 2026-09-07)

Purpose

Encrypt a section of markdown content within a post. The reader enters a password to decrypt and expand the hidden content. Each snippet has its own independent password.

Syntax

{% encrypt password "prompt title" "content summary" %}
Encrypted markdown (can contain inner tags like note/timeline etc.)
{% endencrypt %}

Example

{% encrypt "test-secret" "Private Content" "This is a test encrypted block" %}
**Bold** and {% note %}inner note{% endnote %}
{% endencrypt %}

Effect

• Renders as an encrypted container (password box); enter the correct password to decrypt and expand
• Inner tag support: nested note/timeline etc. work inside the snippet (rendered via after_post_render second pass)
• No plaintext leakage: the rendered HTML contains no plaintext (encryption happens on the final HTML)
• No re-entry needed: after decryption, refreshes are password-free for 1 day (derived dk stored with TTL)

Notes

• Passwords and titles/summaries can both be quoted (Hexo strips quotes automatically)
• Automated test: tools/tests/unit/unit-encrypt.test.js + unit/unit-encrypt2.test.js (encryption round-trip); gate L2y covers post-decrypt refresh
• Two defects fixed (2026-09-23): ① placeholder residue — rendered output no longer leaks internal placeholder comments; ② concurrent crosstalk — multiple encrypted blocks on one page stay independent and never share keys. Fix: async: true + block-ownership check + functional replacement (see skill hexo-blog §encryption)

16. Mind map markmap (hexo-markmap plugin)

Purpose

Render an interactive mind map from a ```markmap code block (click to expand/collapse).

Performance optimisations (2026-09-25 / 09-26)

• On-demand injection: pages without a mind map no longer inject markmap plugin assets (288 pages save ~106KB each)
• Serial loader on encrypted pages: encrypted pages now use a serial loader, fixing dependency-order corruption after decryption (markmap running before its dependencies)

Automated tests

tools/tests/unit/unit-markmap-prune.test.js (6 cases, verifies zero injection on mind-map-free pages); rich-content-integration.test.js (L11, includes markmap rendering assertions)

Appendix: Tag Plugin Quick Reference

Common pitfalls:

• Showing {% xxx %} syntax in a code block requires wrapping with raw tags, otherwise the build fails with unknown block tag
• label puts the color BEFORE @ and text AFTER; button takes the link as the first argument
• Forgetting front-matter mermaid: true means diagrams won’t render (specific mode)
• wechat_dialog only accepts User: / Assistant: line format, not inline params
• On build failure, check the build log for Nunjucks Error first, then inspect the corresponding tag syntax