md-wechat（MD 微信）

微信 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 <input> [options]

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

Usage Examples

基础用法

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

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

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

npm scripts

# 安装依赖
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);

Dependencies

核心依赖

自动安装机制

脚本会自动检测缺失的依赖并安装：

1. 检查 node_modules 目录
2. 缺失时自动执行 npm install
3. 安装完成后继续执行

可选依赖

对于 PlantUML 支持，需要安装 Java 运行时环境。

功能支持矩阵

Implementation Notes

架构设计

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

关键技术点

1. marked 扩展系统：使用 marked 的 extension API 实现自定义语法
2. KaTeX 服务端渲染：在 Node.js 中直接渲染数学公式为 HTML
3. Puppeteer 无头浏览器：渲染 Mermaid 等 JavaScript 依赖的图表
4. CSS 内联化：使用 juice 库将 CSS 样式内联到 HTML 元素

微信公众号适配

关键适配点：

1. 样式内联：所有 CSS 必须内联到 style 属性
2. 选择器限制：不支持 class 选择器，使用标签和内联样式
3. 外部链接：微信会屏蔽外链，建议添加引用标记
4. 图片处理：需上传到微信服务器或使用支持的图床
5. 代码块：使用 pre + code 标签，添加 Mac 装饰
6. KaTeX 样式：通过 CDN 引入，复制时需保留

Troubleshooting

常见问题

Q: Puppeteer 安装失败？ A: Puppeteer 需要下载 Chromium，可能需要配置镜像：

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

Q: 数学公式显示异常？ A: 确保 KaTeX CSS 正确加载，检查网络连接。

Q: Mermaid 图表渲染失败？ A: 检查 Puppeteer 是否正确安装，可能需要额外的系统依赖。

Q: 复制到公众号后样式丢失？ A:

1. 使用浏览器打开 HTML 文件
2. 全选复制（Ctrl+A）
3. 粘贴到公众号编辑器

Q: 图片不显示？ A: 微信公众号不支持外链图片，需要：

1. 上传图片到微信后台
2. 使用微信支持的图床（如腾讯云）

File Structure

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          # 简洁主题

Version History

• 2.0.0 (2024-03) - 使用 Node.js 重写，完整支持数学公式和图表渲染
• 1.0.0 (2024-03) - Python 版本，支持基础 Markdown 和扩展语法

Based on

• doocs/md - 原始项目灵感来源
• marked - Markdown 解析器
• KaTeX - 数学公式渲染
• Mermaid - 图表渲染