gzh-design

WeChat Official Account Article Layout Skill

Convert a Markdown article into HTML that can be copied and pasted directly into the WeChat Official Account editor without losing its styles after pasting.

The core assets are the references/ undertheme component library(one theme per set: design variables + complete HTML for each component + template skeleton + mapping rules), plus 1 set ofgeneral incremental library(code blocks / images·GIFs / small tag headings, shared by all themes). The theme list uses references/theme-index.md as the single source of truth. This SKILL.md is only responsible for the process and decisions;all specific HTML code must be taken from the component library, do not hand-write it from memory。

Workflow

0. Input and format normalization

The user may provide: Markdown text or a .md path (go directly to step 1),.docx、.pdf、.txt/plain text without markup, or web rich text.Non-Markdown input must first be read with references/format-normalize.md and converted into a Markdown draft according to its rules, followed by structural confirmation(for docx use scripts/extract_docx.py, for PDF use Read to read page by page + denoise, and for plain text infer the structure using heading heuristics). If nothing is provided, ask the user for it.

When the user says "just lay it out / auto layout / one-click / no need to ask", enterfully automatic mode: skip structural confirmation and theme-selection questions, automatically infer the structure, choose a theme automatically based on the subject matter, and perform layout validation; when delivering, include an explanation of the decisions (section structure, self-authored headings, and reasons for theme selection).

1. Select a theme (automatic recommendation system)

Read references/theme-index.md(the single source of truth for theme information).Actively recommend the theme that best fits the article's subject matter, then have the user confirm in one step—recommend but do not decide arbitrarily:

• The user has already specified a theme in the request → use it directly, do not ask.
• The subject matter has a clear match → ask a single confirmation question: "I suggest XX (reason). Confirm or switch to another set?" Provide the recommended option + 1~2 alternatives + "view all" as options. For subject matter→theme matching, refer to the "Applicable scenarios" column in theme-index:
  • Tutorials / reviews / lists / tool roundups / knowledge organization / methodology breakdowns (high information density) → Moyu Green
  • In-depth analysis / opinions / topics with a sense of power → red and white palette
  • Design / tech commentary / professional opinions / high-end brands → Graphite Minimalist Style
  • Zen / minimalist living / in-depth essays → Negative Space Zen Style
  • Tool comparisons / creative reviews (receipt visual metaphor) → Moyu Receipt Style
  • Internal newsletters / in-depth reviews / case retrospectives → Olive Notes
• No obvious preference → by default, use the first row of theme-index (Moyu Green) as the recommendation in first place, and use AskUserQuestion to let the user choose among several sets (if there are more than 4 themes, first ask by grouping them by temperament, then ask about the themes in that group).
• Fully automatic mode(the user explicitly says "just lay it out / one-click / no need to ask") → do not ask questions; automatically choose the theme that best fits the subject matter or the default first row, and explain the reason for the choice when delivering.
• The user is dissatisfied with all existing themes / wants a new style → Go through the "Custom Theme Generation" process (see the next section), and after generating and registering it, return to this step to select and use it.
• theme-index is empty → Stop layout, and tell the user that a theme style needs to be added first (the "Custom Theme Generation" process may be used).

Only after the user has settled on a theme does it proceed to component matching within that theme (steps 3 and 4: determine the article type → select the component combination according to that theme's recipe table).

2. Read the component libraries (two of them)

(1) According to the "component library file" column for that theme in theme-index, Read that theme's dedicated component library references/theme-{标识}.md(including theme-specific components such as introduction cards, section headings, body text markers, and signatures). (2) At the same time, Read the general incremental library references/common-components.md—the three categories of code blocks, images/GIFs, and small-label headings are shared by all themes; just apply the current theme's primary color.

Subsequent generation is entirely based on these two component libraries; all HTML must be taken from them, and must not be handwritten.

3. Parse the Markdown structure

Element	Recognition rule
Article title	# 标题 or frontmatter title
Opening introduction	At the very beginning of the article, the > 引用 block
Section heading	## 标题
Subsection	### 标题
Bold / highlight / underline	**文字** / ==文字== / <u>文字</u> or ++文字++
Quoted paragraph	A non-opening > 文字
Image / GIF	、(GIFs are handled the same as images)
Hyperlink / footnote	[text](url)(non-image) → body text text + superscript [n], numbered in order of first appearance; at the end of the article, generate a "References" list corresponding to them (general library 4a/4b)
Code / command / Prompt	``` 围栏代码块 ```, inline `code`
Divider / list	---、*** / - 项 or 1. 项
Table	| separated Markdown table (often from docx conversion) → prioritize the theme library's table/card components (the theme library's mapping rules take precedence)

After parsing the structure, determine the article type(take the dominant type; it may be composite): tutorial/how-to guide, roundup/tool list, opinion/in-depth analysis, interview/character feature, data review/report, life/emotional essay, case study. Basis for determination: many steps and commands → tutorial; many parallel items → roundup; many quotations and character narratives → interview; many numbers and comparisons → data; much argumentative reasoning → opinion.

4. Select the component combination according to the recipe → assemble the HTML

First check the selected theme library's "Article Type → Component Combination Recipe" table, and determine this article's core component combination and accent components according to the article type—do not randomly select components paragraph by paragraph just because you have the component library; the recipe ensures a stable layout character for articles of the same type. Elements outside the recipe should then be supplemented according to the theme library's mapping rule table.

Then assemble according to the theme library's **"Complete Article Template Skeleton" chapter**, replacing each Markdown element with the corresponding component:

• The skeleton order is based on the theme library, and different themes may have different skeletons; do not apply the skeleton of another theme.
• For inline markers, find the corresponding components in the selected component library by semantics(component numbering is not uniform across libraries; always go by semantics and do not apply fixed numbers):**加粗**→Primary color bold;==高亮==→Gradient background highlight;<u>文字</u> or ++文字++→Underline;~~文字~~→Highlighter (bottom half highlight);>引用→Quote highlight block.
• Fromgeneral incremental librarycomponents:``` 代码块 ```→ 1a dark / 1b light code block, inline `code`→ 1c；![说明](url)→ 2a image (only add caption component if there is a caption),.gif→ 2b GIF; for content that needs emphasissmall heading/emphasis→ 3a left vertical bar small heading or 3b pill label, golden quote→ 3d, tip sidenote→ 3e.Priority: first check the theme library mapping rule table——if the theme has an equivalent semantic component (such as its own golden quote/tip block), use the theme library version to keep the style consistent; only when the theme library has no corresponding component, use the general library 3x and recolor it to the theme color according to its color-switching rules.
• Convert hyperlinks to footnotes (general library 4a/4b): for every [text](url)in the body text (non-image) → first collect: assign each distinctfirst occurrence orderto each distinct (text,url) pair number [1] [2] …, and reuse the same number for repeated occurrences of the same pair; when assembling, replace the link with text + general library 4a superscript corner mark [n](using the theme primary color); after the last paragraph of the body text and before the author signature, use general library 4b to generate a "References" list, in one-to-one correspondence with the body text [n] order, with reused numbers listed only once. When the anchor text is empty, use the title or domain name as the label. If there are no hyperlinks in the text, do not generate this block.Do not leave external links as clickable <a>(external links in WeChat Official Account body text are not clickable).
• An article uses only the one set of components from the selected theme, without mixing across themes.
• For emphasis and small headings, use "small label/left vertical bar", not dashed boxes: when you need to highlight a small heading or a section of content, use a left vertical bar small heading (3a), pill label (3b), left vertical bar golden quote/tip block (3d/3e);do not use a dashed box around all sides (dashed border) around a title, as that is bulky and steals the show.

5. Validate compliance (mandatory)

After writing the generated HTML to the target file,you must run the validation script, and it is only complete when ERRORs are zero:

# 用脚本所在 skill 的绝对路径调用，HTML 参数也用其实际路径（两者目录通常不同）
<SKILL_ROOT>/scripts/validate_gzh_html.py <生成的.html 的实际路径>

It deterministically checks platform-prohibited items and <span leaf> wrapping. If it reports ERROR, go back to step 4 and fix it;half-width punctuation WARNINGs must likewise be fixed to 0 before delivery(this is the most frequent rework point in actual use).

6. Output

Product format: pure <section>…</section> body fragment, starting from the global container, do not wrap <!DOCTYPE>/<html>/<head>/<body>——the WeChat Official Account editor only accepts body fragments, and extra document shells will be discarded or interfere with pasting.

1. Clean body file: save the HTML to the current working directory, filename {原文件名}_排版_{主题中文名}({英文标识}).html(English identifier = theme-index component library filename with the theme- prefix and .md suffix removed). This is used for validation and as a manual paste fallback.
2. Preview page with a "Copy" button(lets the user copy with one click, no need to manually select all):

   <SKILL_ROOT>/scripts/wrap_preview.py <上面的干净正文.html>
   

   Produce {...}_预览.html——After opening in a browser, there is a "Copy to WeChat Official Account" button in the upper right corner. Click it once to copy the rendered rich text to the clipboard (equivalent to Ctrl+A/Ctrl+C), then paste it into the WeChat Official Account editor with Ctrl/⌘+V. The button and script are only in the preview shell,not inside the section being copied, so what is pasted into the WeChat Official Account is still clean and compliant body text.
3. Inform the user:Open {...}_预览.html → click "Copy" in the upper right corner → paste in the WeChat Official Account editor; and provide the path to the clean body text file as a fallback. Include the validation script conclusion (passed / remaining warnings).

Intelligent processing during generation (these are the features of this skill and must be done)

1. Automatic section numbering: assign according to the order in which ## appears, using 01/02/03…; if the final chapter is a conclusion/summary type, use the conclusion numbering variant specified by the theme library (such as ∞); if the theme library does not specify one, continue using numeric numbering.
2. English labels: generate English labels based on Chinese section titles (tested → TEST, tutorial → TUTORIAL, summary → SUMMARY, thoughts → THOUGHTS...); use the corresponding slot if the theme library has one.
3. Underline keywords in the body text (core feature): foreach body paragraph, proactively identify 1–3 of the most important phrases and mark them with that theme's underline CSS (see theme-index). Prioritize marking core viewpoints, conclusions, key data, and proper nouns; phrases should be 4–15 characters; if a whole paragraph has no key points, it may be left unmarked. Even if the original text has no bolding at all, proactively add underlines—it is the most frequently occurring basic mark.
4. Highlight keywords in the introduction: identify the core words in the opening quotation and mark them with the highlight component.
5. Table of contents extraction: from all ## , take the first 3 as the guide/table of contents key points (when the theme library has a table of contents component).
6. Signature on the opening introduction card: according to the article'sauthor or theme—if the article has a byline, write "—— Author Name"; if there is no clear author, use a short sign-off related to the theme or omit it directly.Do not always write "Jiamu"(the tail signature area likewise uses {{作者名}} as a placeholder, see item 7).
7. Tail author signature area (filled in by the author, only one place at the end)：By default, do not hard-code any name, use a placeholder byline so the user can replace it with their own.
   • First sentence (author introduction):我是 {{作者名}}，{{一句话简介，如：热衷于分享 AI 观察与干货}}——if the user provides a byline or bio in the request/preferences, fill it in directly; if not,keep {{作者名}} / {{简介}} as a placeholder, and remind the user during delivery to replace it with their own byline.
   • Second sentence (interaction prompt, generic and can be kept as is):如果你觉得今天这篇有收获，欢迎**点赞、在看、转发**三连，我们下篇见
   • The original text already has an author signature paragraph at the end(such as "I am XXX...") → directly use the original text's byline, do not replace it with a placeholder.
8. List conversion: process according to the theme library mapping rules; when there is no dedicated list component, convert to indented body paragraphs.
9. Chinese full-width punctuation: body text punctuation must always use full-width (，。！？：；""''（）—— …), do not use half-width , . ! ? : and English straight quotation marks " '。When generating HTML, write curly quotes ""'' directly; do not write straight quotes first and replace them afterward—straight quotes in the source text are converted on the spot during transcription.Exceptions: inside code blocks, inline code, and English proper nouns/URLs/code identifiers, keep them as-is.

Visual hierarchy (3 progressive tiers, common to all themes)

Tier	Purpose	Frequency	Means
Anchor tier	Strongest anchor: product name/step/CTA/core punchline	≤ 5 places in the whole text	Primary-color bold, dark background with white text quote
Mark tier	Body keywords, 1–3 places per paragraph	High frequency	Underline mark
Container tier	Quote blocks, concept labels, long-sentence emphasis	As needed	Light-background quote, highlighter, badge

Platform red lines (core; full checks are delegated to the validation script)

• Prohibited：<style>/<script>/<div>、class/id attributes,position:fixed/absolute/sticky、float、@media/@keyframes、display:grid, CSS variables, external fonts/CSS.
• Required: all styles inline style; all text nodes wrapped with <span leaf="">文字</span> (otherwise styles are lost after pasting).
• Usable：display:flex(limited),linear-gradient、border-radius、box-shadow、<section>/<p>/<span>/<strong>/<img>/<h3>。

Gotchas (pitfalls actually encountered in typesetting)

• Missing <span leaf> wrappingis the most common fatal error—after pasting into the WeChat official account, styles are lost across the board. Rely on the step 5 validation script as a fallback; do not skip it.
• Underline: implement paragraph by paragraph, 1–3 phrases per paragraph. Do not underline an entire paragraph (loses focus), and do not mark some paragraphs while missing others; key descriptions in list items must also be marked.
• Section numbering out of order: strictly follow the ## order, do not skip numbers; the conclusion numbering variant is only for the final chapter and cannot be used for middle chapters.
• Signature area exists and only at the end: use fixed copy, do not appear in the middle or in multiple places; if the source text already has an author signature/"like, watch, and share triple" type paragraph at the end, identify it andmerge it intothis single signature area/CTA card; do not keep the source paragraph and also generate another one.
• Fabricated image captions: only generate a caption component if there is actually caption text in ![说明](url) ;![](url) do not fabricate a caption for an empty alt.
• Images auto-fit, do not fill the width：<img> always max-width:100%;height:auto;display:block;margin:0 auto—display at the image's own size, centered; large images scale down to the container width, small images keep their original size.Do not use width:100%(it stretches small images and makes them blurry); only layout elements such as tables / cover cards / flowcharts use width:100%。
• Mixing components across themes: one article uses only the components of the selected theme + the common library, and does not borrow components from other themes.
• Anchor tier abuse: the strongest emphasis appears ≤ 5 times in the whole text; bolding everywhere means there is no emphasis.
• Omission of source content: every paragraph and every image must be converted, with none omitted; do not add or remove substantive source content on your own.
• Placeholder image residue: if the signature area/CTA component contains a business-card image placeholder (such as <img src="...名片或引导图URL">), if there is no real image URL, delete the entire line; do not leave placeholders in the output.
• The table of contents is a curated selection, not the full list: introduction/table of contents component displaythe 3 curated core highlights, not the complete chapter list; when there are more than 3 chapters, pick the 3 most important ones; do not force extra items in or mislead readers into thinking there are only 3 chapters.
• Do not use dashed boxes: to highlight titles/emphasis, use small labels or a left vertical bar (general library 3a–3e); do not use a border:…dashed dashed box around the title.Exception: dashed-line components explicitly defined by the theme library (such as the quote-box quote frame in Moyu Green or the oneliner-card highlight card) are stylistic features of that theme; use them normally according to the theme library usage.
• Do not mix half-width punctuation: if half-width commas, periods, or English straight quotation marks " ' appear in the body text, change them all to full-width; however, keep half-width symbols inside code blocks/inline code as-is; do not "full-width-ize" code.
• Code/Prompt must use code blocks: code, commands, and prompts in the article should use the general library code block components (1a/1b); do not stuff them into ordinary paragraphs or quote blocks, otherwise indentation and monospacing will be lost.
• Code blocks should be compact; avoid large blank spaces: use the general library 1a/1b "one <p style=\"margin:0\">per line" approach,never use white-space:pre—it will render the indentation before span in the HTML source and the line breaks between lines as a large left indent + blank lines; for indentation use only full-width spaces 　, and line spacing depends on line-height:1.6。
• Center pending-to-be-added materials：【插入…】, pending screen recordings / GIFs / videos / result images, and other placeholders should use the general library 2c centered material placeholder section(light background soft dashed box + centered icon and description); do not use a left-aligned notice block.
• Do not leave external links as <a>: all Markdown hyperlinks [text](url) in the body text must be converted to general library 4a superscript corner markers + 4b end-of-article reference list (URL displayed as plain text),do not output clickable <a href>—external links in Official Account body text are not clickable; leaving <a> will only be filtered into a bare URL. Numbers and the end-of-article list must correspond one-to-one; repeated URLs reuse the same number.

Custom theme generation (second workflow)

When the user wants a new style beyond the built-in themes (saying "generate a new theme set / custom style / make a component library based on this reference image", or being dissatisfied with all existing themes),read references/theme-generator.md and strictly follow its process：

1. Collect preferences: the theme description is required (or a reference image); name/ID/five colors/fonts/three TAG types/rounded corners/shadows may be left blank and will be auto-completed; ask for everything at once, do not follow up field by field.
2. Generate the block library HTML: execute the [generation prompt] at the end of theme-generator.md as-is, produce a complete block library of 45–75 Blocks, and save it to assets/theme-previews/{theme-id}.html—all blocks are arranged continuously on the same page; the user opens it in a browserto view the whole page at onceand confirm the style, rather than displaying and confirming block by block.
3. Convert + register: after the user confirms the style, convert it to the standard references/theme-{标识}.md（must add <span leaf=""> wrapper, remove preview-only ids, and complete the five sections, see step 3 of theme-generator.md for the rules), register in theme-index.md, run component_lint.py to 0 ERROR.
4. After delivery, the theme becomes a permanent selectable theme, and its subsequent typesetting has exactly the same rights as the built-in themes.

The generation stage is governed by the prompt rules; the stage of converting into the theme library is governed by this file's "Platform Red Lines" and "Specifications for Adding a New Theme" (when the two conflict, the latter takes precedence, because the theme library directly determines the typesetting output).

Specifications for Adding a New Theme

A new theme is named references/theme-{英文标识}.md , and its content must include:

1. Design variable quick reference table(primary color/light background/dark text/heading color/body text color/divider color, etc.)
2. Complete HTML for each component(inline styles + <span leaf=""> wrapping, complying with the above "Platform Red Lines")
3. Complete article template skeleton(component assembly order; if there are table of contents/navigation components, specify their position relative to the cover/introduction)
4. Article type → component combination recipe table(core component combination + accent components for each article type; the recipe is the key to stable typesetting character)
5. Markdown → component mapping rule table

After adding, register one line in references/theme-index.md (theme name / primary color / applicable scenarios / component library file / body text underline CSS), and run python3 scripts/component_lint.py . to confirm the component library has no anti-patterns (0 ERROR).

For regression test cases for triggering and theme selection, see references/eval-cases.md(used for regression verification during maintenance, and does not affect a single generation).