Back to Details

wechat-article-formatter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

微信公众号文章格式化工具（Claude 执行指南）

WeChat Official Account Article Formatting Tool (Claude Execution Guide)

目标: 将 Markdown 文章转换为适配微信公众号的精美 HTML，实现一键发布。
核心价值: 效率提升 15 倍（30分钟 → 2分钟），格式一致专业。
全新升级: 使用 AI 科技主题，专为 AI 领域内容设计，支持丰富的视觉组件和自定义语法。
Objective: Convert Markdown articles into elegant HTML optimized for WeChat Official Accounts, enabling one-click publishing.
Core Value: 15x efficiency improvement (30 minutes → 2 minutes), consistent and professional formatting.
New Upgrade: AI Tech Theme designed specifically for AI-related content, supporting rich visual components and custom syntax.

主题说明

Theme Description

本工具使用 AI 科技主题（ai-tech-theme），专为 AI 领域内容设计：
  • 渐进式紫蓝绿配色（保留原紫色，扩展至青、绿等辅助色）
  • 丰富的视觉组件（信息卡片、徽章、表格、代码块等）
  • AI 领域专用组件（模型对比、Prompt 示例、API 调用、性能指标）
  • Atom One Dark 代码高亮
  • 响应式设计，移动端友好
This tool uses the AI Tech Theme (ai-tech-theme), designed specifically for AI-related content:
  • Progressive purple-blue-green color scheme (retains original purple, expands to cyan, green and other auxiliary colors)
  • Rich visual components (info cards, badges, tables, code blocks, etc.)
  • AI domain-specific components (model comparison, Prompt examples, API calls, performance metrics)
  • Atom One Dark code highlighting
  • Responsive design, mobile-friendly

新增组件使用

New Component Usage

信息卡片

Info Cards

使用 
:::
语法创建不同类型的信息框：
markdown
::: info
这是一条信息提示
:::

::: success
操作成功！模型训练完成。
:::

::: warning
注意：此操作会消耗大量 tokens
:::

::: danger
错误：API key 无效
:::

::: tech
技术提示：使用 --temperature 参数控制输出随机性
:::
Use 
:::
syntax to create different types of info boxes:
markdown
::: info
This is an information prompt
:::

::: success
Operation successful! Model training completed.
:::

::: warning
Note: This operation will consume a large number of tokens
:::

::: danger
Error: Invalid API key
:::

::: tech
Technical Tip: Use the --temperature parameter to control output randomness
:::

徽章标签

Badge Tags

使用 
[!TEXT]
语法添加徽章：
markdown
GPT-4 [!NEW] 支持多模态输入 [!AI]

Claude Opus [!推荐] 具有最强推理能力
支持的徽章类型：
  • [!NEW]
    - 渐变紫蓝徽章（新功能）
  • [!AI]
    - 青色徽章（AI 相关）
  • [!推荐]
    - 紫色徽章（推荐内容）
  • [!成功]
    - 绿色徽章（成功状态）
  • [!警告]
    - 黄色徽章（警告提示）
Use 
[!TEXT]
syntax to add badges:
markdown
GPT-4 [!NEW] supports multimodal input [!AI]

Claude Opus [!推荐] has the strongest reasoning ability
Supported badge types:
  • [!NEW]
    - Gradient purple-blue badge (new feature)
  • [!AI]
    - Cyan badge (AI-related)
  • [!推荐]
    - Purple badge (recommended content)
  • [!成功]
    - Green badge (success status)
  • [!警告]
    - Yellow badge (warning prompt)

⚡ 执行流程（严格遵守）

⚡ Execution Process (Strictly Follow)

步骤1：获取输入文件

Step 1: Obtain Input File

场景判断：
场景如何处理
用户提供文件路径直接使用该路径
用户粘贴 Markdown 内容先使用 Write 工具保存为 .md 文件
刚使用过 wechat-tech-writer自动查找最新生成的 .md 文件（见集成指导）
用户只说"美化文章"询问用户：文件路径或粘贴内容
自动检测最新文章（与 wechat-tech-writer 集成）：
bash
undefined
Scenario Judgment:
ScenarioHow to Handle
User provides file pathUse the path directly
User pastes Markdown contentFirst use the Write tool to save as a .md file
Just used wechat-tech-writerAutomatically find the latest generated .md file (see Integration Guide)
User only says "Beautify article"Ask the user: file path or paste content
Automatic Detection of Latest Article (Integration with wechat-tech-writer):
bash
undefined

查找当前目录最新的 .md 文件

Find the latest .md file in current directory

latest_md=$(ls -t *.md 2>/dev/null | head -1) if [ -n "$latest_md" ]; then echo "检测到最新文章：$latest_md" fi

---
latest_md=$(ls -t *.md 2>/dev/null | head -1) if [ -n "$latest_md" ]; then echo "Detected latest article: $latest_md" fi

---

步骤2：执行转换

Step 2: Execute Conversion

标准转换命令：
bash
cd /root/.claude/skills/wechat-article-formatter

python3 scripts/markdown_to_html.py \
  --input "{文件路径}" \
  --output "{输出路径}" \
  --preview
参数说明：
  • --input
    ：Markdown 文件路径（必需）
  • --output
    ：HTML 输出路径（可选，默认同名 .html）
  • --theme
    ：主题选择（现在只有 ai-tech，可省略）
  • --preview
    ：转换后自动在浏览器打开预览（推荐）
示例：
bash
undefined
Standard Conversion Command:
bash
cd /root/.claude/skills/wechat-article-formatter

python3 scripts/markdown_to_html.py \
  --input "{file path}" \
  --output "{output path}" \
  --preview
Parameter Explanation:
  • --input
    : Markdown file path (required)
  • --output
    : HTML output path (optional, default is same name .html)
  • --theme
    : Theme selection (only ai-tech is available now, can be omitted)
  • --preview
    : Automatically open preview in browser after conversion (recommended)
Example:
bash
undefined

最常用：转换并预览

Most commonly used: convert and preview

python3 scripts/markdown_to_html.py
--input "Claude_Sonnet_4介绍.md"
--preview

**重要提醒**：
- 微信公众号有独立的标题输入框，HTML 中已自动移除 H1 标题
- 转换后的 HTML 包含注释：`<!-- ⚠️ 标题请在微信公众号编辑器中单独填写 -->`

---
python3 scripts/markdown_to_html.py
--input "Claude_Sonnet_4介绍.md"
--preview

**Important Reminder**:
- WeChat Official Account has an independent title input box, so H1 titles are automatically removed from the HTML
- The converted HTML contains a comment: `<!-- ⚠️ Please fill in the title separately in the WeChat Official Account editor -->`

---

步骤3：质量检查

Step 3: Quality Check

转换完成后，必须检查：
使用 Read 工具读取生成的 HTML 文件（前 50 行），检查：
检查项如何验证常见问题
标题样式查看 
<h2>
, 
<h3>
标签的 style 属性		样式丢失 → 重新转换
代码高亮查看 
<pre><code>
是否有语法高亮样式		无高亮 → 检查 Markdown 是否指定语言
信息卡片查看是否包含 
class="alert alert-info"
等		未转换 → 检查 ::: 语法格式
徽章查看是否包含 
class="badge badge-new"
等		未转换 → 检查 [!] 语法格式
图片路径查看 
<img src="">
的路径		本地路径 → 提醒用户需上传到微信
表格格式查看 
<table>
是否有内联样式		格式混乱 → 简化表格列数
快速检查命令：
bash
undefined
After conversion, must check:
Use the Read tool to read the generated HTML file (first 50 lines) and check:
Check ItemHow to VerifyCommon Issues
Title StyleCheck the style attribute of 
<h2>
, 
<h3>
tags		Style missing → re-convert
Code HighlightingCheck if 
<pre><code>
has syntax highlighting styles		No highlighting → check if Markdown specifies language
Info CardsCheck if contains 
class="alert alert-info"
etc.		Not converted → check ::: syntax format
BadgesCheck if contains 
class="badge badge-new"
etc.		Not converted → check [!] syntax format
Image PathCheck the path in 
<img src="">
Local path → remind user to upload to WeChat
Table FormatCheck if 
<table>
has inline styles		Format messy → simplify number of table columns
Quick Check Commands:
bash
undefined

查看 HTML 文件前 50 行

View first 50 lines of HTML file

head -50 output.html
head -50 output.html

检查是否包含信息卡片

Check if info cards are included

grep -o 'class="alert alert-[^"]*"' output.html
grep -o 'class="alert alert-[^"]*"' output.html

检查是否包含徽章

Check if badges are included

grep -o 'class="badge [^"]*"' output.html

---
grep -o 'class="badge [^"]*"' output.html

---

步骤4：预览和反馈

Step 4: Preview and Feedback

询问用户：
✅ 转换成功！已生成：{输出文件路径}

预览效果：
- 已在浏览器打开预览
- 或访问：file://{绝对路径}

请检查效果，满意吗？
- 满意 → 进入步骤5（发布指导）
- 需要调整 → 可以修改 Markdown 后重新转换
如果用户不满意：
问题解决方案
"信息框没显示"检查是否使用了正确的 ::: 语法
"徽章没显示"检查是否使用了正确的 [!] 语法
"代码块没高亮"检查 Markdown 代码块是否指定语言（```python）
"图片显示不正常"提醒：本地图片需上传到微信编辑器
"表格太宽"建议简化表格（≤4列）或接受横向滚动
Ask User:
✅ Conversion successful! Generated: {output file path}

Preview effect:
- Opened preview in browser
- Or visit: file://{absolute path}

Please check the effect, are you satisfied?
- Satisfied → Proceed to Step 5 (Publishing Guide)
- Need adjustments → Modify Markdown and re-convert
If User is Unsatisfied:
ProblemSolution
"Info boxes not displayed"Check if correct ::: syntax is used
"Badges not displayed"Check if correct [!] syntax is used
"Code blocks not highlighted"Check if Markdown code blocks specify language (```python)
"Images not displaying properly"Reminder: Local images need to be uploaded to WeChat editor
"Table too wide"Suggest simplifying table (≤4 columns) or accepting horizontal scrolling

步骤5：发布指导

Step 5: Publishing Guide

输出给用户的完整指导：
📋 发布到微信公众号步骤：

1. 打开微信公众号编辑器
2. ✅ 在标题栏填写文章标题：{从 Markdown 提取的标题}
3. 打开生成的 HTML 文件：{文件路径}
4. 在浏览器中按 Ctrl+A（全选）→ Ctrl+C（复制）
5. 粘贴到编辑器正文区（Ctrl+V）
6. 处理图片：
   - 删除无法显示的本地图片引用
   - 重新上传图片到微信编辑器
7. 最后检查：标题层级、段落间距、代码块、信息卡片、徽章
8. 使用微信编辑器的"预览"功能在手机查看
9. 确认无误后发布

⚠️ 注意事项：
- 样式已内联，可直接粘贴
- 本地图片需重新上传
- 粘贴后微信编辑器可能微调部分样式（正常）
- 信息卡片和徽章的颜色背景会保留
Complete Guide for User:
📋 Steps to Publish to WeChat Official Account:

1. Open WeChat Official Account Editor
2. ✅ Fill in article title in the title bar: {Title extracted from Markdown}
3. Open the generated HTML file: {file path}
4. Press Ctrl+A (select all) → Ctrl+C (copy) in browser
5. Paste into editor content area (Ctrl+V)
6. Handle images:
   - Delete local image references that cannot be displayed
   - Re-upload images to WeChat editor
7. Final check: Title hierarchy, paragraph spacing, code blocks, info cards, badges
8. Use the "Preview" function in WeChat editor to view on mobile
9. Publish after confirmation

⚠️ Notes:
- Styles are inline, can be pasted directly
- Local images need to be re-uploaded
- WeChat editor may fine-tune some styles after pasting (normal)
- Background colors of info cards and badges will be retained

🔄 与 wechat-tech-writer 集成

🔄 Integration with wechat-tech-writer

场景：刚用 wechat-tech-writer 生成文章

Scenario: Just used wechat-tech-writer to generate article

识别标志：
  • 用户刚说过"写一篇关于XXX的文章"
  • 当前目录有新生成的 .md 文件
自动化流程：
bash
undefined
Identification Signs:
  • User just said "Write an article about XXX"
  • There is a newly generated .md file in current directory
Automation Process:
bash
undefined

1. 查找最新文章

1. Find latest article

latest_article=$(ls -t *.md 2>/dev/null | head -1)
latest_article=$(ls -t *.md 2>/dev/null | head -1)

2. 确认是否是目标文章

2. Confirm if it's the target article

echo "检测到最新文章：$latest_article" echo "是否要转换这篇文章？(y/n)"
echo "Detected latest article: $latest_article" echo "Do you want to convert this article? (y/n)"

3. 自动转换（AI 科技主题）

3. Automatic conversion (AI Tech Theme)

python3 scripts/markdown_to_html.py
--input "$latest_article"
--preview

**无缝衔接话术**：
检测到你刚用 wechat-tech-writer 生成了文章：{文件名} 现在为你美化格式，使用 AI 科技主题...

---
python3 scripts/markdown_to_html.py
--input "$latest_article"
--preview

**Seamless Transition Script**:
Detected you just generated an article with wechat-tech-writer: {file name} Now beautifying the format with AI Tech Theme...

---

❌ 错误处理表

❌ Error Handling Table

错误信息原因Claude 应该做什么
FileNotFoundError: Input file not found
文件路径错误询问用户正确的文件路径
Unknown theme: xxx
主题名错误提示现在只有 ai-tech 主题
Theme CSS file not found
主题文件缺失检查文件是否存在，重新安装
转换成功但代码无高亮Markdown 未指定语言提醒用户修改代码块（```python）
信息框未转换::: 语法格式错误检查是否有正确的开始和结束标记
徽章未转换[!] 语法格式错误检查是否使用了支持的徽章类型
图片无法显示本地路径或外链失效提醒用户在微信编辑器重新上传
表格格式混乱表格过宽建议简化表格或转为图片
Error MessageCauseWhat Claude Should Do
FileNotFoundError: Input file not found
Incorrect file pathAsk user for correct file path
Unknown theme: xxx
Incorrect theme namePrompt that only ai-tech theme is available now
Theme CSS file not found
Theme file missingCheck if file exists, reinstall
Conversion successful but code not highlightedMarkdown did not specify languageRemind user to modify code block (```python)
Info boxes not convertedIncorrect ::: syntax formatCheck if correct start and end tags are present with correct type (info/success/warning/danger/tech)
Badges not convertedIncorrect [!] syntax formatCheck if supported badge type is used
Images cannot be displayedLocal path or external link invalidRemind user to re-upload in WeChat editor
Table format messyTable too wideSuggest simplifying table or converting to image

📚 快速参考

📚 Quick Reference

最常用命令

Most Commonly Used Commands

标准转换（最常用）：
bash
python3 scripts/markdown_to_html.py --input article.md --preview
指定输出路径：
bash
python3 scripts/markdown_to_html.py --input article.md --output output.html --preview
Standard Conversion (Most Commonly Used):
bash
python3 scripts/markdown_to_html.py --input article.md --preview
Specify Output Path:
bash
python3 scripts/markdown_to_html.py --input article.md --output output.html --preview

常见问题快速解答

Quick Answers to Common Questions

Q: 粘贴到微信后样式丢失？ A: 使用"粘贴"而非"粘贴并匹配样式"，或清空编辑器后重新粘贴。
Q: 代码块没有高亮？ A: 确保 Markdown 中指定了语言：```python（不是 ```）
Q: 信息卡片没有显示？ A: 检查 ::: 语法格式，确保有开始和结束标记，且类型正确（info/success/warning/danger/tech）
Q: 徽章没有显示？ A: 检查 [!] 语法格式，确保使用了支持的徽章类型（NEW/AI/推荐/成功/警告）
Q: 如何自定义颜色？ A: 修改 
templates/ai-tech-theme.css
中的 CSS 变量（:root 部分）
Q: Styles lost after pasting to WeChat? A: Use "Paste" instead of "Paste and Match Style", or clear editor and re-paste.
Q: Code blocks not highlighted? A: Ensure language is specified in Markdown: ```python (not ```)
Q: Info cards not displayed? A: Check ::: syntax format, ensure start and end tags are present with correct type (info/success/warning/danger/tech)
Q: Badges not displayed? A: Check [!] syntax format, ensure supported badge type is used (NEW/AI/推荐/成功/警告)
Q: How to customize colors? A: Modify CSS variables in 
templates/ai-tech-theme.css
(root section)

✅ 执行检查清单（每次执行完毕后确认）

✅ Execution Checklist (Confirm After Each Execution)

  • 已获取输入文件（路径或内容）
  • 已执行转换命令
  • 已检查生成的 HTML 文件（标题、代码、信息卡片、徽章、图片）
  • 已询问用户预览效果是否满意
  • 已提供完整的发布指导
  • 已处理可能出现的错误
记住：这个 skill 的核心是自动化 + 专业化，让用户 2 分钟完成原本 30 分钟的工作！
  • Obtained input file (path or content)
  • Executed conversion command
  • Checked generated HTML file (title, code, info cards, badges, images)
  • Asked user if preview effect is satisfactory
  • Provided complete publishing guide
  • Handled possible errors
Remember: The core of this skill is automation + professionalism, allowing users to complete what originally took 30 minutes in just 2 minutes!