SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsgzh-design

gzh-design

Writing & research

View repository

Updated 10-16 10:56

About this skill

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 styling 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 of theshared 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;always take the specific HTML code 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 , converted into a Markdown draft according to its rules, and have its structure confirmed(for docx use scripts/extract_docx.py, for PDF use Read to read page by page + remove noise, 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 / don't ask", enterfully automatic mode: skip structure confirmation and theme selection questions, automatically infer the structure, automatically choose a theme based on the subject matter, validate the layout, and include decision notes when delivering (chapter structure, self-created titles, theme selection rationale).

1. Theme selection (automatic recommendation system)

Read references/theme-index.md(the single source of truth for theme information).Actively recommend the most fitting theme based on 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: "Recommend XX (reason). Confirm or switch to another set?" Options should include the recommended item + 1–2 alternatives + "view all". For subject matter→theme matching, refer to the "applicable scenarios" column in theme-index:
    • Tutorials / reviews / checklists / tool roundups / knowledge organization / methodology breakdowns (high information density) → Moyu Green
    • In-depth analysis / opinions / high-impact topics → Red and White series
    • Design / tech commentary / professional opinions / high-end brands → Graphite Minimalist style
    • Zen / minimalist living / in-depth essays → Zen Whitespace style
    • Tool comparisons / creative reviews (receipt visual metaphor) → Moyu Receipt style
    • Internal newsletter notes / in-depth reviews / case retrospectives → Olive Notes
  • No obvious preference → by default, put 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 (when there are more than 4 themes, first ask by grouping by vibe, then ask about the themes under that group).
  • Fully automatic mode(the user explicitly says "just lay it out / one-click / don't 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 next section), generate and register it, then return to this step to select it.
  • theme-index is empty → Stop typesetting, and inform the user that a theme style needs to be added first (the "Custom Theme Generation" process can be used).

Only after the user has settled on a theme do you 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 intro card, section headings, body text markers, and signature). (2) At the same time, Read the general incremental library references/common-components.md——code blocks, images/GIFs, and small tag headings are shared by all themes; just apply the current theme's primary color.

Subsequent generation is based entirely on these two component libraries; always take HTML from them and do not hand-write it.

3. Parse the Markdown structure

Element Recognition rule
Article title # 标题 or frontmatter title
Opening introduction The > 引用 block at the very beginning of the article
Section heading ## 标题
Subsection ### 标题
Bold / highlight / underline **文字** / ==文字== / <u>文字</u> or ++文字++
Quoted paragraph A non-initial > 文字
Image / GIF ![说明](URL)、![](xxx.gif)(GIFs are handled the same as images)
Code / command / prompt ``` 围栏代码块 ```, inline `code`
Divider / list ---、*** / - 项 or 1. 项
Table | A Markdown table separated by (often from docx conversion) → prefer 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 can 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 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 pick components randomly paragraph by paragraph once you have the component library; the recipe ensures stable typesetting character for articles of the same kind. Elements outside the recipe should then be supplemented according to the theme library's mapping rules table.

Then assemble according to the theme library's **"Complete article template skeleton" section**, 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 component in the selected component library according to semantics(component numbers are 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);>引用→ quoted highlight block.
  • FromGeneral Incremental Librarycomponents:``` 代码块 ```→ 1a dark / 1b light code block, inline `code`→ 1c；![说明](url)→ 2a image (only add a caption component if there is a caption),.gif→ 2b GIF; when something needs emphasis,subheading/emphasis→ 3a left vertical bar subheading or 3b pill label, punchline → 3d, tip side note → 3e.Priority: first check the theme library mapping rules table— if that theme has an equivalent semantic component (such as its own punchline/tip block), use the theme library version to keep the tone 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-swap rules.
  • An article uses only the one set of components from the selected theme, and does not mix across themes.
  • For emphasis and subheadings use "small labels/left vertical bars", not dashed boxes: when you need to highlight a subheading or a piece of content, use a left vertical bar subheading (3a), a pill label (3b), or a left vertical bar punchline/tip block (3d/3e);do not use a box with dashed borders on all sides (dashed border) around a heading, as that is clunky and steals the spotlight.

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> wrappers. 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

Artifact format: pure <section>…</section> body fragment, starting from the global container, without wrapping <!DOCTYPE>/<html>/<head>/<body>— the WeChat editor only accepts body fragments; 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 one 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 it in a browser, there is a "Copy to WeChat" button in the upper right corner; one click copies the rendered rich text to the clipboard (equivalent to Ctrl+A/Ctrl+C), then paste in the WeChat editor with Ctrl/⌘+V. The button and script are only in the preview shell,not inside the copied section, so what is pasted into WeChat is still a clean, compliant body.
  3. Tell the user:Open {...}_预览.html → click "Copy" in the upper right corner → paste in the WeChat editor; and provide the clean body file path as a fallback. Attach the validation script conclusion (passed / remaining warnings).

Smart handling during generation (these are this skill's features 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 with numeric numbering.
  2. English labels: Generate English tags based on Chinese section titles (actual test→TEST, tutorial→TUTORIAL, summary→SUMMARY, thoughts→THOUGHTS…), use them when the theme library has corresponding slots.
  3. Underline body keywords (core feature): Foreach body paragraphproactively identify 1–3 of the most important phrases and mark them with the theme's underline CSS (see theme-index). Prioritize core viewpoints, conclusions, key data, and proper nouns; phrases 4–15 characters; if a whole paragraph has no key points, you may skip it. Even if the original text has no bold at all, proactively add underlines—it is the most frequently occurring basic markup.
  4. Highlight introduction keywords: 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. Opening introduction card attribution: Determined by 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 simply omit it.Do not always write "Jiamu"(the tail signature area likewise uses the {{作者名}} placeholder, see item 7).
  7. Tail author signature area (filled in by the author, only one place at the end)：By default do not hardcode any name, use a placeholder signature so the user can replace it with their own.
    • First sentence (author introduction):我是 {{作者名}}，{{一句话简介，如：热衷于分享 AI 观察与干货}}—if the user provided a signature or bio in the request/preferences, fill it in directly; if not,keep the {{作者名}} / {{简介}} placeholder, and remind the user at delivery to replace it with their own signature.
    • 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 signature, do not replace it with a placeholder.
  8. List conversion: Handle according to the theme library's mapping rules; when there is no dedicated list component, convert to indented body paragraphs.
  9. Chinese full-width punctuation: Body punctuation must all be full-width (，。！？：；""''（）—— …); do not use half-width , . ! ? : and straight English quotation marks " '。When generating HTML, write curly quotes ""'' directly; do not write straight quotes first and replace them afterward—straight quotes in the original text are converted on the spot during transcription.Exception: Inside code blocks, inline code, English proper nouns/URLs/code identifiers, keep them as is.

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

Layer Function Frequency Means
Anchor layer Strongest anchor: product name/step/CTA/core quotation ≤ 5 places in the whole text Primary-color bold, dark background with white text quote
Marker layer Body keywords, 1–3 places per paragraph High frequency Underline marking
Container layer Quote blocks, concept tags, long-sentence emphasis As needed Light-background quote, highlighter, badge

Platform red lines (core; full check is delegated to the validation script)

  • Forbidden：<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 in <span leaf="">文字</span> (otherwise styles are lost after pasting).
  • Allowed：display:flex(limited),linear-gradient、border-radius、box-shadow、<section>/<p>/<span>/<strong>/<img>/<h3>。

Gotchas (pitfalls actually encountered in real typesetting)

  • Missing <span leaf> wrappingis the most common fatal error—after pasting into the official account, the styles are lost entirely. Rely on the step 5 validation script as a backstop; do not skip it.
  • Underlining: 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 ## order, do not skip numbers; the conclusion numbering variant is only used for the final chapter, and cannot be used for middle chapters.
  • The signature area exists and is only one at the end: use fixed copy, do not place it in the middle or in multiple places; if the original text already has an author signature/"like, watching, and forwarding triple combo"-type paragraph at the end, identify andmerge it intothis single signature area/CTA card, do not keep the original paragraph and generate another one.
  • Fabricated image captions: only generate a caption component if there is actual caption text in ![说明](url) ;![](url) empty alt should not have a fabricated caption.
  • Images adapt to content, do not fill the width：<img> always max-width:100%;height:auto;display:block;margin:0 auto—display at the image's own size and center it; large images shrink to the container width, small images keep their original size.Do not use width:100%(it will also stretch small images and make them blurry); only layout elements such as tables / cover cards / flowcharts use width:100%。
  • Mixing components across themes: an article uses only the components of the selected theme + the general library, and does not borrow components from other themes.
  • Anchor layer abuse: the strongest emphasis should be used no more than 5 times in the whole article; bolding everywhere means there is no emphasis.
  • Omission of original content: every paragraph and every image must be converted, none may be omitted; do not add or remove substantive content from the original.
  • Placeholder image residue: if the signature area/CTA component contains a business card image placeholder (such as <img src="...名片或引导图URL">), delete the entire line when there is no real image URL, and do not leave the placeholder in the output.
  • The table of contents is a selection, not complete: the preface guide/table of contents component displays3 selected core highlights, not a complete chapter list; when there are more than 3 chapters, pick the 3 most important ones, do not force extra ones in or mislead readers into thinking there are only 3 chapters.
  • Do not use dashed boxes: to highlight titles/emphasis, use small labels or left vertical bars (general library 3a–3e), do not use border:…dashed a dashed box around the title.Exception: dashed components explicitly defined by the theme library (such as Moyu Green's quote-box quotation box and oneliner-card highlight card) are stylistic features of that theme, and are used normally according to the theme library's usage.
  • Do not mix punctuation with half-width: half-width commas, periods, and English straight quotation marks " ' appearing in the body text must all be changed to full-width; but half-width symbols inside code blocks/inline code remain as they are, do not "full-width-ize" code.
  • Code/Prompt must use code blocks: Code, commands, and prompts in the article must use the general-purpose library code block components (1a/1b); do not stuff them into normal paragraphs or quote blocks, otherwise indentation and monospacing will be lost.
  • Code blocks must be compact; avoid large blank spaces: Use the general-purpose library 1a/1b "one <p style=\"margin:0\">per line" approach,never use white-space:pre—it renders the indentation before the span in the HTML source and the newlines between lines as-is, producing a large left indent plus blank lines; for indentation use only the full-width space 　, and for line spacing rely on line-height:1.6。
  • Center materials pending to be added：【插入…】, placeholders such as pending screen recordings / GIFs / videos / result images, use the general-purpose library 2c centered material placeholder section(light background with a soft dashed border + centered icon and description); do not use left-aligned tip blocks.

Custom theme generation (the second workflow)

When the user wants a new style besides the built-in themes (saying "generate a new theme / custom style / make a component library set based on this reference image", or is unsatisfied 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/corner radius/shadow may be left empty and will be auto-completed; ask everything at once, do not ask field by field.
  2. Generate the block library HTML: Execute the [generation prompt] at the end of theme-generator.md as-is, producing a complete block library of 45–75 Blocks, saved to assets/theme-previews/{theme-id}.html—all blocks are laid out continuously on the same page; the user opens it in the browserto view the entire page at onceto confirm the style, without showing and confirming block by block.
  3. Convert + register: After the user confirms the style, convert to the standard references/theme-{标识}.md（must add the <span leaf=""> wrapper, remove preview-only ids, and fill in the five sections; for rules see step 3 of theme-generator.md), register it in theme-index.md, and run component_lint.py to 0 ERROR.
  4. After delivery, the theme becomes a permanent selectable theme, and thereafter has exactly the same rights as built-in themes for layout.

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 layout output).

Specifications for Adding a New Theme

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

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

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

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