# MD-TO-HTML

**Repository Path**: ironbamboo/md-to-html

## Basic Information

- **Project Name**: MD-TO-HTML
- **Description**: 将 Markdown 文档转换为微信公众号编辑器可直接粘贴使用的内联样式 HTML，支持多种主题、微信公众号 API 集成、草稿箱管理、发布能力等功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MD_TO_HTML - Markdown 转微信公众号格式工具

**版本**: v1.20.0
**更新日期**: 2026-03-28
**开发者**: 甘肃传德源科技工程有限公司
![输入图片说明](screenshots/640.png)

将 Markdown 文档转换为微信公众号编辑器可直接粘贴使用的内联样式 HTML，支持多种主题、微信公众号 API 集成、草稿箱管理、发布能力等功能。

> 衷心感谢 DeepSeek、豆包、千问、智谱、MiniMax、Kimi 等大模型的技术支持，也由衷致谢 OpenClaw、CoPaw、Trae、QoderWork 等开源项目的无私贡献。正是这些工具与开源生态，让我这样零基础的编程小白也能顺利完成程序开发，向所有开发者与项目团队致以诚挚谢意。因此我们也开源了这个项目，希望能帮助到更多的人。

---

## 软件截图

### 主界面预览

![主界面预览](screenshots/main_interface.png)

### 功能演示

| 编辑器与实时预览 | 主题切换 |
|:---:|:---:|
| ![编辑器预览](screenshots/editor_preview.png) | ![主题切换](screenshots/theme_switch.png) |

| 素材库管理 | 公众号配置 |
|:---:|:---:|
| ![素材库管理](screenshots/material_modal.png) | ![公众号配置](screenshots/settings.png) |

---

## 功能特性

- **Markdown 转 HTML**：将 Markdown 文档转换为微信公众号兼容的内联样式 HTML
- **多主题支持**：10 种精美主题（默认、科技、优雅、温暖、醒目、极简、暗黑、海洋、森林、日落）
- **微信公众号 API 集成**：支持获取 Token、保存草稿、直接发布、发布能力管理
- **素材库管理**：上传和管理封面图片
- **实时预览**：本地服务器预览，支持主题切换
- **行距调整**：实时调整文章行距
- **文件上传**：支持 .md、.txt、.docx、.doc 文件
- **发布能力**：获取已发布列表、删除发布文章、发布状态查询、获取图文详情、发布草稿

---

## 目录结构

```
md-to-html/
├── scripts/
│   ├── main.py           # 主程序入口
│   ├── formatter.py      # Markdown 格式化器
│   ├── api.py            # 微信公众号 API 封装
│   ├── config.py         # 配置管理（加密存储）
│   ├── local_server.py   # 本地预览服务器
│   ├── material_modal.py # 素材库弹窗模块
│   ├── errors.py         # 错误处理模块
│   └── styles/
│       └── preview.css   # 预览页面样式
├── static/
│   ├── css/
│   │   └── preview.css
│   └── js/
│       ├── api.js        # 前端 API 调用
│       └── ui.js         # 前端 UI 逻辑
├── templates/
│   └── preview.html      # 预览页面模板
├── themes/               # 主题配置文件
│   ├── default.json
│   ├── tech.json
│   ├── elegant.json
│   ├── warm.json
│   ├── bold.json
│   ├── minimal.json
│   ├── dark.json
│   ├── ocean.json
│   ├── forest.json
│   └── sunset.json
└── README.md
```

---

## 安装

### 1. 拉取项目

```bash
# 克隆 Gitee 仓库
git clone https://gitee.com/ironbamboo/md-to-html.git
cd md-to-html
```

### 2. 依赖要求

- Python 3.8+
- pip

### 3. 安装依赖

**方式一：使用 requirements.txt（推荐）**

```bash
pip install -r requirements.txt
```

**方式二：手动安装**

```bash
pip install markdown cryptography Flask requests python-docx
```

---

## 使用方法

### 命令行方式

```bash
# 基本转换
python scripts/main.py -i "文章路径.md" -t tech --open

# 参数说明
# -i, --input      Markdown 文件路径（必须）
# -t, --theme      主题名称（default/tech/elegant/warm/bold/minimal/dark/ocean/forest/sunset）
# -o, --output     输出目录（默认 ./output）
# --open           自动用系统浏览器打开预览
# --config-mp      配置微信公众号 AppID 和 AppSecret
# --save-draft     保存到微信公众号草稿箱
```

### 本地服务器方式

```bash
# 启动本地服务器（自动生成预览）
python scripts/local_server.py

# 访问预览页面
# http://127.0.0.1:5000/preview
```

### 配置微信公众号

```bash
# 命令行配置
python scripts/main.py --config-mp

# 或在预览页面点击「公众号配置」按钮
```

---

## 作为 Trae SKILL 使用

本工具可作为 Trae SKILL 使用，提供快捷的 Markdown 转微信公众号格式功能。

### 触发关键词

当用户说以下关键词时，会自动触发 SKILL：
- `/format 文件路径`
- `排版这篇文章`
- `微信排版`
- `格式化为公众号格式`
- `把这篇转成微信格式`
- `wechat format`
- `convert to wechat html`

### SKILL 配置

SKILL 配置文件：`SKILL.md`

```yaml
---
name: "wechat-md-to-html"
description: "Converts Markdown to WeChat-compatible inline-styled HTML. Invoke when user asks to format/convert Markdown for WeChat official account, or mentions '微信排版', '公众号格式', 'wechat format'."
---
```

### SKILL 工作流

1. **确认文章**：读取用户指定的 Markdown 文件
2. **选择主题**：根据文章类型推荐合适的主题
3. **调用格式化**：执行转换脚本
4. **复制到微信**：在系统浏览器中打开并复制

---

## 主题列表

| 主题 | 命令值 | 主色 | 适用场景 |
|------|--------|------|----------|
| 默认 | default | #333333 | 通用文章 |
| 科技 | tech | #0071e3 | 技术教程、AI 资讯 |
| 优雅 | elegant | #c9a962 | 深度长文、观点文 |
| 温暖 | warm | #e07a5f | 故事、生活类 |
| 醒目 | bold | #ff4757 | 热点评论 |
| 极简 | minimal | #888888 | 知识分享、教程 |
| 暗黑 | dark | #64b5f6 | 夜间阅读、技术文章 |
| 海洋 | ocean | #0088cc | 科技、清新风格 |
| 森林 | forest | #2e7d32 | 自然、环保主题 |
| 日落 | sunset | #ff6b35 | 活力、创意文章 |

---

## 支持的 Markdown 元素

| 元素 | Markdown 语法 | 微信 HTML 处理 |
|------|-------------|---------------|
| 标题 | `# ~ ######` | `<h1>` ~ `<h6>` 内联样式 |
| 段落 | 空行分隔 | `<p>` 内联样式 |
| 粗体 | `**text**` | `<strong>` 内联样式 |
| 斜体 | `*text*` | `<em>` 内联样式 |
| 链接 | `[text](url)` | 转为脚注格式 |
| 图片 | `![alt](src)` | `<img>` 内联样式 |
| 引用 | `> text` | `<blockquote>` 内联样式 |
| 代码 | `` `code` `` | `<code>` 内联样式 |
| 代码块 | ` ``` ` | `<pre><code>` 内联样式 |
| 列表 | `- item` / `1. item` | `<section>` 模拟 |
| 表格 | Markdown 表格 | `<table>` 内联样式 |
| 分隔线 | `---` | `<hr>` 内联样式 |
| 删除线 | `~~text~~` | `<del>` 内联样式 |

---

## 微信兼容说明

脚本自动处理以下微信限制：

- **纯内联样式**：所有 CSS 直接写在每个标签的 `style=""` 属性上
- **列表模拟**：`<ul>/<ol>` 改为 `<section>` + flexbox 模拟（微信会重置列表样式）
- **外链转脚注**：`[text](url)` 自动变成正文 `text[1]` + 文末脚注列表
- **颜色格式**：统一使用十六进制格式（如 `#333333`）
- **内容宽度**：最大宽度 677px

---

## 微信公众号 API 功能

### 配置要求

1. 在微信公众平台获取 AppID 和 AppSecret
2. 路径：设置与开发 → 基本配置 → 开发者ID
3. 配置 IP 白名单（服务器 IP 或本地开发 IP）

### 支持的 API 功能

| 功能 | 说明 |
|------|------|
| 获取 Token | 自动获取和刷新 access_token（页面加载时自动获取） |
| 保存草稿 | 将文章保存到微信公众号草稿箱 |
| 直接发布 | 直接发布文章（仅服务号可用） |
| 素材管理 | 上传和管理图片素材 |
| API 配额查询 | 查询 API 调用额度（显示剩余/总额） |
| RID 诊断 | 查询 API 调用详情（接口、耗时、客户端IP、响应） |
| 发布能力 | 获取已发布列表、删除发布文章、发布状态查询、获取图文详情、发布草稿 |

---

## 发布能力说明

| 功能 | 接口 | 说明 |
|------|------|------|
| 获取已发布列表 | freepublish_batchget | 获取已成功发布的图文消息列表 |
| 删除发布文章 | freepublish_delete | 删除已发布的图文消息 |
| 发布状态查询 | freepublish_getarticle | 查询图文发布状态 |
| 获取图文详情 | freepublish_getarticle | 获取已发布图文的完整内容 |
| 发布草稿 | freepublish_submit | 将草稿箱中的图文发布 |

---

## 注意事项

1. **图片处理**：图片在预览中可见，但粘贴到微信后需要手动上传
2. **复制操作**：点击「复制到公众号」按钮后，到微信公众号编辑器按 Ctrl+V 粘贴
3. **直接发布**：仅服务号可用，订阅号请使用「保存到草稿箱」功能
4. **封面图片**：保存草稿或发布前需要先选择封面图片
5. **Token 记忆**：AppID 和 AppSecret 存储在浏览器 localStorage 中，仅本地浏览器可用

---

## 版本变更记录

### v1.20.0 (2026-03-28)
- **修复**: 预览窗口与编辑器内容不一致问题
- **修复**: 代码块换行符被移除的问题
- **优化**: 按钮文案修改为「上传要转换的文件」
- **优化**: 版本信息移至右侧工具栏

### v1.19.3 (2026-03-21)
- **优化**: 页面宽度改为 95%，居中显示
- **优化**: 编辑器与预览区平均分配宽度
- **修复**: 预览区标题固定，内容区域滚动
- **新增**: 页面加载时自动获取 Token
- **新增**: Token 成功后自动刷新 API 配额
- **修复**: 修复 refreshQuota() 正确解析 quota 对象格式
- **修复**: 修复 queryRid() 字段映射（cost_in_ms、request_url）
- **优化**: 统一按钮大小样式
- **新增**: local_server.py 启动时自动生成预览

### v1.19.2 (2026-03-21)
- **新增**: local_server.py 自动生成预览功能

### v1.19.1 (2026-03-21)
- **修复**: 页面占满浏览器宽度问题
- **修复**: html、body 元素添加 width/height 100%

### v1.18.0 (2026-03-20)
- **优化**: 按钮文案修改
- **优化**: 删除在浏览器打开按钮
- **修复**: 空行问题
- **优化**: 放大素材库弹窗
- **重构**: 模块分离

---

## License

MIT License

---

## 相关链接

- [Gitee 仓库](https://gitee.com/ironbamboo/md-to-html)
- [微信公众平台](https://mp.weixin.qq.com)
- [微信公众开发文档](https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html)