md2wx-cli

轻量、确定性、高保真的 Markdown 转微信公众号排版 CLI。

从写作到发布全链路命令行闭环：内联 CSS 排版、5 套精选主题、多主题画廊对比、推文抓取逆向、主题智能提取、官方 API 直传草稿箱、排版合规体检。不依赖任何网页编辑器，改一个错别字只需重跑一条命令。

安装

要求 Python ≥ 3.11。

pip install md2wx-cli

或免安装直接运行：

uvx md2wx-cli article.md -c

命令入口名为 md2wx。PyPI 包名 md2wx-cli 与 import 名 md2wx 分离（md2wx 在 PyPI 上已被其他项目占用）。

快速开始

# 转换并写入系统剪贴板，公众号编辑器 Ctrl+V 直接粘贴
md2wx article.md -c

# 输出 HTML 文件
md2wx article.md -o output.html

# 切换主题
md2wx article.md -t github-tech -c

# 生成完整 <html> 独立页面，双击即可预览
md2wx article.md -o preview.html --full-page

# 支持标准输入管道
cat article.md | md2wx -c

转换器处理的不只是 Markdown 渲染：中英文之间自动加空格、代码块语法高亮（Pygments）、外链自动转为文末脚注（微信正文不允许外链可点击）、全内联 CSS 与暗黑模式适配——这些全是微信编辑器的兼容性硬需求。

主题系统

内置 5 套主题，-t 一键切换：

主题	风格	适合内容
default	现代极简杂志编辑风	通用，默认选项
github-tech	GitHub 开发者文档风（OneDark 代码高亮）	教程、源码解析
bauhaus	包豪斯几何设计风	设计类、观点文
bold-green	清新高对比科技绿	环保、健康主题
bold-navy	深邃藏青商务编辑风	深度长文、行业分析

不确定选哪套？生成全主题交互画廊，浏览器里秒级切换对比，选中即一键复制：

md2wx gallery article.md -o gallery.html

主题是 YAML 文件（字体栈、配色、标题层级、代码块样式全部可调），也支持从外部逆向提取：

# 从一篇排版不错的微信推文学一套主题
md2wx learn-theme --url "https://mp.weixin.qq.com/s/xxxxxx" -n brand-editorial

# 或从本地设计稿目录提取
md2wx learn-theme --dir ./design_folder -n brand-editorial

# 直接套用
md2wx article.md -t brand-editorial -c

发布到公众号草稿箱

前置条件：公众号 AppID / AppSecret（微信公众平台「设置与开发 → 基本配置」获取），且将本机出口 IP 加入后台 IP 白名单（否则报 errcode=40164）。

首次配置凭据，永久保存至 ~/.md2wx/config.yaml：

md2wx config set wechat.appid "wx1234567890abcdef"
md2wx config set wechat.secret "你的AppSecret"

一键直传（自动上传本地配图到微信永久图床并替换链接、上传封面、创建草稿）：

md2wx article.md -p --title "文章标题" --author "作者" --cover images/cover.png

命令返回 media_id，登录 mp.weixin.qq.com 在草稿箱中确认后手动群发。直传只写草稿箱，不会自动群发。

凭据读取优先级：命令行参数（--appid / --secret）> 环境变量 > ~/.md2wx/config.yaml，方便在 CI 中注入。

注意：--cover 路径相对于输入 Markdown 文件所在目录解析，建议传绝对路径或相对 md 文件的路径。

发布前体检

md2wx check article.md

内置 16+ 条微信平台硬规则检测：失效的本地图片引用、未转脚注的裸外链、编辑器不支持的非法 CSS（position: fixed、display: grid、animation 等）、代码块格式保护。体检通过再直传，基本不会翻车。

抓取推文逆向

md2wx fetch "https://mp.weixin.qq.com/s/xxxxxx" -o draft.md

配图自动下载至 draft-assets/，居中高亮、白底卡片、实心横幅被识别还原为对应的容器语法。学习他人排版或做二次加工，从这一步开始。

容器排版语法

标准 Markdown 之外，原生支持几种扩展容器（渲染为微信兼容的内联样式组件）：

::: banner 导语标题
正文内容，支持 **加粗** 与 `代码`
:::

::: card 白底描边卡片，适合承载补充说明或外链
https://github.com/example/repo
:::

> [!WARNING]
> GitHub 风格告示块同样支持，自动渲染为主题色提示卡。

配置文件

~/.md2wx/config.yaml：

wechat:
  appid: "wx1234567890abcdef"
  secret: "你的AppSecret"
  author: "你的笔名"

开发

git clone <repo-url> && cd md2wx-cli
pip install -e .
python -m pytest tests/

License

MIT