# Markdown Publisher 使用说明

Markdown Publisher 是一款 Obsidian 插件，用于把 Markdown 笔记自动排版成微信公众号格式，并直接发布到公众号草稿箱：CSS 全部内联、本地图片自动上传、支持 KaTeX 公式与代码高亮。

> 环境要求：Obsidian 桌面版（macOS / Windows / Linux）v1.7.2 及以上；已认证的微信公众号（订阅号或服务号）。

---

## 一、安装插件

### 社区插件市场（推荐）

插件已上架 Obsidian 社区插件市场：

1. 打开 Obsidian → **设置 → 第三方插件 → 浏览**
2. 搜索 **Markdown Publisher**
3. 点击 **安装**，然后 **启用**

### 手动安装

1. 前往 [Releases](https://github.com/volcanicll/obsidian-md-publisher/releases)，下载最新版本的三个文件：
   - `main.js`
   - `manifest.json`
   - `styles.css`
2. 在你的 Obsidian 仓库中创建目录：`.obsidian/plugins/md-publisher/`
3. 把三个文件放入该目录。
4. 打开 Obsidian → 设置 → 第三方插件 → 关闭「安全模式」（如已开启）→ 在已安装插件列表中启用 **Markdown Publisher**。

## 二、配置微信公众号认证

打开 设置 → Markdown Publisher，在「微信公众号」区域选择一种认证方式。

### 方式 A：自动模式（推荐，需 IP 白名单）

1. 登录 [微信公众平台](https://mp.weixin.qq.com)，进入「设置与开发 → 基本配置」，获取 **AppID** 和 **AppSecret**。
2. 在同一页面的「IP 白名单」中，添加你本机的公网 IP（可在浏览器搜索"我的 IP"查询）。
3. 在插件设置中填入 AppID 和 AppSecret。
4. 点击 **测试连接**，显示成功即可。

⚠️ 注意：

- AppSecret 以明文保存在本机 Obsidian 配置文件中，请勿共享或提交你的 `.obsidian` 目录到公开仓库。
- 本机 IP 变化后（如换了网络），需要更新白名单。

### 方式 B：手动 token 模式（无需 IP 白名单）

1. 在插件设置中开启「使用手动 token」。
2. 登录公众平台，在「基本配置 → 开发者工具」等入口获取当前有效的 **access_token**（也可用公众号后台提供的调试工具生成）。
3. 将 token 粘贴进插件设置，点击 **测试连接** 验证。

⚠️ access_token 有效期约 **2 小时**，过期后需要重新获取并粘贴。

## 三、排版与发布

### 打开预览面板

- 点击左侧边栏的 📄 图标（打开排版预览），或
- 使用命令面板（`Ctrl/Cmd + P`）执行 **Markdown Publisher: 打开排版预览**。

预览面板实时渲染当前笔记，顶部可切换排版主题（代码高亮随主题自动匹配）。笔记中的本地图片会直接显示在预览中。

### 四种输出方式

| 操作 | 用途 |
|------|------|
| **复制** | 复制带内联样式的 HTML，粘贴到公众号编辑器手动微调后再发 |
| **发布** | 弹窗中填写标题、作者、摘要、原文链接等，直接存入公众号草稿箱 |
| **导出图片** | 把排版结果截成 PNG 长图存进 vault，用于发到不支持富文本的平台或存档 |
| **草稿** | 打开草稿管理面板，分页查看草稿箱、把草稿拉回 Obsidian 继续编辑、删除草稿；列表会标出每篇草稿关联的笔记 |

### 导出为图片

点预览面板工具栏的 **导出图片**（或命令面板执行 **Markdown Publisher: 导出为图片**），
当前排版会按预览面板的实际宽度与所选缩放截成一张 PNG 长图，保存进 vault，完成后提示保存路径。

相关设置（设置 → Markdown Publisher → 导出图片）：

- **导出图片缩放**：1x / 2x / 3x 像素密度，默认 2x；内容过长时会自动降级以避免超出画布上限，并给出提示
- **导出图片文件夹**：留空保存到当前笔记所在文件夹；填写则为 vault 内相对路径（不存在时自动创建）

说明：

- 导出宽度跟随预览面板的实际宽度（上限 1080px），预览有多宽导出就有多宽；预览宽度读取失败时按 375px 导出并提示
- 文件名取自笔记名；同目录已有同名文件时自动追加 `-1`、`-2`，不会覆盖
- 正文中的本地图片与外链图片会先内联为 data URL 再截图，避免出现空白图
- 内容高度即使按 1x 也超出画布上限时，会明确报错并建议拆分笔记，不会产出空白图
- 导出效果与预览一致（同一套渲染管线），但**不含**公众号文章页的标题 / 作者 / 封面版式——那是「发布」弹窗左侧的手机预览

### 发布设置

点预览面板的 **发布** 会打开发布弹窗：左边是手机预览，右边是发布信息表单，改一个字预览就跟着更新，不需要在「填表」和「看效果」之间来回切。

手机预览按公众号真机的 375px 逻辑宽度排版，并带上真机上会看到的外壳：状态栏、「返回 / 公众号名 / 更多」顶栏、蓝色作者名与日期，以及底部固定的赞 / 在看 / 留言条。正文宽度、字号、行高、列表缩进都直接取自渲染结果里内联的样式，和最终发到公众号的那份 HTML 一致；预览窗口固定为白底黑字，不随 Obsidian 的深色主题变化——公众号正文在真机上本来就是浅色版式。弹窗变窄时手机会等比收缩，不会横向溢出。

预览上方有两个标签：

- **文章页**：按公众号文章页结构展示标题、作者、封面、正文与「阅读原文」入口
- **分享卡片**：按微信聊天里的转发样式展示标题（两行截断）、缩略图与摘要
- **手机预览**：草稿保存后，这里会显示一个二维码，用微信扫一扫即可在手机上打开这篇草稿的真实文章页——版式、字体、封面都是微信自己的渲染结果，比桌面模拟更可靠。草稿还没保存时该标签为禁用状态；也可以点「在浏览器中打开」直接查看

表单里可以设置：

- **标题**：必填，最多 64 字（微信限制）
- **作者**：可选，最多 8 字
- **摘要**：可选，最多 120 字，默认从正文自动提取。提取时会跳过标题、图片、表格、分隔线与代码块，取第一段可读文字；引用与列表只去掉标记保留文字，加粗、链接、双链、高亮等行内语法都会还原为纯文本
- **封面**：点「更换封面」选择来源，当前来源在缩略图左上角的角标里标明
  - **正文首图**（默认）：取正文第一张图片
  - **从 vault 选择**：在文件选择器里挑一张笔记仓库里的图片
  - **上传本地文件**：从电脑上选一张图片，只用于本次发布，不会写进 vault
  - **按标题生成**：用文章标题画一张卡片封面，改标题后预览会自动重画
  - 正文完全没有图片时，默认行为自动退化为「按标题生成」
- **正文顶部显示封面**：对应微信的 `show_cover_pic`，决定文章页顶部是否重复展示封面。默认值来自 设置 → Markdown Publisher → 正文顶部显示封面
- **开启评论** / **仅粉丝可评论**：评论权限
- **原文链接**：点击「阅读原文」跳转的地址
- **发布方式**：默认「覆盖更新已有草稿」，也可切换为「新建草稿」

超出微信字数限制时，发布前会收到明确提示。

还没配置公众号凭证时，弹窗仍然照常打开：可以正常填写标题、封面、预览效果并运行发布前检查，顶部只显示一条提示横幅。点「保存到草稿」时才校验，并说明该去补哪一项配置。

点「保存到草稿」后，插件会先校验一次公众号凭证，再开始上传图片。校验会真的向微信换取一次 access_token，因此填错 AppID / AppSecret、两者不匹配、本机 IP 不在白名单、手动 token 过期都会立刻拦下，并直接说明该去设置里改哪一项，不必等几十张图片传完才看到报错。手动 token 模式不会发起这个请求，只检查本地记录的有效期。

发布后文章进入草稿箱，请在手机或公众平台网页端**终审排版**后再群发。

### 覆盖更新已有草稿

同一篇笔记多次发布时，插件默认**覆盖**上一次生成的草稿，而不是在草稿箱里不断新增重复文章：

- 首次发布会在本地记录这条笔记与草稿的对应关系（保存在插件设置里）；之后打开同一篇笔记发布，弹窗默认选中「覆盖更新已有草稿」，并显示将被覆盖的草稿标题
- 需要另起一篇时，把「发布方式」切到「新建草稿」；想覆盖的不是自动记住的那篇（例如笔记换过文件名、或用旧版本发布过），点「发布方式」右侧的草稿箱按钮从列表中另选
- 封面来源（指定封面图 / 正文首图 / 按标题生成的卡片）没有变化时，会直接复用上次上传的永久素材，不重复上传；改了封面才会重新上传
- 笔记重命名或移动后关联会跟着迁移；在草稿管理里删除某篇草稿后，对应关联同时清除
- 覆盖失败有兜底：原草稿已被删除或无权操作时自动改为新建；封面素材失效时重新上传封面再覆盖一次；已经群发过的文章无法修改，会提示改用新建
- 多图文草稿（一篇草稿里含多篇文章）暂不支持整体覆盖，选择列表中会给出提示

### 拉取草稿到 Obsidian

草稿箱里的文章不只能在网页后台看：在草稿管理面板点每篇草稿右侧的 **拉取到笔记**，插件会把这篇草稿完整拉回 vault。

点下按钮后会先弹出**目录选择**：列出 vault 内全部文件夹，搜索框里也可以直接输入一个尚不存在的路径（按回车即用该路径，不存在会自动创建）。默认选中上次用过的目录，所以重复拉取只需回车确认。

拉取时会做四件事：

1. **正文还原成 Markdown**：标题层级、列表、表格、代码块、公式、图片、链接、引用块都会还原成可直接编辑的源码；插件自己生成的 callout 卡片会还原成 `> [!tip]` 语法，主题注入的装饰符号（列表圆点等）会被剥掉
2. **图片下载进 vault**：正文图片按 Obsidian 的附件设置存放（跟随你的「附件默认位置」），正文里的链接改写成相对路径；下载失败的图片保留原 URL，正文仍然完整
3. **元信息写进 frontmatter**：草稿的 `media_id`、标题、作者、摘要、原文链接、封面素材 id 写进笔记的 `wechat` 段。这些字段无法从正文还原，留着它们才能原样发布回去
4. **登记关联**：之后打开这篇笔记点发布，弹窗默认就是「覆盖更新已有草稿」，作者、摘要、原文链接、封面都会预填好

相关设置（设置 → Markdown Publisher → 草稿拉取）：

- **默认拉取文件夹**：拉取时目录选择的默认值；每次拉取都会先弹出目录选择，可临时改到 vault 内任意文件夹，也可以直接输入一个尚不存在的路径新建。留空则默认选中 vault 根目录；图片仍按 Obsidian 的附件设置存放

几点说明：

- 草稿已经有对应笔记时按钮显示为 **重新拉取**，会覆盖那篇笔记——本地还没发布的改动会丢，所以会先弹确认
- 拉取后再发布时，正文里已经是微信 CDN 地址的图片不会重复上传，只有你新插入的本地图片才会上传
- 拉取还原的是**可编辑的源码**，不是逐像素的样式快照：公众号正文本来只认内联样式，重新发布时会用当前主题重新排版。想保持原样就不要改正文，直接覆盖更新
- 多图文草稿只拉第一篇，其余图文会给出提示

### 主题与样式

内置 **11 套排版主题**，统一设计语言「纸上编辑部」，分四个经典家族与三个单套方向：

- **柔和轻氧**：晨雾 Mist（默认，通用首选）、蜜桃 Peach（温暖陪伴）
- **学院学术**：学报 Journal（深度长文、三线表）、笔记 Notes（手帐感、荧光笔重点）
- **杂志风尚**：封面 Cover（刊物级黑白红）、别册 Booklet（纸质文艺小册）
- **素纸墨蓝**：信笺 Letter（暖纸衬线、疏朗慢读）、拓本 Rubbing（素面严肃、碑帖资料）
- **终端极客**：终端 Terminal（墨板标题条、等宽序标，开发教程与工具评测）
- **商务数据**：账本 Ledger（报告头式标题、报表三线表，行业与财经分析）
- **节庆活力**：橙意 Festive（橙底徽章标题、票根式引用，盘点清单与活动运营）

每套排版主题都自带一套经过对比度校验的深色代码高亮（Dracula、GitHub Dark 等），不需要单独选择；想覆盖时可在设置里指定其它深色高亮。还可以在「自定义 CSS」中覆盖任意主题规则（会内联生效）。整体效果见 [主题设计稿](./theme-preview.html)。

#### 自定义主题

两种方式：

- **「自定义 Custom」主题**：内置一个空白气质层入口，配合设置中的「自定义 CSS」，从零搭建你的排版。
- **导入主题文件**：在 vault 的 `.obsidian/plugins/md-publisher/themes/` 文件夹（路径可在设置中修改）放入任意数量的 `.css` 文件，每个文件就是一套主题。插件会自动叠加通用基础样式，主题文件只需写颜色、标题记号等「气质层」规则（选择器以 `#bm-md` 开头）。文件首行加注释（例如 `name: 我的企业风`）可指定主题名，否则使用文件名。修改后点设置中的「重新扫描」即可。

### 预览与发布前校验

- **双向滚动同步**：编辑器与预览面板按比例同步滚动位置（设置 → 预览 → 双向滚动同步，可关闭）。
- **实时字数提示**：发布弹窗中标题 / 作者 / 摘要实时显示 `已输入 / 上限`，超限即时变红。
- **实时预览**：左侧手机预览跟随表单即时更新，可在「文章页」「分享卡片」「手机预览」三个标签间切换，所见即发布后的样子。
- **发布前检查**：点弹窗底部的「发布前检查」，结果在弹窗下方的抽屉里列出，页脚同时显示一条摘要（如 `链接 1 条失败 · 敏感词 2`）。检查只做提示，不阻止发布。
  - **链接有效性**：检查正文全部外链是否可访问（HEAD 优先，超时 8 秒），结果逐条列出失效原因。
  - **敏感词检测**：基于内置启发式词表（极限用语 / 医疗夸大 / 收益承诺 / 诱导互动）扫描标题、摘要与正文，命中词条附上下文片段；可在设置中补充自定义词条。

### 内容格式兼容

- **Mermaid 图表**：\`\`\`mermaid 代码块自动渲染为高清 PNG 并随图片上传到微信 CDN；语法错误时保留原代码块，不会阻塞发布。
- **Callout 提示框**：`> [!note] 标题` 语法转为公众号可渲染的卡片样式（note / tip / warning / danger / example 等 13 种类型各有配色）；`> [!tip]-` 折叠写法仅保留标题卡片（公众号正文不支持折叠交互）。
- **笔记嵌入**：`![[笔记名]]` 将整篇笔记折入引用块；`![[笔记名#标题]]` 只嵌入该标题下的章节。未找到笔记时显示占位提示，不影响其余内容发布。

## 四、支持的内容格式

- GFM 表格、任务列表、脚注、删除线
- KaTeX 数学公式（块级 `$$...$$`；行内 `$...$` 默认关闭，见下方说明）
- 代码块高亮（样式内联到公众号）
- Obsidian 图片嵌入语法 `![[图片.png]]` 与 `![[图片.png|300]]`（尺寸后缀会被忽略，代码块中不会误转换）
- Obsidian 高亮 `==文本==`（转为带主题配色的背景高亮）
- Obsidian 双链 `[[笔记]]` / `[[笔记|别名]]` / `[[笔记#小节]]`（公众号不支持 vault 内跳转，按可读文本输出，如「笔记」「别名」「笔记 > 小节」）

### 任务列表与脚注在公众号里的样子

微信公众号编辑器会过滤部分 HTML，插件在渲染阶段做了两处等效替换：

- **任务列表**：`- [x]` / `- [ ]` 的复选框换成 ✓ / □ 文本符号并保留主题色，勾选状态在文章里清晰可见；同时不会再叠加列表圆点
- **脚注**：保留角标数字与脚注正文，去掉页内跳转锚点与 `↩` 回跳符号（公众号不支持页内跳转，留着只是乱码）

### 关于美元符号与公式

为避免把正文里的金额与 Shell 变量当成公式改写，**单个 `$` 之间的内容默认按普通文本输出**：

- `从 $10 到 $20 不等`、`粗估 $150-250/月（集群 ~$30）`、`export A=$1 B=$2` 均原样保留
- 块级公式 `$$...$$` 始终按公式渲染，不受此设置影响
- 如果你的笔记确实使用单个 `$` 写行内公式（如 `$E=mc^2$`），到 **设置 → Markdown Publisher → 排版 → 解析行内公式 `$...$`** 打开即可；打开后金额写法会重新按公式解析，请按笔记实际用法取舍

### 复制到公众号时的图片

点「复制」会把本地图片与外链图片内联为 data URL 一并放进剪贴板，粘贴到公众号编辑器即可直接显示，不会出现裂图。因此：

- 复制包含图片的笔记时，剪贴板体积会明显变大（图片以 base64 随 HTML 携带），属正常现象
- 个别图片读取或下载失败时会给出提示，失败位置留空，其余内容正常复制
- 粘贴到纯文本编辑器时得到的是剥离标签的纯文本，不会看到 HTML 源码

### 图片处理规则

- 本地图片自动压缩并上传到微信素材 CDN（默认 quality 0.8）
- GIF 保留动画；SVG 自动转为 PNG
- WebP / BMP / AVIF 等微信不支持的格式自动转为 PNG 后上传
- PNG 保留透明通道；需要转 JPEG 压缩时自动铺白底，不会出现黑底
- 同一图片在文中出现多次时只上传一次，复用微信 URL
- 多张图片并发上传（3 路），长文的等待时间不再随图片数量线性增长；结果顺序仍与正文一致，首图仍作为默认封面
- 任一图片上传或下载失败时会取消发布并明确提示，不会产出残留本地路径的裂图草稿

## 五、常见问题

**Q：测试连接失败？**
检查 AppID/AppSecret 是否正确、本机 IP 是否已加入白名单（自动模式），或 token 是否已过期（手动模式）。

**Q：发布报错 IP 不在白名单？**
自动模式要求本机公网 IP 在白名单内；换网络后 IP 会变。可改用手动 token 模式绕过。

**Q：为什么没有移动端？**
插件依赖桌面端能力，目前仅支持 Obsidian 桌面版。

**Q：发布的文章样式错乱？**
公众号编辑器限制较多，个别标签会被过滤。先在预览面板确认效果，必要时用「自定义 CSS」调整，或复制 HTML 粘贴后在编辑器中微调。

**Q：图片上传失败？**
确认图片可被 Obsidian 访问（本地路径或可下载的 URL），过大图片先手动压缩。

---

## 许可与反馈

本项目基于 [MIT License](../LICENSE) 开源。遇到问题或功能建议，欢迎到 [Issues](https://github.com/volcanicll/obsidian-md-publisher/issues) 反馈。