Convert Markdown articles into elegant Official Account HTML, supporting multi-theme switching, structured components, and SVG opening animations.
Usage
# 默认模式（纯净排版，无组件无动画）
/wechat-styler path/to/article.md
/wechat-styler path/to/article.md --theme kami
# 组件模式（Agent 智能改写 + 开场动画 + 8 种结构化表达）
/wechat-styler path/to/article.md --components
# 丰富组件模式（仅在用户明确要求“激进一点 / 多用组件”时启用）
/wechat-styler path/to/article.md --components --component-density rich
/wechat-styler "articles/*.md" --theme kami
Output to specified path/wechat-styler path/to/article.md --output path/to/output.html
**两种模式：**
- **默认模式**：直接转换，克制排版，无组件无动画。90% 场景用这个。
- **组件模式（`--components`）**：Agent 分析文章结构，智能改写 Markdown，自动加开场动画。生成前向用户确认。
组件密度由 Agent 改写层控制，不传时保持 `standard`：
| 密度 | 触发方式 | 结构组件预算 |
|------|----------|--------------|
| `restrained` | 用户说“克制、少组件、轻排版” | 2-4 个 |
| `standard` | 默认 | 3-6 个 |
| `rich` | 用户说“激进一点、丰富一点、多用组件” | 7-12 个；超过 8000 字可到 14 个 |
普通图片、正文引用和行内高亮不计入结构组件预算。密度只改变组件候选数量，不放宽防重复、卡片短文本和微信兼容规则。
## 可用主题
| 主题 | 命令 | 风格 | 适用场景 |
|------|------|------|----------|
| zhijian（默认） | `--theme zhijian` | 暖纸感 × 顾问可信度 | 智见AI 品牌内容 |
| kami | `--theme kami` | 纸感编辑排版 | 深度文章、商业分析 |
| magazine-ink | `--theme magazine-ink` | 墨水经典杂志 | 通用杂志内页 |
| magazine-indigo | `--theme magazine-indigo` | 靛蓝研究风 | 技术研究、深度调研 |
| magazine-forest | `--theme magazine-forest` | 森林田野笔记 | 非虚构、自然叙事 |
| elegant | `--theme elegant` | 优雅复古 | 商业案例、知识分享 |
| modern | `--theme modern` | 现代简约 | 科技产品、教程 |
| minimal | `--theme minimal` | 极简主义 | 哲学思考、个人随笔 |
主题详情、YAML 参数、扩展指南见 `references/theme-guide.md`。
## 工作流程
### 默认模式
用户只给文件路径和主题，Agent 直接调用 `convert.mjs` 转换，不做 Markdown 改写。
### 组件模式（`--components`）
Agent **不直接调用 convert**，先执行 5 步智能改写流程：
**写作层前置硬门：先检查段落密度**
WeChat Styler 不负责把拥挤长段自动切开。段落边界属于写作语义，渲染器按标点拆段会破坏作者节奏。组件改写前先运行：
```bash
npm run qa:density -- /absolute/path/to/article.md --strict
If it fails, stop the layout and return to the upstream Markdown to split paragraphs according to the transition points of facts, judgments, mechanisms, examples, boundaries, and actions. Do not use smaller font sizes, larger line heights, or additional components to cover up a wall of body text.
Step 1: Analyze the article structure
Read the entire Markdown and identify content suitable for presentation with components (tables→comparison cards, processes→step blocks, quotable lines→quote blocks, etc.). Only rewrite content that is truly suitable, and follow component-density to execute the budget; when unspecified, use standard 's 3-6. See references/component-guide.md。
⛔ Anti-duplication hard rule: the core principle of quote blocks/tip blocks/warning blocks isreplace the original text, not append. If the original text already states the same meaning clearly, do not append a component after the original text to repeat it. The correct approach is to delete the original summary sentence and keep only the component with higher visual weight; or, if the original text already expresses it fully, do not add a component. Before generating, you must scan the full text to confirm there is no duplication.
⛔ Fence format hard rule：:::compare / :::flow / :::timeline must occupy its own line, with blank lines before and after. A :::compare immediately following body text will not be parsed and will be displayed as raw markdown.
Step 2: Extract opening animation parameters
Infer the title (frontmatter.title), subtitle (one sentence for the core viewpoint), and tags (no more than 3 keywords) from the article content, and choose a template (see below).
Step 3: Confirm with the user
组件改写计划:
• 开场动画(typewriter): 标题「初识 WorkBuddy」/ 副标题「...」/ 标签: ...
• 「专家对比表」→ 对比卡片
• 「Ask/Plan/Craft」→ 对比卡片
• 「用好 WorkBuddy 的核心」→ 金句块
确认后开始生成?
Step 4: Pre-generation check (required)
Before calling convert, you must check the rewritten Markdown item by item against references/component-guide.md 's "Pre-generation Checklist":
- Whether image insertion positions are after complete paragraphs (not in the middle of sentences)
- Whether quote blocks/tip blocks/warning blocks duplicate the original text
:::compare/:::flowWhether the- Whether matrix comparisons are mistakenly converted to compare
- Whether the opening animation title length exceeds the viewBox
- Whether the number of structural components falls within the selected density budget
- Whether the paragraph density hard gate passes; record the median, P90, proportion of 100-character long paragraphs, and the longest consecutive long paragraph
Step 5: Generate
Rewrite the Markdown in memory (without changing the original file), then call convert:
node scripts/convert.mjs /tmp/rewritten.md --theme zhijian --components \
--strict-density \
--cover --cover-template typewriter \
--cover-title "..." --cover-subtitle "..." --cover-tags "..."
--components When enabled, automatically includes --cover(opening animation).
After generating HTML,zhijian the theme must undergo a mobile visual check:
npm run qa:mobile -- /absolute/path/to/article.html \
--expect-zhijian --strict-image-uniqueness \
--screenshot /tmp/article-mobile.png
Check items include horizontal overflow at a 390px viewport, broken images, abnormally repeated image URLs, alignment of quotation symbols with the first line in the same paragraph, whether quotes mistakenly use a left vertical bar, and the warm terracotta hierarchy of H2. If it fails, fix the layout first, then inject into the Official Account.
convert.mjs By default, a paragraph density soft gate report is printed; release candidates must pass --strict-density. This gate automatically blocks obvious walls of text; consecutive ultra-short paragraphs only prompt manual review and cannot be judged a failure based on quantity alone. The renderer does not automatically modify the body text.
SVG opening animation
--components mode automatically includes an opening animation. SVG SMIL animation only plays on first load, so it is used only for the opening; static components are used elsewhere.
5 templates
| Template | Parameter values | Character | Fit |
|---|---|---|---|
| Ink Charm Opening | ink-wash (default) |
Ceremonial feel · ink dot diffusion | Methodology, branding, courses |
| Typewriter flow | typewriter |
Geeky feel · character-by-character typing · cursor follow | Technical tutorials, tool introductions |
| Scroll unfolding | scroll-painting |
Narrative feel · double horizontal lines · gradual immersion | Case studies, retrospectives, stories |
| Focus spotlight | spotlight |
Sense of judgment · spotlight · title scaling | Opinions, reviews, trends |
| Minimalist line drawing | minimal-sketch |
Restrained · whitespace · breathing dots | Essays, thoughts, reflections |
Agent template selection logic
- "tutorial/tool/technical/CLI/Agent/development" → typewriter
- "case study/retrospective/story/implementation/combat record" → scroll-painting
- "judgment/opinion/trend/review/analysis" → spotlight
- "essay/thought/reflection/monthly/annual" → minimal-sketch
- Default/brand course/methodology → ink-wash
After the Agent selects a template, it clearly tells the user during the confirmation step: "I chose template X because the article has feature Y; you can change it." When uncertain, it defaults to ink-wash.
For template design principles and the pitfalls checklist, see references/svg-animation-design.md。
Inject into the WeChat editor
The WeChat editor's paste filter strips <animate> tags. The current stable path is to operate the DOM directly with OpenCLI:
export OPENCLI_PROFILE="<your-opencli-profile>"
export WX_EDITOR_URL="https://mp.weixin.qq.com/..."
node scripts/inject-to-wechat.mjs article_wechat.html
Publishing backend selection rules: The built-in Chrome in Codex can only become an injection backend if the official account editing page allows DOM access and writes. The current Chrome Browser security policy will, at mp.weixin.qq.com/cgi-bin/appmsg refuse page access and explicitly prohibit bypassing it via CDP, so it cannot be used to inject or verify SVG animations. When blocked by this policy, use OpenCLI directly; do not work around it via CDP, other browser automation, or indirect scripts. In the future, the default backend can be adjusted only after completing four live tests on the same editing page: "read-only probe → body write → <animate> read-back → draft save".
Stable publishing mode:
node scripts/inject-to-wechat.mjs article_wechat.html \
--reuse-current \
--title "公众号标题" \
--summary "转发摘要" \
--sync-cover-from-body \
--cover-file /path/to/local-cover.jpg \
--save-draft \
--report /tmp/wechat-publish-report.json
--cover-file is the recommended explicit cover entry point: when a cover already exists, it is replaced with the specified file; when there is no cover, it automatically opens the image library, uploads the local cover, selects the asset, and completes "Next" and crop confirmation in sequence. Only when using --sync-cover-from-body and not passing a file will it prefer to keep the existing cover or select the first image from the body. For local covers, 2.35:1 is recommended; when over 180KB, it is automatically compressed on macOS into a JPEG suitable for page injection.
The injector polls to locate the body editing area, avoiding the title ProseMirror; syncs the title and summary; automatically compresses remote images over 2MB; waits for WeChat to finish image transfer; treats mmbiz.qlogo.cn、mmbiz.qpic.cn and wx.qlogo.cn both as images already taken over by WeChat; after saving, confirms the draft via "a new appmsgid" or "existing appmsgid + this save's prompt/history change", and verifies the SVG, animation, images, and the beginning and end of the body text.history When page fields are missing, they are normalized to an empty array and no longer trigger script exceptions.
The publish command should always include --report. The success report includes cover.strategy, image status, and saved evidence; failures at any stage are also written to mode: "failed"、phase, the desensitized error, the read-only on-site status, and directly executable recovery actions. Use --verify-only --reuse-current to perform a read-only check of an already opened draft.
For the detailed process, see references/opencli-injection.md。
Component Extension Layer
--components mode enables 8 kinds of structured expressions. In default mode, component syntax degrades gracefully to ordinary markdown.
| Component | Syntax | Applicable Scenario |
|---|---|---|
| Pull Quote Block | > **核心观点** |
Core argument of the article |
| Lightweight Mark | ==关键词== |
Emphasis on keywords in the body text (thin bottom line) |
| Note Block | > [!NOTE] 内容 |
Supplementary explanations, technical side notes |
| Warning Block | > [!WARNING] 内容 |
Precautions, pitfall reminders |
| Step Number | 1. [step] 动作 |
Operation flow, action checklist |
| Process Card | :::flow Fence |
Stage process |
| Comparison Card | :::compare Fence |
Solution A vs B vs C |
| Timeline | :::timeline Fence |
Evolution history, project retrospective |
For complete syntax examples and design principles, see references/component-guide.md。
Design principles: Restraint over decoration · Colors taken from the theme · Horizontal cards prioritize flex:1 equal division with overflow as fallback · Matrix comparisons retain table · Card content should be short · Silent by default
Parameter Description
| Parameter | Description | Default Value |
|---|---|---|
--theme |
Theme name | zhijian |
--font-size |
Body font size (px) | Theme default |
--line-height |
Line height | Theme default |
--accent-color |
Accent color | Theme default |
--background-color |
Background color (solid hex) | Theme default |
--max-width |
Maximum content width (px) | 640 |
--output |
Output file path | <input>_wechat.html |
--components |
Enable component mode (intelligent rewriting + animation + components) | false |
--component-density |
Agent rewriting layer component density:restrained / standard / rich, not passed to convert.mjs |
standard |
--strict-density |
Stop generation when paragraph density fails; required for formal publishing candidates | false |
--cover |
Generate opening animation (--components automatically included) |
false |
--cover-template |
Opening animation template | ink-wash |
--cover-title |
Opening animation main title | Taken from frontmatter.title |
--cover-subtitle |
Opening animation subtitle | Taken from frontmatter.summary |
--cover-tags |
Opening animation tags (comma-separated) | None |
Font Size Recommendations
zhijian The current visual baseline is editorial-weighted-2026-07: H2/H3 use the Canger Jinkai preferred stack, body text uses Source Han Serif VF 15px / 450 / 1.68, and captions and metadata use Source Han Sans 13px. Dapeng has confirmed that 15px is more comfortable to read on mobile; the 450 weight restores the steadiness of paper reading. Font size only controls the display scale and cannot replace paragraph repair at the content layer. Recommendations:
- Official account long-form articles/high information density articles: Keep the default 15px, and first pass the hard paragraph density gate
- Narrative articles, older readers, or those who want a more relaxed look: 17px can be used
- 16px relaxed mode: can be used explicitly when the reader age is higher or the body text has more terminology
- Minimal theme minimal: it is already on the small side by default, generally no adjustment needed
Placeholder mechanism
Image host not ready while writing? Write a placeholder in Markdown, and convert will render it as a centered dashed gray box:
【插入:文章开头的视频截图】
Only supports 【插入:xxx】on a line by itself (full-width square brackets).
Output rules
- Input:
path/to/article.md→ Output:path/to/article_wechat.html - Complete HTML, inline styles, can be copied directly into the WeChat official account editor
- After convert,
validate.mjssoft gate validation runs automatically (non-blocking, prints a report)
For compatibility hard rule details, see references/wechat-compatibility.md。
References
| File | Content |
|---|---|
references/theme-guide.md |
Complete configuration for 8 themes, Renderer Presets, extension guide, technical implementation |
references/component-guide.md |
Syntax examples, design principles, and intelligent rewriting rules for 8 types of structured expression |
references/svg-animation-design.md |
Design principles for 5 templates, technical constraints, 11-item pitfalls checklist |
references/wechat-compatibility.md |
WeChat official account compatibility hard rules (ERROR/WARN details) |
references/opencli-injection.md |
OpenCLI injection process, browser capability boundaries, prerequisites and failure recovery |
references/zhijian-theme-baseline.md |
Zhijian theme version comparison, style locks, and mobile visual baseline |
Version: 1.9.0 · Author: Dapeng