README file from
GithubMP Publisher - 微信公众号发布插件
一个强大的 Obsidian 插件，支持自定义 CSS 主题预览和一键发布到微信公众号。
👇 查看演示
https://github.com/user-attachments/assets/b62e82a0-9b3c-4406-8007-1bbb6b9b7bac
中文说明 | English
✨ 为什么选择 MP Publisher
- 🎉 已上架 Obsidian 社区插件市场 — 在 Obsidian 设置中直接搜索安装，无需任何额外步骤
- 💰 完全免费 — 所有功能开源免费，无任何付费墙
- 📱 多公众号支持 — 同时管理多个微信公众号，一键切换
- 🎨 自定义 CSS 主题 — 在
custom/文件夹放置.css文件即可加载，自由打造你的排版风格 - 🗂️ 自由的主题管理页面 — 独立视图管理主题：浏览、切换、新建、编辑、重命名、删除，一站搞定
MP Publisher 是一个 Obsidian 插件，用于撰写文章并发布到微信公众号。它提供实时预览（支持自定义 CSS 主题）、一键复制粘贴到微信编辑器、以及通过 API 直接发布到草稿箱。
☕️ 支持作者
如果插件帮助到您，欢迎请作者喝杯咖啡～
✨ 功能特点
🎨 纯 CSS 主题系统
- 8 个内置 CSS 主题：默认、优雅、暗色、极简、清新绿、暖橙、猩红、学术
- 本地自定义主题：在插件目录
custom/文件夹下放置.css文件即可加载为自定义主题 - 主题管理界面：通过命令面板打开独立的主题管理视图，支持浏览、切换、新建、编辑、重命名、删除主题
- 查看与复制 CSS：在主题卡片中一键查看完整 CSS 源码，支持一键复制
- ✨ 伪元素自动转换：
::before/::after伪元素和 CSS 计数器（counter-reset/counter-increment）在复制/发布时自动转为真实 DOM 元素，公众号编辑器完美兼容 - 📖 编写自定义主题前请阅读 CSS 主题编写指南，了解可用选择器和完整模板
https://github.com/user-attachments/assets/e807ce6e-eb76-4465-93f9-92a9f9668e36
👁️ 实时预览
- 所见即所得：实时预览公众号效果
- 主题实时同步：在主题管理界面切换主题后，预览视图自动同步更新
- 强制刷新：点击刷新按钮可强制重新加载主题和预览内容
- 内置字体选择：预置多种中文字体供选择
- 字号调整：灵活调整文章字号
https://github.com/user-attachments/assets/24288345-b5c8-4613-956b-78b622317d95
智能发布
- 直接发布：通过微信公众号 API 直接发布草稿
- 图片上传：自动上传文档中的图片到微信服务器
- 草稿同步：支持更新已发布的草稿
- 封面选择：从微信素材库选择或上传封面图
- 元数据管理：自动管理发布状态和图片信息
- 发布进度指示器：右上角显示实时发布进度，清晰展示处理状态
📋 便捷复制
- 一键复制：复制格式化后的内容到剪贴板
- 格式保持：完美保持样式，可直接粘贴到公众号编辑器
- 跨设备兼容：使用 juice 内联 CSS，确保在任何设备上粘贴样式都正确显示
🔢 数学公式支持
- LaTeX 公式渲染：支持在 Markdown 中使用 LaTeX 数学公式，发布时自动转换为 PNG 图片
- 行内公式：支持
$...$和\(...\)语法 - 块级公式：支持
$$...$$和\[...\]语法 - 在线渲染：使用 CodeCogs API 渲染公式，确保微信公众号兼容
- 设置开关：在插件设置中可开启/关闭数学公式转换功能
💡 Callout 提示框支持
- 30+ 种 Callout 类型：支持 note/tip/warning/danger/success/example/todo/quote 等
- 专属样式：每种 Callout 类型有对应的 emoji 图标、背景色、边框色和标题色
- 主题适配：所有内置主题均有专属 Callout 配色方案
📦 安装
通过社区插件市场安装（推荐）
- 打开 Obsidian 设置 → 第三方插件 → 社区插件市场
- 搜索 "MP Publisher"
- 点击安装并启用
🚀 快速开始
第一步：配置微信公众号 API
-
获取 API 凭证
- 登录 微信公众平台
- 进入"设置与开发" > "基本配置"
- 记录你的
AppID和AppSecret - 在
IP 白名单中输入你的本地 IP 地址（不知道的可以问问 AI） - 💡 家用宽带 IP 经常变动？可以设置为
0.0.0.0/0允许所有 IP，省去频繁更新的麻烦
-
在插件中配置
- 打开 Obsidian 设置
- 找到 "MP Publisher" 设置
- 在"微信公众号配置"部分填入：
- AppID
- AppSecret
- 可选：配置图片存储位置（默认：
[文档名]__assets）
第二步：开始使用
预览功能
-
打开预览窗口
- 点击左侧栏的发送图标 📤
- 或按 Ctrl+P 打开命令面板，输入"打开公众号发布插件"
-
选择样式
- 在预览窗口顶部选择主题模板
- 调整字体和字号
- 实时查看效果
-
复制到公众号
- 点击"复制到公众号"按钮
- 打开微信公众号编辑器
- 粘贴（Ctrl+V 或 Cmd+V）
发布功能
-
准备发布
- 确保已配置微信公众号 API
- 编辑好你的文章内容
-
发布文章
- 点击预览窗口的"发布"按钮
- 或使用命令"发布到微信公众号"
- 输入标题
- 选择或上传封面图
- 点击"发布"
-
查看结果
- 登录微信公众平台
- 进入"内容与互动" > "草稿箱"
- 找到刚发布的草稿
📋 常用功能速查
键盘快捷键
Ctrl+P(或Cmd+P) - 打开命令面板- 搜索 "mp" 可快速找到插件命令
预览窗口控件
- 🔄 刷新按钮 - 强制重新加载主题和预览内容
- 主题选择器 - 切换不同 CSS 主题
- 字体选择器 - 更换内置字体
- ± 按钮 - 调整字号
- 复制按钮 - 复制格式化内容
- 发布按钮 - 一键发布到微信
⚙️ 配置说明
微信公众号配置
- AppID：公众号的应用ID
- AppSecret：公众号的应用密钥
- 获取方式：登录微信公众平台 > 设置与开发 > 基本配置
图片存储配置
- 存储位置模式：
[文档名]__assets：在文档同级创建资产文件夹.obsidian/assets：统一存储在 Obsidian 配置目录- 自定义路径：指定任意路径
调试模式
- 开启后会在控制台输出详细日志
- 便于排查问题
🎨 支持的 Markdown 语法
- ✅ 标题（H1-H6）
- ✅ 段落和换行
- ✅ 粗体、斜体、删除线
- ✅ 有序列表和无序列表
- ✅ 任务列表
- ✅ 引用块
- ✅ Callout 提示框（30+ 种类型）
- ✅ 代码块（支持语法高亮）
- ✅ 行内代码
- ✅ 链接
- ✅ 图片
- ✅ 表格
- ✅ 分隔线
- ✅ 脚注
- ✅ 数学公式（LaTeX 格式，自动转换为 PNG）
📝 元数据管理
插件会将元数据存储在 Obsidian 的 data.json 配置文件中（位于 .obsidian/plugins/mp-publisher/ 目录），包括：
- 发布状态：记录文章是否已发布或更新草稿
- 微信素材 ID：保存已上传图片的微信素材 ID，避免重复上传
- 文章 URL：保存发布后的文章链接
- 封面图信息：记录使用的封面图 ID 和来源
这样可以在多次发布时保持数据同步，提升发布效率，同时避免在文件系统中创建额外的文件夹和文件。
💡 使用技巧
1. 图片管理
- 图片会自动存储在
[文档名]__assets文件夹 - 发布时会自动上传到微信服务器
- 已上传的图片会缓存，避免重复上传
2. 样式自定义
- 在插件目录
custom/文件夹下放置.css文件即可加载为自定义主题 - 使用命令面板「打开主题管理」进入主题管理界面
- CSS 主题使用
.mp-content-section作为根选择器 - 可在主题卡片中点击「查看 CSS」查看完整源码，一键复制后修改
- 使用"预览"功能查看效果后再保存
- 📖 编写自定义主题前请阅读 CSS 主题编写指南，了解可用选择器和禁止使用的 CSS 特性和完整模板
3. 数学公式
- 使用
$...$或\(...\)包裹行内公式 - 使用
$$...$$或\[...\]包裹块级公式 - 在插件设置中开启数学公式转换功能
- 发布时公式会自动转换为 PNG 图片
4. Callout 提示框
- 使用 Obsidian 标准 Callout 语法：
> [!type] Title - 支持 30+ 种类型，如 note、tip、warning、danger 等
- 在不同主题下会自动适配配色方案
5. 草稿更新
- 再次发布同一文档会自动更新草稿
- 元数据保存在
[文档名]__assets/metadata.json - 删除该文件可以创建新草稿
6. 批量发布
- 可以为多个文档分别配置不同的样式
- 使用命令面板快速切换文档并发布
🔧 常见问题与解决
Q: 发布时提示"请先配置微信公众号"？
A: 需要在插件设置中填入有效的 AppID 和 AppSecret。
Q: 发布时提示"无法获取 Access Token"？
A: 请检查以下几点：
- AppID 和 AppSecret 是否正确（注意区分大小写）
- 当前 IP 是否已添加到微信公众平台白名单
- 网络连接是否正常
- 公众号是否已被封禁或限制
Q: 发布时提示"AppID 为空"（错误码 41002）？
A: 这个错误表示没有正确填写 AppID。解决方法：
- 打开 Obsidian 设置 > 第三方插件 > MP Publisher
- 确认"微信公众号配置"中的 AppID 已填写
- 填写完成后关闭设置窗口，重新尝试发布
⚠️ 注意事项：
- 确保 AppID 没有多余的空格
- 修改设置后需要重新打开预览窗口或重启 Obsidian
- AppID 通常是 18 位左右的字符串，如
wx1234567890abcdef
Q: 发布时提示"IP 白名单错误"（错误码 40164）？
A: 这是由于微信公众平台的 IP 白名单安全机制导致的。解决方法：
- 登录 微信公众平台
- 进入「设置与开发」→「基本配置」→「IP 白名单」
- 点击「修改」并添加提示中的 IP 地址
- 使用管理员微信扫码确认保存
⚠️ 注意事项：
- 如果你的网络使用动态 IP，每次 IP 变化后都需要更新白名单
- 修改白名单后可能需要等待 5-10 分钟才能生效
- 你可以通过访问 whatismyip.com 查看当前公网 IP
Q: 图片上传失败？
A: 请检查以下几点：
- 图片格式是否为 JPG 或 PNG
- 图片大小是否超过 2MB
- 微信公众号 API 配置是否正确
- 图片路径是否正确（相对路径或绝对路径）
- 网络连接是否稳定
Q: 样式在公众号编辑器中显示不正确？
A:
- 使用"复制到公众号"功能而不是直接复制粘贴
- 自定义主题中不要使用 CSS 变量
var(--xxx)、@media查询等，这些在复制/发布时会丢失。::before/::after伪元素和 CSS 计数器现已支持自动转换。详见 CSS 主题编写指南 - 确保所有选择器以
.mp-content-section开头 - 尝试清除浏览器缓存后重新打开公众号编辑器
Q: 如何获取微信公众号的 AppID 和 AppSecret？
A: 登录微信公众平台 > 设置与开发 > 基本配置，可以查看和获取。
Q: 发布后在哪里查看？
A: 登录微信公众平台 > 内容与互动 > 草稿箱，可以看到发布的草稿。
Q: 插件无法加载？
A:
- 确保
main.js、manifest.json、styles.css都在插件目录 - 检查 Obsidian 版本是否 >= 0.15.0
- 查看开发者工具的控制台错误信息（按 F12 打开）
Q: 如何创建自定义主题？
A: 有两种方式：
- 通过主题管理界面：命令面板搜索「打开主题管理」，在本地自定义主题区域点击「+ 新建主题」，输入名称和 CSS 内容后保存
- 直接放置 CSS 文件：将
.css文件放入插件目录的custom/文件夹中，在主题管理界面点击「重新加载」即可
📖 推荐阅读 CSS 主题编写指南，包含完整的选择器说明、禁止使用的 CSS 特性清单和可直接使用的模板。如果你使用 AI 生成主题，请将该指南提供给 AI 参考。
CSS 主题使用 .mp-content-section 作为根选择器，例如：
.mp-content-section h1 {
color: #1a1a2e;
font-size: 1.8em;
border-bottom: 2px solid #1a1a2e;
}
Q: 如何使用数学公式？
A:
- 在 Obsidian 设置 > MP Publisher 中开启"启用数学公式转换"
- 在 Markdown 中使用 LaTeX 语法：
- 行内公式：
$E = mc^2$或\(\alpha + \beta\) - 块级公式：
$$\int_0^\infty e^{-x} dx = 1$$或\[...\]
- 行内公式：
- 发布时公式会自动转换为 PNG 图片
⚠️ 注意事项：
- 需要网络连接以访问 CodeCogs API 进行渲染
- 复杂公式可能需要更长的渲染时间
Q: Callout 提示框如何使用？
A: 使用 Obsidian 标准语法：
> [!note] 提示标题
> 这是提示内容
> [!warning] 警告
> 这是警告内容
> [!tip] 技巧
> 这是技巧内容
支持 30+ 种类型，在不同主题下会自动适配配色。
🎓 最佳实践
1. 内容编写
- 使用标准 Markdown 语法
- 合理使用标题层级
- 图片使用描述性文件名
- 保持段落简洁
2. 样式选择
- 根据内容类型选择合适的 CSS 主题
- 技术文章推荐「暗色」或「极简」主题
- 文学内容推荐「优雅」或「学术」主题
- 使用 Callout 提示框增强重要信息的视觉效果
3. 数学公式使用
- 在技术文章中合理使用数学公式
- 确保公式语法正确以避免渲染错误
- 复杂公式建议先在本地测试渲染效果
- 发布前在预览窗口仔细检查
4. 发布流程
- 先在预览窗口检查样式
- 确认无误后再发布
- 发布后在微信平台进行最后检查
4. 图片优化
- 发布前压缩图片以减小大小
- 使用适当的图片尺寸
- 避免使用过多图片
🤝 贡献
欢迎提交 Issue 和 Pull Request！
📄 许可证
本软件采用 双重许可 模式：
- 开源使用：AGPL-3.0 — 可自由使用和修改，但衍生作品必须以相同协议开源
- 商业使用：需要商业授权，请联系作者（[email protected]）
详见 LICENSE 文件。
🙏 致谢
本插件整合了以下优秀项目的功能：
- mp-preview: 样式模板预览系统，已重构样式，但依然感谢作者的工作。
- obsidian-enhanced-publisher: 微信发布功能有参考。
📖 English
MP Publisher is an Obsidian plugin for writing and publishing articles to WeChat Official Account (微信公众号). It provides real-time preview with customizable CSS themes, one-click copy/paste to the WeChat editor, and direct API publishing to the draft box.
Key features:
- 8 built-in CSS themes + local custom themes via
custom/folder - Theme management view — browse, switch, create, edit, rename, delete themes
- Real-time preview — see your article as it will appear in WeChat
- Smart publishing — upload images, select cover art, create/update drafts via WeChat API
- One-click copy — formatted HTML with inline CSS, paste directly into the WeChat editor
- LaTeX math — renders
$...$/$$...$$formulas as PNG images - 30+ Callout types — note, tip, warning, danger, etc. with theme-adapted styling
- Multi-account support — manage multiple WeChat Official Accounts
Installation
Via Community Plugin Market (recommended):
- Open Obsidian Settings → Community Plugins → Browse
- Search for "MP Publisher"
- Click Install and enable
Via BRAT:
- Install BRAT from Obsidian community plugins
- Open BRAT settings → Add beta plugin
- Paste:
https://github.com/joeytoday/obsidian-mp-publisher - Confirm and enable the plugin in Obsidian settings
Manual installation:
- Download
mp-publisher.zipfrom Releases - Unzip into
<vault>/.obsidian/plugins/ - Reload Obsidian and enable the plugin
Quick Start
Step 1: Configure WeChat API
- Log into WeChat MP Platform → Settings & Development → Basic Configuration
- Note your
AppIDandAppSecret - Add your IP to the whitelist (or set
0.0.0.0/0if your IP changes frequently) - In Obsidian → Settings → MP Publisher, enter AppID and AppSecret
Step 2: Preview & Publish
- Preview: Click the 📤 icon in the left sidebar, or run the command "Open MP Publisher"
- Copy: Click "Copy to WeChat" → paste into the WeChat editor (Ctrl+V / Cmd+V)
- Publish: Click "Publish" → enter title → select cover image → confirm
Published articles appear in WeChat MP Platform → Content & Interaction → Drafts.
📖 Read the CSS Theme Guide before writing custom themes.
⭐ Star History
如果这个插件对你有帮助，欢迎 Star ⭐️