微信 Markdown 排版 (md-wechat)

Overview

将 Markdown 文档转换为适配微信公众号的 HTML 格式。支持三种预设主题（经典、优雅、简洁），可自定义字体、颜色、代码高亮等样式，生成的 HTML 可直接复制粘贴到微信公众号编辑器使用。

版本 2.0.0 - 使用 Node.js 重写，完整支持所有功能！

核心功能

基础语法

• 标题：h1-h6，带样式装饰
• 段落：自动排版，支持缩进和两端对齐
• 列表：有序/无序列表，支持嵌套
• 引用：单层和多级嵌套引用
• 表格：GFM 表格语法
• 分隔线：水平分割线

扩展语法

• 删除线：~~删除线~~
• 高亮：==高亮==
• 下划线：++下划线++
• Ruby 注音：[文字]{注音} 或 [文字]^(注音)

高级功能

• 代码高亮：使用 highlight.js，支持 100+ 语言
• Mac 风格代码块：带红黄绿装饰按钮
• 数学公式：KaTeX 渲染，支持行内和块级公式
• Mermaid 图表：流程图、时序图、饼图等
• PlantUML 图表：UML 类图、时序图等
• Infographic 信息图：数据可视化图表

Workflow

1. 环境准备

前提条件：Node.js >= 18.0.0

推荐安装方式（更安全）：

# 手动安装依赖，可审查 package.json
npm install

# 然后运行转换
node scripts/convert.js article.md --no-auto-install

自动安装方式：

# 脚本会自动检测并安装缺失依赖
node scripts/convert.js article.md

安全提示：建议在隔离环境（Docker/沙盒）中首次运行，或使用 --no-auto-install 参数手动控制依赖安装。

2. 转换流程

输入：

• Markdown 文件路径（必需）
• 配置选项（可选）

处理流程：

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ 读取 MD 文件 │ -> │ 解析 Markdown │ -> │ 渲染特殊元素 │ -> │ 生成 HTML   │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
                         │                   │
                         v                   v
                ┌─────────────┐    ┌─────────────────────┐
                │ marked 解析  │    │ KaTeX 渲染公式      │
                │ 扩展语法处理 │    │ Puppeteer 渲染图表  │
                └─────────────┘    └─────────────────────┘

输出：

• 文件名：{原文件名}-wechat.html
• 特点：样式内联，可直接复制到微信公众号

3. 输出格式

生成的 HTML 特点：

• 所有样式内联（微信公众号要求）
• 支持 GFM（GitHub Flavored Markdown）
• 代码块带 Mac 风格装饰
• 图片带图注
• 外链自动添加引用标记
• 数学公式已渲染为 HTML
• 图表已渲染为 SVG

Configuration

配置文件 md-config.json

{
  "version": "1.0.0",
  "theme": {
    "name": "default"
  },
  "style": {
    "fontFamily": "-apple-system-font, BlinkMacSystemFont, Helvetica Neue, PingFang SC, sans-serif",
    "fontSize": "16px",
    "primaryColor": "#0F4C81",
    "textColor": "#3f3f3f",
    "bgColor": "#ffffff",
    "lineHeight": 1.75
  },
  "codeBlock": {
    "themeUrl": "https://cdn.jsdelivr.net/npm/highlight.js@11.9.0/styles/atom-one-dark.min.css",
    "themeName": "atom-one-dark",
    "isMacStyle": true,
    "showLineNumber": false
  },
  "image": {
    "legend": "alt-title",
    "borderRadius": "4px"
  },
  "link": {
    "citeStatus": false,
    "color": "#0F4C81"
  },
  "content": {
    "countStatus": true,
    "useIndent": false,
    "useJustify": false,
    "padding": "20px"
  },
  "headingStyles": {
    "h1": "default",
    "h2": "default",
    "h3": "default",
    "h4": "default",
    "h5": "default",
    "h6": "default"
  },
  "customCSS": ""
}

配置提取功能

从已排版好的 HTML 文件中提取样式配置，实现样式复用：

# 从渲染后的 HTML 提取配置
node scripts/extract-config.js example-result.html -o my-style.json

# 同时提供 Markdown 源文件，增强分析
node scripts/extract-config.js example-result.html -m example.md -o my-style.json

# 指定配置名称
node scripts/extract-config.js output.html --name "my-brand" -o my-brand-config.json

可提取的样式参数：

使用提取的配置

# 使用提取的配置文件进行转换
node scripts/convert.js article.md -c my-style.json -o article-output.html

# 命令行参数覆盖配置文件
node scripts/convert.js article.md -c my-style.json --color "#FF6600"

命令行参数

md-wechat  [options]

选项：
  -o, --output      输出 HTML 文件路径
  -c, --config      配置文件路径 (默认: md-config.json)
  --theme           主题名称 (default/grace/simple)
  --color          主题颜色 (覆盖配置文件)
  --font            字体系列 (覆盖配置文件)
  --font-size       字体大小 (覆盖配置文件)
  --bg-color       背景颜色 (覆盖配置文件)
  --text-color     文本颜色 (覆盖配置文件)
  --no-auto-install       禁用自动安装依赖

# 转换单个文件
node scripts/convert.js article.md

# 指定输出路径
node scripts/convert.js article.md -o output.html

# 使用自定义主题色
node scripts/convert.js article.md --color "#009874"

# 安装依赖
npm install

# 测试转换
npm run test

import { MDToWechatConverter } from './scripts/convert.js';

const converter = new MDToWechatConverter({
  primaryColor: '#0F4C81',
  macStyleCode: true
});

const html = await converter.convert(markdownText);
console.log(html);

convert.js
├── 扩展语法处理器
│   ├── strikethrough  删除线
│   ├── highlight      高亮
│   ├── underline      下划线
│   ├── rubyBrace      Ruby 注音 {}
│   └── rubyCaret      Ruby 注音 ^()
│
├── 数学公式渲染
│   ├── mathExtension  块级公式
│   └── inlineMath     行内公式
│
├── 图表渲染
│   └── mermaidExtension  Mermaid → SVG
│
├── 代码块处理
│   └── codeBlockExtension  代码高亮 + Mac 装饰
│
└── 核心转换器
    └── MDToWechatConverter
        ├── setupMarked()     配置解析器
        ├── convert()         主转换流程
        ├── renderMermaid()   渲染 Mermaid
        └── wrapHTML()        包装输出

npm config set puppeteer_download_host=https://cdn.npmmirror.com/mirrors
npm install puppeteer

md-wechat/
├── skill.md                    # 本文档
├── package.json                # Node.js 依赖配置
├── md-config.json              # 默认配置文件
├── scripts/
│   ├── convert.js              # 核心转换脚本 (Node.js)
│   ├── extract-config.js       # 配置提取脚本
│   └── convert.py              # Python 备用脚本
├── references/
│   ├── config-reference.md     # 配置参考
│   └── theme-reference.md      # 主题参考
└── assets/
    └── themes/
        ├── base.css            # 基础样式
        ├── default.css         # 经典主题
        ├── grace.css           # 优雅主题
        └── simple.css          # 简洁主题