ZJU-REAL/Easel / skills/builtin/gzh-design
gzh-design
Verified微信公众号文章排版引擎:把 Markdown / Word(.docx) / PDF / 纯文本转成可直接粘贴进公众号编辑器的 HTML,自动章节编号、关键词标记、引言卡、目录、代码块、图片/GIF、作者签名;主题从 references/theme-index.md 组件库按题材推荐,支持"一键自动排版"与按描述/参考图生成自定义主题。触发:用户提到"公众号排版/微信排版/gzh"、想把文章(md/docx/pdf/纯文本)转成公众号 HTML、说"自动排版/一键排版"公众号内容。不用于普通网页/落地页/PPT。
README.en.md
View on GitHub> 🤝 **A joint project by Jiamu × [Moyu Xiaoli (摸鱼小李)](https://mp.weixin.qq.com/s/EMahAzgfAbRQrYukWE7_IQ)** — the components, theme design and quality bar are shaped by both authors' hands-on WeChat publishing practice. Special thanks to Xiaoli.
<div align="center">
# gzh-design-skill · WeChat Layout Skill
**Turn Markdown into polished HTML you can paste straight into the WeChat editor**
6 curated themes + theme generator · code blocks / images / GIFs · auto section numbers & keyword marks · two-gate quality checks
[](LICENSE)
[](https://claude.ai/code)
[](references/theme-index.md)
[](CONTRIBUTING.md)
[](#-quick-start)
English | [中文](README.md)
</div>
---
A layout Skill for AI agents (Claude Code / Codex / Cursor …). You write Markdown; it renders HTML with **fully inlined styles that survive pasting into the WeChat editor** — auto section numbers, keyword underlines, intro cards, code blocks, images, merged author signature — with scripts that deterministically enforce WeChat's platform limits.
## ✨ Features
- **6 curated themes**: Moyu Green (default) · Red & White · Graphite Minimal · Zen Whitespace · Moyu Ticket · Olive Journal — each a self-contained thick component library (design tokens + dozens of components + visual-hierarchy table + article-type recipe table).
- **Theme generator**: none fit? Describe a style in one line or drop a reference image, and generate a fresh component library saved for reuse (see `references/theme-generator.md`).
- **Full content support**: code blocks (dark/light, monospace), images, GIFs (with an animated badge), inline code, quotes, lists, product badges.
- **Smart layout**: auto section numbering (last chapter ∞ / ///), 1–3 keyword underlines per paragraph, intro card & TOC distilled from the body, de-duplicated signature.
- **Full-width CJK punctuation** in prose; kept as-is inside code blocks.
- **Paste-safe**: all styles inlined, every text node wrapped in `<span leaf="">`, avoiding `<style>/<div>/class/grid/position` that WeChat strips.
- **Two-gate quality checks**: `component_lint.py` (library source) + `validate_gzh_html.py` (final output) form a reproducible edit → verify → fix loop.
- **One-click copy**: a preview page with a **Copy** button — click to copy the rich text and paste straight into WeChat, no manual select-all.
## ✅ Good for / ❌ Not for
**✅ Good for**: opinion/analysis · tutorials/how-tos · reviews/tool roundups · knowledge notes/methodology · interviews/features · data recaps · lifestyle/personal essays · case studies — turning Markdown / Word / PDF / plain text long-form into paste-ready WeChat HTML; also generating custom themes from a description or reference image.
**❌ Not for**: generic web/landing pages (use a frontend skill) · slide decks (use a PPT skill) · pure image posters / social cards (use a social-card skill) · non-WeChat layout · **writing the article** (this skill only lays out — bring the Markdown first).
## 🗂 Common use cases
| Your content | How to lay it out |
|---|---|
| Opinion / deep long-form | Red & White or Graphite Minimal; keyword underlines + pull-quotes |
| Product review / tool roundup | Moyu Green or Moyu Ticket; step/tool-labels + cards, by recipe |
| Tutorial / how-to | Moyu Green; step-labels + code blocks + numbered lists |
| Data recap / annual report | Moyu Green or Olive Journal; data cards + tables |
| Zen / minimal essay | Zen Whitespace; generous whitespace + centered serif quotes |
| Editorial notes / deep review | Olive Journal; editor's note + sections + dark summary box |
| Word / PDF draft → WeChat | auto-normalize format → then pick a theme by topic |
| A style beyond the built-ins | Theme generator: make one from a line or an image |
## 🎨 6 Curated Themes
One long-form article laid out in all 6 themes (full-fidelity screenshots with real images):
<table>
<tr>
<td width="33%" align="center"><img src="https://github.com/isjiamu/gzh-design-skill/releases/download/assets-v1/lf-moyu-green.png?v=1" width="250"><br><sub><b>Moyu Green (default)</b></sub></td>
<td width="33%" align="center"><img src="https://github.com/isjiamu/gzh-design-skill/releases/download/assets-v1/lf-red-white.png?v=1" width="250"><br><sub><b>Red & White</b></sub></td>
<td width="33%" align="center"><img src="https://github.com/isjiamu/gzh-design-skill/releases/download/assets-v1/lf-graphite-minimal.png?v=1" width="250"><br><sub><b>Graphite Minimal</b></sub></td>
</tr>
<tr>
<td align="center"><img src="https://github.com/isjiamu/gzh-design-skill/releases/download/assets-v1/lf-zen-whitespace.png?v=1" width="250"><br><sub><b>Zen Whitespace</b></sub></td>
<td align="center"><img src="https://github.com/isjiamu/gzh-design-skill/releases/download/assets-v1/lf-moyu-ticket.png?v=1" width="250"><br><sub><b>Moyu Ticket</b></sub></td>
<td align="center"><img src="https://github.com/isjiamu/gzh-design-skill/releases/download/assets-v1/lf-olive-journal.png?v=1" width="250"><br><sub><b>Olive Journal</b></sub></td>
</tr>
</table>
> 📚 **All 6 themes → [docs/all-themes.md](docs/all-themes.md)** | or open `docs/gallery/index.html` for the interactive full HTML.
### Theme cheat-sheet
| | Theme | Best for |
|---|---|---|
|  `#059669` | Moyu Green (default) | Tutorials, reviews, checklists, tool roundups |
|  `#DC2626` | Red & White | Deep analysis, opinions, strong takes |
|  `#52525B` | Graphite Minimal | Design, tech commentary, premium brand |
|  `#4A5D52` | Zen Whitespace | Zen, minimal living, reflective essays |
|  `#059669` | Moyu Ticket | Tool comparisons, creative reviews (ticket motif) |
|  `#1e1f23` | Olive Journal | Editorial notes, deep reviews, case recaps |
> English slug, library file and underline CSS for each theme: see [`references/theme-index.md`](references/theme-index.md). Need another style? Have the AI generate one with the [theme generator](references/theme-generator.md).
## 🚀 Quick Start
```bash
# One-line install (recommended)
npx skills add https://github.com/isjiamu/gzh-design-skill
# Or manual clone
git clone https://github.com/isjiamu/gzh-design-skill.git ~/.claude/skills/gzh-design
```
Or just ask **any agent** (Claude Code / Codex / Cursor …):
> Please find and install the skill at https://github.com/isjiamu/gzh-design-skill
Then, once installed, tell your agent:
> Lay out `article.md` as WeChat HTML using the Moyu Green theme.
## 💬 Community
Scan to join the **official WeChat Work group** (dynamic QR, auto-invite) — chat about WeChat layout & Agent Skills:
<img src="https://github.com/isjiamu/gzh-design-skill/releases/download/assets-v1/group-qr.png" width="220" alt="WeChat Work group QR">
> QR expired? Add WeChat **`zuiyn_soul`** (note "gzh-design") to get invited.
## 📖 Workflow
1. **Pick a theme** — auto-suggests the best fit by topic and asks you to confirm (defaults to Moyu Green); or specify one, or generate a new one.
2. **Load libraries** — the chosen theme lib + the shared incremental lib (code/image/label).
3. **Parse Markdown** — headings, chapters, bold, highlight, quotes, images, code, lists.
4. **Assemble HTML** — from real components; apply numbering, underlines, full-width punctuation, signature.
5. **Validate** — run `validate_gzh_html.py`, ship only at 0 ERROR.
6. **Output** — a clean fragment + a preview page with a **Copy** button; open it, click "Copy to WeChat", then paste into the editor (no manual select-all).
## 🧩 Platform limits (enforced)
Output obeys: no `<style>/<script>/<div>`, no `class/id`, no `position:fixed/absolute/sticky`, `float`, `@media/@keyframes`, `display:grid`, CSS variables, external fonts; all styles inlined; every text node wrapped in `<span leaf="">`. Checked deterministically by scripts, not by model discipline.
## 🔁 Verifiable loop
```bash
python3 scripts/component_lint.py . # source gate: anti-patterns in libraries
python3 scripts/validate_gzh_html.py out.html # output gate: final HTML compliance
```
Source gate flags `white-space:pre` (blank bloat), full-border dashed frames in prose, and forbidden platform items — must be 0 ERROR. Output gate flags forbidden tags, `<span leaf>` wrapping, half-width punctuation — must be 0 ERROR / 0 half-width WARN.
## 💡 Why it's built this way
- **Constraint beats freedom** — preset palettes + fixed components lock in a quality floor instead of letting the model improvise each time.
- **Paste-safe by design** — fully inlined styles + every text node in `<span leaf="">`, avoiding exactly what the WeChat editor strips.
- **Quality by script, not discipline** — two gates (`component_lint` at source + `validate_gzh_html` on output) deterministically check platform rules and punctuation.
- **Model-agnostic** — layout logic lives in libraries and scripts, not any one model's tricks; Claude / GPT / Gemini / Chinese models all produce the same result.
- **Agent-friendly** — input and output are plain-text Markdown / HTML any agent can read, write, edit and verify — native to Claude Code / Codex / Cursor.
## 📁 Structure
```
gzh-design/
├── SKILL.md # layout workflow (agent entry)
├── references/ # 6 theme libs + generator + shared lib + theme-index + eval-cases
├── scripts/ # validate_gzh_html.py + component_lint.py
├── assets/ # sample-article.md + theme-previews/
└── docs/gallery/ # browser preview of themes
```
## 🎯 Principles
- **Constraint over freedom** — preset palettes and fixed components guarantee a quality floor.
- **Determinism to scripts** — hard rules go to the linters; the model only judges content.
- **Small labels, not dashed frames** — emphasis uses left bars / pill labels; dashed frames are reserved for the centered "asset placeholder".
- **Reproducible** — every lesson becomes a gotcha or a check, guarded by the verifiable loop.
- **Model-agnostic** — works with any capable LLM (Claude, GPT, Gemini, plus Chinese models like DeepSeek, Kimi, Qwen, GLM); layout lives in the libraries and linters, not model-specific tricks, so switching models keeps the same result.
- **Recipe over free choice** — pick the component combo from the theme's article-type recipe table first, then assemble; same-genre articles stay visually consistent.
- **Restrained color** — primary only at anchors (≤5/article), mostly white + gray, color as punctuation.
## 🧠 Make your own theme
### Theme generation — one line or one reference image
Not enough with the built-in 6? Have the AI make one. Driven by the second workflow in [`references/theme-generator.md`](references/theme-generator.md):
1. **Collect preferences** (asked all at once): theme description required (or a reference image); name / colors / font / radius / shadow / use-case auto-filled if blank.
2. **Generate a block library**: 45–75 blocks of full inline-style HTML saved to `assets/theme-previews/{id}.html` — review the whole page at once in a browser.
3. **Convert + register**: turn it into `references/theme-{id}.md` (add `<span leaf>`, the five required sections), register in theme-index, pass `component_lint.py` at 0 ERROR.
4. **First-class from then on**: use it exactly like a built-in theme.
> Try: *"Generate a new WeChat theme — mono magazine, Klein-blue accent, serif type"* or *"Build a component library from this reference image."*
### Color pairing — a repeatable palette structure the AI can auto-fill
Every theme is built on a **design-token palette** with fixed roles: a recognizable **primary** (anchors only, ≤5/article), **light tints** of it for card / quote / label backgrounds, one **contrasting accent** for highlights, a **neutral gray scale** carrying ~90% of the text, and a **light underline color** for per-paragraph keyword marks. Restraint: mostly white + gray, color only as punctuation, ≤2 highlights per paragraph.
Give just a primary color or a vibe, and the generator derives the whole harmonious palette (tints, borders, highlight, grays, underline) with readable contrast:
> *"Use #7C9EB2 misty-blue as the primary and generate a fresh travel-essay WeChat theme."*
## ❓ FAQ
**Will styles survive pasting into WeChat?** Yes — everything is inlined and every text node is `<span leaf="">`-wrapped, enforced by the validator.
**Can I add my own theme?** Two ways: (1) have the AI generate one via `references/theme-generator.md`; (2) hand-write one per `CONTRIBUTING.md` and open a PR.
**Can it output several themes at once?** Yes — say "lay this out in each of these themes" for a batch to choose from.
**How do I update?** Re-run `npx skills add https://github.com/isjiamu/gzh-design-skill`, or `git pull` in the install dir.
**What if the agent's output isn't compliant?** Run `scripts/validate_gzh_html.py`; fix on ERROR until both gates are green. Still stuck? Open an Issue.
## ⭐ Star History
If this project helps you, a Star means a lot 🙏
<a href="https://www.star-history.com/?repos=isjiamu%2Fgzh-design-skill&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=isjiamu/gzh-design-skill&type=date&theme=dark&legend=top-left&sealed_token=OSZCPLO_3NeTUKAtXcnNT6T3HuZwlFsH1HDGh6BcU0G2bdOm-5snTE01rzgYkwgNkF0pvraNI226pwK4jt9zYc4YuJ196yA1fcRRZKmfVQDMWqtE87dHqXn1E4v2q1mCWNFHzXAGJrCMEHx_0wwNmIVOg5nOaNCtRUYS2C_E1IlITdmy_yv7vpyVxqti" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=isjiamu/gzh-design-skill&type=date&legend=top-left&sealed_token=OSZCPLO_3NeTUKAtXcnNT6T3HuZwlFsH1HDGh6BcU0G2bdOm-5snTE01rzgYkwgNkF0pvraNI226pwK4jt9zYc4YuJ196yA1fcRRZKmfVQDMWqtE87dHqXn1E4v2q1mCWNFHzXAGJrCMEHx_0wwNmIVOg5nOaNCtRUYS2C_E1IlITdmy_yv7vpyVxqti" />
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=isjiamu/gzh-design-skill&type=date&legend=top-left&sealed_token=OSZCPLO_3NeTUKAtXcnNT6T3HuZwlFsH1HDGh6BcU0G2bdOm-5snTE01rzgYkwgNkF0pvraNI226pwK4jt9zYc4YuJ196yA1fcRRZKmfVQDMWqtE87dHqXn1E4v2q1mCWNFHzXAGJrCMEHx_0wwNmIVOg5nOaNCtRUYS2C_E1IlITdmy_yv7vpyVxqti" />
</picture>
</a>
## 🤝 Contributing · 📄 License
See [CONTRIBUTING.md](CONTRIBUTING.md). Co-built by **Jiamu × Moyu Xiaoli** — the component libraries and theme design standards come from both authors' WeChat publishing practice.
**AGPL-3.0 © 2026 Jiamu × Moyu Xiaoli.** Key terms:
1. **Attribution required** — keep the copyright and co-author notice.
2. **Derivatives must be open source** — any modified version, fork or redistribution must be released under AGPL-3.0 (or a compatible license) with full source.
3. **Network use must be open** — even deploying a modified version as a SaaS / web service (without distributing the code) requires publishing the source — this is what sets AGPL apart from GPL.
4. **No closed-source, proprietary, or paid-only distribution.**
Full terms in [LICENSE](LICENSE).
> 🤝 **AI Agent & model vendors welcome to co-create**: want to integrate gzh-design into your product or deeply co-build on it? We'd love that — contact Jiamu for the co-creation agreement.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |