Gzh Design Skill Wechat Markdown Formatter

gzh-design-skill: WeChat Official Account Markdown Formatter

Skill by ara.so — Design Skills collection.

This skill transforms Markdown documents into production-ready HTML for WeChat Official Accounts (微信公众号) with professional typesetting, automatic section numbering, keyword highlighting, and strict platform compliance. Ships with 6 battle-tested themes plus a theme generator.

What It Does

• One-click formatting: Markdown → inline-styled HTML that pastes cleanly into WeChat's editor
• 6 curated themes: Moyu Green (default), Red-White, Graphite Minimal, Zen Whitespace, Moyu Ticket, Olive Notes
• Smart typography: Auto section numbering, keyword underlining (1-3 per paragraph), full-width punctuation
• Platform compliance: All styles inline, text wrapped in <span leaf="">, no <div>/<style>/class/position/grid
• Rich components: Code blocks (light/dark), images, GIF badges, quotes, lists, product labels, intro cards
• Quality gates: Dual validation (source linting + output validation) ensures nothing breaks

Installation

Quick Install (Recommended)

npx skills add https://github.com/isjiamu/gzh-design-skill

Manual Clone

# For Claude Code
git clone https://github.com/isjiamu/gzh-design-skill.git ~/.claude/skills/gzh-design

# For Cursor
git clone https://github.com/isjiamu/gzh-design-skill.git ~/.cursor/skills/gzh-design

# For Codex
git clone https://github.com/isjiamu/gzh-design-skill.git ~/.codex/skills/gzh-design

Let AI Install It

Simply tell your agent:

"Install the skill from https://github.com/isjiamu/gzh-design-skill"

Core Workflow

The skill follows this deterministic pipeline defined in SKILL.md:

1. Theme Selection

User: "Format this article for WeChat using moyu-green theme"

The agent will:

• Read references/theme-index.md to map theme name to file
• Load the theme component library (e.g., references/theme-moyu-green.md)
• Load references/common-components.md for universal components (code blocks, images)

2. Content Analysis

User: "Convert article.md to WeChat HTML, auto-detect best theme"

The agent analyzes content type and recommends:

• Tutorial/Guide → Moyu Green (step labels, code blocks)
• Opinion/Analysis → Red-White or Graphite Minimal (emphasis on text hierarchy)
• Product Review → Moyu Ticket (card-based layout)
• Minimalist Essay → Zen Whitespace (breathing room)

3. HTML Assembly

The agent will:

• Parse Markdown structure (headings, paragraphs, code, images, lists)
• Apply automatic section numbering (末章 marked with ∞ or ///)
• Highlight 1-3 keywords per paragraph with theme-specific underlines
• Convert punctuation to full-width (正文 only, preserves half-width in code)
• Wrap all text nodes in <span leaf=""> for paste safety
• Inline all styles (no external CSS)

4. Validation

Two-checkpoint quality gate:

# Source checkpoint: Lint component library
python3 scripts/component_lint.py .

# Output checkpoint: Validate final HTML
python3 scripts/validate_gzh_html.py output.html

Must achieve:

• 0 ERRORs in both checks
• 0 WARNs for half-width punctuation in body text

5. Delivery

Generates two files:

• article_clean.html — Clean HTML for direct paste
• article_preview.html — Preview with "Copy to WeChat" button (one-click copy to clipboard)

Theme System

Using Built-in Themes

# Default (Moyu Green)
User: "Format article.md for WeChat"

# Specific theme
User: "Use red-white theme for this markdown"
User: "Apply zen-whitespace style to my essay"

Theme Quick Reference

Full specs in references/theme-index.md.

Generating Custom Themes

User: "Create a new WeChat theme inspired by tech magazines, 
use deep blue (#1e40af) as primary color, clean and professional"

The agent will:

1. Read references/theme-generator.md for generation workflow
2. Collect requirements (description, colors, fonts)
3. Generate complete component library (30+ components)
4. Save to references/theme-custom-{name}.md
5. Generate preview blocks in assets/theme-previews/

From a reference image:

User: "Generate a WeChat theme matching this screenshot: [attach image]
Call it 'emerald-tech'"

Component Usage

Code Blocks

Markdown:

​```python
def hello_wechat():
    return "内联样式,等宽字体,不折行"
​```

Renders with:

• Monospace font (Consolas/Monaco)
• Light background (#f9fafb) or dark (#1f2937) based on theme
• Horizontal scroll (no line wrapping)
• Preserved half-width punctuation

Images

![Alt text](https://example.com/image.jpg)

Auto-formatted with:

• Max width 100%, responsive
• Border radius from theme
• Optional caption below

GIFs get an animated corner badge.

Keyword Highlighting

Automatic in body text:

这段讲**核心概念**和实现方式。

Becomes:

• Bold text gets theme-colored underline
• 1-3 keywords per paragraph max (not every bold)
• Uses border-bottom (not text-decoration for better mobile support)

Section Numbering

## First Chapter
Content...

## Second Chapter
Content...

## Conclusion
Final thoughts...

Auto-numbered as:

• 一、First Chapter
• 二、Second Chapter
• ∞ Conclusion (last chapter gets ∞ or ///)

Intro Cards & TOC

User: "Add intro card and table of contents to this article"

Agent extracts:

• Intro card: First 2-3 compelling sentences
• TOC: All H2 headers with jump links

Product Badges

User: "Add tech stack badges for React, TypeScript, Tailwind"

Renders inline pill badges with theme colors.

Validation & Quality

Platform Compliance Checks

WeChat Official Account editor strips/breaks:

• ❌ <style>, <script>, <div> tags
• ❌ class, id attributes
• ❌ position: fixed/absolute/sticky
• ❌ display: grid, float
• ❌ @media, @keyframes, CSS variables
• ❌ External fonts (must use system stack)

This skill ensures:

• ✅ All styles inline on elements
• ✅ Text wrapped in <span leaf="">
• ✅ Only safe tags: <section>, <p>, <span>, <h*>, <pre>, <code>, <img>, <blockquote>, <ul>, <ol>, <li>

Running Validation

# Check component library source
python3 scripts/component_lint.py .

# Check final HTML output
python3 scripts/validate_gzh_html.py output.html

Component Lint catches:

• white-space: pre (causes layout breaks)
• Dotted borders around body text (visual noise)
• Forbidden CSS properties

HTML Validation catches:

• Missing <span leaf=""> wrappers
• Half-width punctuation in body (should be full-width: 。、！？)
• Forbidden tags/attributes
• External styles

Both must show 0 ERRORs before delivery.

Reproducible Quality Loop

# 1. Edit component library
vim references/theme-moyu-green.md

# 2. Validate source
python3 scripts/component_lint.py .

# 3. Generate test HTML
# (via agent: "format test article")

# 4. Validate output
python3 scripts/validate_gzh_html.py test_output.html

# 5. Fix until both pass

Documented in references/eval-cases.md.

Real-World Examples

Example 1: Tutorial Article

Input: tutorial.md

# 如何用 Claude Code 自动化排版

本文教你把 Markdown 一键转成公众号 HTML。

## 安装技能

先克隆仓库...

## 选择主题

推荐用**摸鱼绿**主题...

​```bash
npx skills add https://github.com/isjiamu/gzh-design-skill
​```

## 生成 HTML

运行命令后...

Command:

User: "Format tutorial.md for WeChat, use moyu-green theme, 
add step labels and intro card"

Output: HTML with:

• Auto-numbered sections (一、二、三)
• Keywords underlined in green (#10b981)
• Code block with light background
• Intro card extracted from first paragraph
• All punctuation converted to full-width

Example 2: Opinion Essay

Input: opinion.md

# AI 工具的本质是放大人的意图

很多人误解了 AI...

**核心观点**:工具不会取代思考...

Command:

User: "Convert opinion.md to WeChat HTML, recommend best theme"

Agent response:

Analyzing content... This is an opinion/analysis piece.
Recommended theme: red-white (classic editorial style)
Proceed? [yes]

Output: HTML with:

• Red underlines on key terms (#ef4444)
• Pull quotes for 核心观点
• Generous line spacing (1.8)
• Centered bold quote blocks

Example 3: Custom Theme Generation

Command:

User: "Generate a WeChat theme called 'tech-purple' with:
- Primary: #7c3aed (purple)
- For developer tools content
- Modern, clean, slightly playful
- Code blocks with dark background"

Agent workflow:

1. Loads references/theme-generator.md
2. Generates component library with:
   • Purple heading underlines
   • Dark code blocks (#1f2937 bg)
   • Purple link hover states
   • 30+ styled components
3. Saves to references/theme-custom-tech-purple.md
4. Generates preview: assets/theme-previews/tech-purple-preview.html

Usage after generation:

User: "Format devtools.md using tech-purple theme"

Example 4: Batch Conversion

Command:

User: "Convert all markdown files in ./articles/ to WeChat HTML,
use moyu-green for tutorials, red-white for opinions.
Detect type automatically."

Agent process:

for article in articles:
    content_type = analyze_content_type(article)
    theme = "moyu-green" if content_type == "tutorial" else "red-white"
    generate_wechat_html(article, theme)
    validate_output(output_file)

Configuration Files

Theme Index

references/theme-index.md — Single source of truth for themes:

| 主题名称 | 文件 | 主色 | 适用场景 |
|---------|------|------|---------|
| 摸鱼绿 | theme-moyu-green.md | #059669 | 教程/测评 |
| 红白色系 | theme-red-white.md | #dc2626 | 观点/深度 |

Theme Component Library Structure

Each theme-*.md contains:

## 设计变量
- 主色: #059669
- 正文色: #374151
- 背景色: #ffffff
- 强调色: #10b981

## 文字组件
### 正文段落
<p style="margin:16px 0;line-height:1.8;color:#374151">
  <span leaf="">正文内容</span>
</p>

### 小标题 (H3)
<h3 style="font-size:18px;font-weight:600;color:#059669;margin:24px 0 12px">
  <span leaf="">小标题</span>
</h3>

## 配方表（按文章类型）
- 教程类: step-label + 代码块 + 编号列表
- 测评类: tool-label + 对比卡片 + 数据框

Common Components

references/common-components.md — Cross-theme components:

## 代码块（浅色）
<pre style="background:#f9fafb;padding:16px;border-radius:8px;overflow-x:auto">
<code style="font-family:Consolas,Monaco,monospace;font-size:14px;white-space:pre">
<span leaf="">代码内容</span>
</code>
</pre>

## 动图标记
<div style="position:relative;display:inline-block">
  <img src="URL" style="max-width:100%">
  <span style="position:absolute;top:8px;right:8px;background:rgba(0,0,0,0.6);
               color:#fff;padding:4px 8px;border-radius:4px;font-size:12px">
    <span leaf="">GIF</span>
  </span>
</div>

Troubleshooting

Issue: Styles disappear after pasting

Cause: Used <div> or external <style> tags (WeChat strips them)

Fix: Ensure validate_gzh_html.py passes. All styles must be inline, structure must use <section>/<p>/<span>.

python3 scripts/validate_gzh_html.py output.html
# Look for ERRORs about forbidden tags

Issue: Code blocks render with broken layout

Cause: white-space: pre without overflow-x: auto, or missing monospace font

Fix: Component lint will catch this:

python3 scripts/component_lint.py .
# ERROR: Found white-space:pre without overflow-x

Use the corrected code block component from common-components.md.

Issue: Half-width punctuation warnings

Cause: Body text contains , . instead of ， 。

Fix: Validation shows WARNings:

python3 scripts/validate_gzh_html.py output.html
# WARN: Half-width comma at line 45

The agent should auto-convert during generation. If not, add explicit instruction:

User: "Format article.md, ensure all punctuation in body is full-width"

Issue: Keywords not highlighted

Cause: Markdown uses italics instead of bold, or too many bold items

Fix: Use **keyword** for emphasis. Agent auto-selects 1-3 per paragraph. If not triggering:

User: "Highlight these keywords with underlines: 核心概念, 实现方式, 质量保证"

Issue: Section numbering wrong

Cause: Markdown uses H1 for sections (should be H2)

Fix: Use H2 (##) for main sections, H3 (###) for subsections:

## 第一章 (becomes 一、第一章)
### 小节 (becomes plain H3, no number)

Issue: Custom theme not available

Cause: Theme generation created file but agent didn't index it

Fix: Regenerate theme and explicitly reference file:

User: "Use the theme from references/theme-custom-tech-purple.md 
to format this article"

Or update theme-index.md to add your custom theme.

Best Practices

1. Start with theme selection — Let agent recommend based on content type before generating
2. Validate every output — Run both linters, 0 ERRORs is non-negotiable
3. Keep component libraries DRY — Reuse from common-components.md, don't duplicate in themes
4. Test paste before publishing — Open preview HTML, click "Copy to WeChat", paste in editor, check on mobile
5. Use theme recipes — Each theme's "配方表" section defines proven component combinations per article type
6. Generate themes conservatively — Built-in 6 themes cover 90% use cases; custom themes add maintenance burden
7. Lock punctuation — Body text must use full-width, code blocks must preserve half-width (linter enforces this)
8. Minimize color usage — Primary color should appear ≤5 times per article (headings, key underlines), rely on grayscale for body

Advanced Usage

Normalizing Non-Markdown Inputs

User: "Convert report.docx to WeChat HTML using olive-notes theme"

Agent workflow:

1. Reads references/format-normalize.md
2. Extracts text from DOCX
3. Normalizes to Markdown (headings, lists, emphasis)
4. Applies theme and generates HTML

Supports: .docx, .pdf, plain text with ad-hoc formatting.

Batch Processing with Validation

# Process all files, fail fast on validation errors
for file in *.md; do
  echo "Processing $file..."
  # (agent generates HTML via skill)
  python3 scripts/validate_gzh_html.py "${file%.md}.html" || exit 1
done

Theme Variants

Create theme variants by editing:

User: "Create a dark mode variant of moyu-green called moyu-green-dark"

Agent duplicates theme-moyu-green.md, inverts colors:

• Background: #1f2937 → #ffffff
• Text: #374151 → #f9fafb
• Primary stays: #059669

(Note: WeChat doesn't support true dark mode, but useful for preview screenshots)

Integration with AI Agents

Claude Code

# In Claude Code chat
User: "Load gzh-design skill and format my-article.md with moyu-green theme"

Claude reads SKILL.md, loads theme, generates HTML, runs validation.

Cursor

# In Cursor composer
User: "@gzh-design format article.md for WeChat, auto-detect theme"

Cursor references skill via @ mention.

Codex / Custom Agents

Add skill to agent's system prompt:

system_prompt = f"""
You have access to gzh-design-skill for WeChat formatting.
Skill docs: {skill_md_content}
Theme index: {theme_index_content}
Always validate output with validate_gzh_html.py before delivering.
"""

File Structure Reference

gzh-design/
├── SKILL.md                      # Main workflow (this skill's source)
├── references/
│   ├── theme-index.md            # Theme registry (single source)
│   ├── theme-moyu-green.md       # Default theme library
│   ├── theme-red-white.md        # Editorial theme
│   ├── theme-graphite-minimal.md # Minimal theme
│   ├── theme-zen-whitespace.md   # Zen theme
│   ├── theme-moyu-ticket.md      # Ticket-style theme
│   ├── theme-olive-notes.md      # Notes theme
│   ├── theme-generator.md        # Custom theme creation workflow
│   ├── common-components.md      # Universal components (code, images)
│   ├── format-normalize.md       # DOCX/PDF → Markdown conversion
│   └── eval-cases.md             # Test cases + quality loop
├── scripts/
│   ├── validate_gzh_html.py      # Output validation (ERROR/WARN)
│   └── component_lint.py         # Source linting (anti-patterns)
├── assets/
│   ├── sample-article.md         # Demo input
│   └── theme-previews/           # Generated theme previews
└── docs/
    ├── all-themes.md             # Full theme screenshots
    └── gallery/
        └── index.html            # Interactive theme browser

Version & Compatibility

• HTML Output: Tested on WeChat Official Account editor (微信公众平台) as of 2026-07
• Python Scripts: Require Python 3.7+
• Agent Compatibility: Claude Code, Cursor, Codex, any agent that can read Markdown docs and run shell commands

License

AGPL-3.0 — See LICENSE file.

Contributing

See CONTRIBUTING.md for:

• Adding new themes
• Improving component libraries
• Reporting validation edge cases
• Submitting test articles

Links

• GitHub: https://github.com/isjiamu/gzh-design-skill
• Theme Previews: docs/gallery/index.html (open in browser)
• Validation Docs: references/eval-cases.md
• Example Output: docs/all-themes.md

Quick Start Checklist:

• Install skill: npx skills add https://github.com/isjiamu/gzh-design-skill
• Verify files: ls ~/.claude/skills/gzh-design/references/
• Format test article: "Format assets/sample-article.md using moyu-green"
• Validate output: python3 scripts/validate_gzh_html.py output.html
• Open preview: open output_preview.html
• Paste in WeChat editor and check mobile preview

You're ready to ship production-quality WeChat articles. 🚀