MP Publisher

unlisted

by joeytoday

Preview with custom CSS themes and publish articles to WeChat Official Accounts with one click.

★ 123 starsUpdated 11d agoAGPL-3.0
View on GitHub

MP Publisher - 微信公众号发布插件

一个功能强大的 Obsidian 插件，支持自定义 CSS 主题样式预览和一键发布到微信公众号。

https://github.com/user-attachments/assets/b62e82a0-9b3c-4406-8007-1bbb6b9b7bac

✨ 功能特点

🎨 纯 CSS 主题系统

  • 8 个内置 CSS 主题：默认、优雅、暗色、极简、清新绿、暖橙、猩红、学术
  • 本地自定义主题：在插件目录 custom/ 文件夹下放置 .css 文件即可加载为自定义主题
  • 主题管理界面：通过命令面板打开独立的主题管理视图，支持浏览、切换、新建、编辑、重命名、删除主题
  • 查看与复制 CSS：在主题卡片中一键查看完整 CSS 源码，支持一键复制
  • 📖 编写自定义主题前请阅读 CSS 主题编写指南，了解可用选择器和禁止使用的 CSS 特性和完整模板

https://github.com/user-attachments/assets/78e8df0e-ea0d-4902-bcb5-dd384e19fefe

👁️ 实时预览

  • 所见即所得：实时预览公众号效果
  • 主题实时同步：在主题管理界面切换主题后，预览视图自动同步更新
  • 强制刷新：点击刷新按钮可强制重新加载主题和预览内容
  • 内置字体选择：预置多种中文字体供选择
  • 字号调整：灵活调整文章字号

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 配色方案

📦 安装

通过 BRAT 插件安装（推荐）

  1. 在 Obsidian 社区插件中搜索并安装 BRAT 插件
  2. 打开 BRAT 设置，点击 Add beta plugin
  3. 粘贴仓库链接：https://github.com/joeytoday/obsidian-mp-publisher
  4. 可选择安装版本，点击确认即可自动安装
  5. 在 Obsidian 设置中启用插件

手动安装

  1. 前往 Releases 下载最新版本的 mp-publisher.zip 文件
  2. 将文件解压到你的 Obsidian 仓库 <vault>/.obsidian/plugins/ 目录下
  3. 重新加载 Obsidian
  4. 在设置中启用插件

🚀 快速开始

第一步：配置微信公众号 API

  1. 获取 API 凭证

    • 登录 微信公众平台
    • 进入"设置与开发" > "基本配置"
    • 记录你的 AppID 和 AppSecret
    • 在 IP 白名单中输入你的本地 IP 地址（不知道的可以问问 AI）
    • 💡 家用宽带 IP 经常变动？可以设置为 0.0.0.0/0 允许所有 IP，省去频繁更新的麻烦

  2. 在插件中配置

    • 打开 Obsidian 设置
    • 找到 "MP Publisher" 设置
    • 在"微信公众号配置"部分填入：
      • AppID
      • AppSecret
    • 可选：配置图片存储位置（默认：[文档名]__assets）

第二步：开始使用

预览功能

  1. 打开预览窗口

    • 点击左侧栏的发送图标 📤
    • 或按 Ctrl+P 打开命令面板，输入"打开公众号发布插件"

  2. 选择样式

    • 在预览窗口顶部选择主题模板
    • 调整字体和字号
    • 实时查看效果

  3. 复制到公众号

    • 点击"复制到公众号"按钮
    • 打开微信公众号编辑器
    • 粘贴（Ctrl+V 或 Cmd+V）

发布功能

  1. 准备发布

    • 确保已配置微信公众号 API
    • 编辑好你的文章内容

  2. 发布文章

    • 点击预览窗口的"发布"按钮
    • 或使用命令"发布到微信公众号"
    • 输入标题
    • 选择或上传封面图
    • 点击"发布"

  3. 查看结果

    • 登录微信公众平台
    • 进入"内容与互动" > "草稿箱"
    • 找到刚发布的草稿

📋 常用功能速查

键盘快捷键

  • 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: 请检查以下几点：

  1. AppID 和 AppSecret 是否正确（注意区分大小写）
  2. 当前 IP 是否已添加到微信公众平台白名单
  3. 网络连接是否正常
  4. 公众号是否已被封禁或限制

Q: 发布时提示"AppID 为空"（错误码 41002）？

A: 这个错误表示没有正确填写 AppID。解决方法：

  1. 打开 Obsidian 设置 > 第三方插件 > MP Publisher
  2. 确认"微信公众号配置"中的 AppID 已填写
  3. 填写完成后关闭设置窗口，重新尝试发布

⚠️ 注意事项：

  • 确保 AppID 没有多余的空格
  • 修改设置后需要重新打开预览窗口或重启 Obsidian
  • AppID 通常是 18 位左右的字符串，如 wx1234567890abcdef

Q: 发布时提示"IP 白名单错误"（错误码 40164）？

A: 这是由于微信公众平台的 IP 白名单安全机制导致的。解决方法：

  1. 登录 微信公众平台
  2. 进入「设置与开发」→「基本配置」→「IP 白名单」
  3. 点击「修改」并添加提示中的 IP 地址
  4. 使用管理员微信扫码确认保存

⚠️ 注意事项：

  • 如果你的网络使用动态 IP，每次 IP 变化后都需要更新白名单
  • 修改白名单后可能需要等待 5-10 分钟才能生效
  • 你可以通过访问 whatismyip.com 查看当前公网 IP

Q: 图片上传失败？

A: 请检查以下几点：

  1. 图片格式是否为 JPG 或 PNG
  2. 图片大小是否超过 2MB
  3. 微信公众号 API 配置是否正确
  4. 图片路径是否正确（相对路径或绝对路径）
  5. 网络连接是否稳定

Q: 样式在公众号编辑器中显示不正确？

A:

  1. 使用"复制到公众号"功能而不是直接复制粘贴
  2. 自定义主题中不要使用 CSS 变量 var(--xxx)、伪元素 ::before/::after、@media 查询等，这些在复制/发布时会丢失。详见 CSS 主题编写指南
  3. 确保所有选择器以 .mp-content-section 开头
  4. 尝试清除浏览器缓存后重新打开公众号编辑器

Q: 如何获取微信公众号的 AppID 和 AppSecret？

A: 登录微信公众平台 > 设置与开发 > 基本配置，可以查看和获取。

Q: 发布后在哪里查看？

A: 登录微信公众平台 > 内容与互动 > 草稿箱，可以看到发布的草稿。

Q: 插件无法加载？

A:

  1. 确保 main.js、manifest.json、styles.css 都在插件目录
  2. 检查 Obsidian 版本是否 >= 0.15.0
  3. 查看开发者工具的控制台错误信息（按 F12 打开）

Q: 如何创建自定义主题？

A: 有两种方式：

  1. 通过主题管理界面：命令面板搜索「打开主题管理」，在本地自定义主题区域点击「+ 新建主题」，输入名称和 CSS 内容后保存
  2. 直接放置 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:

  1. 在 Obsidian 设置 > MP Publisher 中开启"启用数学公式转换"
  2. 在 Markdown 中使用 LaTeX 语法：
    • 行内公式：$E = mc^2$ 或 \(\alpha + \beta\)
    • 块级公式：$$\int_0^\infty e^{-x} dx = 1$$ 或 \[...\]
  3. 发布时公式会自动转换为 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 — 可自由使用和修改，但衍生作品必须以相同协议开源
  • 商业使用：需要商业授权，请联系作者（joeykai2022@126.com）

详见 LICENSE 文件。

🙏 致谢

本插件整合了以下优秀项目的功能：

⭐ Star History

Star History Chart

如果这个插件对你有帮助，欢迎 Star ⭐️

For plugin developers

Search results and similarity scores are powered by semantic analysis of your plugin's README. If your plugin isn't appearing for searches you'd expect, try updating your README to clearly describe your plugin's purpose, features, and use cases.