SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsgzh-design

gzh-design

Design & creation

View repository

Updated 10-15 22:38

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 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 label 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;specific HTML code must always 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/unmarked plain text, 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 based on the subject matter, perform layout validation, and include a decision explanation when delivering (chapter structure, self-created titles, reasons for theme selection).

1. Select theme (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: "Suggest using XX (reason), confirm or switch to another set?" The 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 / powerful topics → Red and White series
    • 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 newsletter notes / in-depth reviews / case retrospectives → Olive Notes
  • No obvious preference → by default, use the first row of theme-index (Moyu Green) as the recommended item 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 according to temperament, then ask about the themes under 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), generate and register it, then return to this step to select it.
  • theme-index is empty → Stop the layout, and tell the user they need to add a theme style first (they can go through "Custom Theme Generation").

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 the introduction 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 label 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 ++文字++
Quote paragraph A non-opening > 文字
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 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 temperament for articles of the same type. For elements outside the recipe, supplement them according to the theme library's mapping rule 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; different themes may have different skeletons, so do not apply another theme's skeleton.
  • For inline markers, find the corresponding component in the selected component library by semantics(component numbers are not uniform across libraries; always go by semantics and do not apply fixed numbers):**加粗**→ primary-color bold;==高亮==→ solid light-background highlight;<u>文字</u> or ++文字++→ underline;~~文字~~→ highlighter (solid light background);>引用→ quote highlight block.
  • Fromthe General Increment Librarycomponents:``` 代码块 ```→ 1a dark / 1b light code blocks, inline `code`→ 1c；![说明](url)→ 2a images (add a caption component only if there is a caption),.gif→ 2b GIF; when something needs emphasis,subheading/emphasis→ 3a left-bar subheading or 3b pill label; for key quotes → 3d, for tip side notes → 3e.Priority: first check the theme library mapping rules table— if the theme has an equivalent semantic component (such as its own key quote/tip block), use the theme library version to keep the style consistent; only when the theme library has no corresponding component should you use the general library 3x and recolor it to the theme color according to its recolor rules.
  • An article uses only the one set of components from the chosen theme, and does not mix across themes.
  • For emphasis and subheadings, use "small labels/left bars", not dashed boxes: when you need to highlight a subheading or a section of content, use a left-bar subheading (3a), a pill label (3b), or a left-bar key quote/tip block (3d/3e);do not use a dashed border on all sides (dashed border) around a title, as that is clunky 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 zeroed out:

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

It deterministically checks platform prohibitions 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).

Gradient background WARNINGs must be handled item by item: text highlighting, quote/data/guide card backgrounds should by default be changed to solid colors within the theme or rgba solid colors; if the user explicitly requests keeping them, note in the delivery that they may trigger darkmode-no-gradient pop-ups. Purely decorative gradients will also be flagged, and it has not yet been confirmed that they will not trigger pop-ups; if kept, explain the same risk.

6. Output

Artifact 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 = the 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, eliminating manual select-all): 
    <SKILL_ROOT>/scripts/wrap_preview.py <上面的干净正文.html>
    Produce {...}_预览.html— after opening it 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 in 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 gets pasted into the WeChat official account is still a clean, compliant body.
  3. Tell the user:Open {...}_预览.html → click "Copy" in the upper right corner → paste in the WeChat official account 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 the features of this skill and must be done)

  1. Automatic section numbering: by ## Order-of-appearance numbering 01/02/03…; if the final chapter is a conclusion/summary type, use the conclusion numbering variant specified by the theme library (e.g., ∞); if the theme library does not specify one, continue with numeric numbering.
  2. English label: Generate an English label based on the Chinese chapter title (hands-on test → TEST, tutorial → TUTORIAL, summary → SUMMARY, thoughts → THOUGHTS…); use it when the theme library has a corresponding slot.
  3. Body keyword underline (core feature): Foreach body paragraphactively 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 should be 4–15 characters; a paragraph with no key points may be left unmarked. Even if the original text has no bold at all, actively add underlines—it is the most frequently occurring basic mark.
  4. Introduction keyword highlight: Identify the core words in the opening hook and mark them with the highlight component.
  5. Table of contents extraction: From all ## take the first 3 as the guide/table of contents points (when the theme library has a table of contents component).
  6. Opening quote card attribution: Depends on 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 footer signature area likewise uses the {{作者名}} placeholder, see item 7).
  7. Footer author signature area (filled in by the author, only one place at the end)：By default, do not hard-code any person's 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(e.g., "I am XXX…") → directly reuse the original 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 always use full-width (，。！？：；""''（）—— …); do not use half-width , . ! ? : and English straight quotes " '。When generating HTML, write curly quotes ""'' directly; do not write straight quotes first and replace them afterward—straight quotes in the original text should be converted on the spot during transcription.Exception: Inside code blocks, inline code, and English proper nouns/URLs/code identifiers, keep them as is.

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

Level Function Frequency Method
Anchor level Strongest anchors: product names/steps/CTA/core hook lines ≤ 5 places in the whole text Primary-color bold, dark background with white text quote
Marking level Body keywords, 1–3 places per paragraph High frequency Underline marker
Container layer Blockquotes, concept tags, long-sentence emphasis As needed Light-background quotes, highlighters, badges

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),border-radius、box-shadow、<section>/<p>/<span>/<strong>/<img>/<h3>。
  • Gradient background compatibility: gradients can render, but may trigger WeChat Official Account darkmode-no-gradient content structure detection; use solid colors by default for text and card backgrounds, and do not add extra gradients. For old components/custom themes that encounter this item, also handle it according to Step 5.

Gotchas (pitfalls actually encountered in real 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.
  • Underlining: implement paragraph by paragraph, 1–3 phrases per paragraph. Do not underline an entire paragraph (it loses focus), and do not mark some paragraphs while missing others; key descriptions in list items must also be marked.
  • Section numbering disorder: strictly follow the ## order, do not skip numbers; the conclusion numbering variant is only used for the final chapter and cannot be used for middle chapters.
  • There is exactly one signature area, at the end: use fixed copy, do not have it appear in the middle or in multiple places; if the original text already has an author signature/"like, watch, and share triple combo"-type paragraph at the end, identify it andmerge it intothis single signature area/CTA card; do not keep the original paragraph and then generate another one.
  • Fabricated image captions: only generate a caption component if there is actually caption text in ![说明](url) ;![](url) do not fabricate captions for empty alt text.
  • 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, centered; large images shrink to the container width, small images keep their original size.Do not use width:100%(it will 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.
  • Abuse of the anchor layer: the strongest emphasis should appear ≤ 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, with none omitted; do not add or remove substantive original content on your own.
  • Leftover placeholder images: 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; do not leave the placeholder in the output.
  • The table of contents is a selection, not the full list: the preface guide/table of contents component displays3 selected core highlights, not the complete chapter list; when there are more than 3 chapters, pick the 3 most important ones, and do not force in more or mislead readers into thinking there are only 3 chapters.
  • Do not use dashed boxes: to highlight titles/emphasis, use small tags or a left vertical bar (general library 3a–3e), do not use border:…dashed A dashed border box surrounds the title.Exception: Dashed-border components explicitly defined in the theme library (such as Moyu Green's quote-box quote frame and oneliner-card highlight card) are stylistic features of that theme; use them normally according to the theme library's usage.
  • Don't mix half-width punctuation: If half-width commas, periods, or straight English quotation marks " ' appear in the body text, change them all to full-width; but keep half-width symbols inside code blocks/inline code as they are, and do not "full-width-ize" code.
  • Code/Prompts must use code blocks: Use the general library code block components (1a/1b) for code, commands, and prompts in the article; do not stuff them into ordinary paragraphs or quote blocks, otherwise indentation and monospacing will be lost.
  • Code blocks should be compact and avoid large blank spaces: Use the general library 1a/1b "one per line <p style=\"margin:0\">" approach,never use white-space:pre—it renders the indentation before spans and line breaks in the HTML source as a large left indent + blank lines; for indentation use only full-width spaces 　, and for line spacing rely on line-height:1.6。
  • Center pending materials：【插入…】, placeholders such as pending screen recordings / GIFs / videos / result images should use the general library 2c centered material placeholder section(light background soft dashed border box + centered icon and description), not a left-aligned tip block.

Custom theme generation (second workflow)

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

  1. Collect preferences: Theme description is required (or a reference image); name/ID/five colors/fonts/three TAG types/rounded corners/shadows can be left blank and will be auto-completed; ask for everything at once, do not ask field by field.
  2. Generate 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 laid out continuously on the same page, and the user opens it in a browserto browse the whole page at onceto confirm the style, without 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 chapters, see step 3 of theme-generator.md for the rules), 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 subsequent typesetting has exactly the same rights as 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

New themes are named references/theme-{英文标识}.md , and the 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 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(the core component combination + accent components for each article type; the recipe is the key to stable typographic 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 for triggering and theme selection, see references/eval-cases.md(used for regression verification during maintenance, does not affect a single generation).