topmindspace/topmind-writing-skills / topmind-wechat-post
topmind-wechat-post
Verified创作、整理和排版公众号文章;支持工具/插件推荐结构、产品实测评测、深度解读与叙事随笔,从选题或底稿到 Markdown,按需导出内联 HTML、预览与上传清单。公众号短文用 topmind-briefs,独立改稿用 topmind-revise。
references/wechat-constraints.md
View on GitHub# 微信公众号编辑器硬约束
所有排版决策的依据。违反任一条,粘贴后的效果就会与预览不一致。
> **先厘清一个常见误解**:`::: stat`、`::: pull`、`==高亮==`、`[!徽章]` 这些**不是公众号语法**。
> 公众号后台是富文本编辑器,**根本不认 Markdown**。它们是我们自研的「中间标记」,
> 由 `md2wechat.py` 转成内联样式 HTML 后才粘进后台。所以判断「公众号支不支持」,
> 看的是**转换产物**(`section/p/span/div` + 内联样式),而不是 `:::` 本身。
> 本文件约束的就是「转换产物」必须遵守的规则。
## 1. 只保留内联样式
- 剥离 `<style>` 标签、`<link>`、`class` 属性、`id` 属性
- 剥离 `<script>`,所有交互失效
- **不用 `<div>`**:新版编辑器底层是 ProseMirror,白名单里没有 div。
div 包裹的块会连同它的背景、内边距、圆角**被整段吞掉**,只剩文字,
表面看就是「整篇没 CSS」。这是「粘贴后样式全丢」的头号元凶,比渐变被吃更隐蔽。
**一律用 `<section>`**(标签级硬约束清单见 `element-spec.md`)。
- **结论**:HTML 里每一个样式都必须写成 `style="..."`,不许出现 class 依赖
## 2. 外链
- 正文 `<a href>` 指向非白名单域名时,链接不可点(未认证订阅号尤其如此)
- 「阅读原文」是唯一官方外链入口
- **结论**:外链降级为「灰色小字 URL 文本」,读者手动复制;重要链接放「阅读原文」
## 3. 图片
- 本地相对路径 / `file://` 一律失效
- 远程图片在粘贴进入编辑器时,微信**多数情况下会自动抓取**转存素材库,但不保证(防盗链、content-type 不对、超时都会失败)
- **宽度用 `max-width:100%;height:auto`,绝不用 `width:100%`**:
正文容器约 677px,`width:100%` 会把 400px 的小截图强行拉满变糊,竖图更糟。
`max-width` 让大图缩到容器宽、小图保持原尺寸并居中。
- `WebP` 在正文图里不被支持(需转 PNG/GIF);`SVG` 完全不支持(需光栅化)
- **结论**:默认走「导出图片包 + 手动上传」;用 CDN 外链时必须提供上传清单兜底
## 4. 代码与特殊语法
- 无代码块语法,**不要用 `<pre>`**:pre 不自动换行,窄屏横向溢出,且会被格式检测标为风险项
- 用 `<section style="white-space:pre-wrap;word-break:break-all;">` + 等宽字体 + 深色底模拟
- **已发布文章里不可能有一键复制按钮**(2026-09-29 核实):公众号正文剥离 JS,
第三方工具的"复制代码"按钮只活在它们自己的预览页,进不了正文;编辑器原生代码块
也没有读者侧复制入口。``` 围栏渲染为高亮代码区(语言标签 + pre-wrap 自动折行),
读者靠长按/全选手动复制。需要分发"复制即用"的提示词时,走评论区置顶、附件、
或小程序文档等站外链路,**不要在正文里承诺一键复制**
- 不支持 mermaid、LaTeX、SVG 内联(部分 SVG 会被剥离)
- `<iframe>`、`<video>` 会被剥离,视频只能用公众号自带的腾讯视频/视频号组件
- **结论**:mermaid / 公式必须预渲染成 PNG 再插图
## 5. 字体与颜色
- 不允许自定义 font-family 之外的特殊字体,系统字体最稳
- 正文字号 15-16px 为佳,行高 1.7-1.8,段间距 20-24px
- `text-align` **只允许 `left` / `center` / `right`**。`justify` 会被格式检测判为「非标准值」,
且部分安卓机型出现难看字间距 → 正文统一 `left`,标题与图注用 `center`
## 6. 表格
- 支持,但**列数 > 4 时在手机端必然横向溢出**
- 表头**不要** `white-space:nowrap`,它会强制撑宽导致溢出;改用 `word-break:break-word`
- **不要用 `table-layout:fixed`**(本条修正了此前的错误建议):
`fixed` 会让各列宽度**均分**,5 列表格在 677px 正文宽里每列只有 135px,
中文会被压成竖条。除非逐列显式设置百分比宽度,否则它只会让小屏更糟。
正确做法是让列宽按内容自适应(`table-layout:auto`,即不写)。
- **不用 `<thead>` / `<tbody>` / `<colgroup>`**:公众号不支持表格分组标签,
表头行直接作为首个 `<tr>` 输出
- **结论**(与 `md2wechat.py` 的实现一致):
- 列数 ≤ 3 → 保留 `<table>`,`width:100%` + 内容自适应
- 列数 ≥ 4 → **转卡片化**,每行一张卡(首列作标题,其余「列名 + 值」成对),
彻底摆脱横向溢出。这是唯一稳的解法。
## 7. 格式检测硬约束(实测触发告警的项)
微信侧/第三方格式检测会逐段校验内联样式,以下写法会被告警:
| 写法 | 告警 | 正确做法 |
|---|---|---|
| `text-align:justify` | 文字对齐异常·非标准值 | `text-align:left` |
| `max-width:677px` 等 px 宽度 | 不同屏幕下宽度差异 | `max-width:100%` |
| `<div>` 包裹 | 块被整段吞掉(样式全丢) | `<section>` |
| `<pre>` + `white-space:pre` | pre 标签·移动端溢出 | `<section>` + `pre-wrap` + `break-all` |
| `<h1>` 标签 | 标题语义映射,字号被覆盖 | `<p>` + 内联样式(20px/700/居中) |
| `<figure>` / `<figcaption>` | 粘贴时剥离包裹,图注错位 | `<section>` + `<p>` + 独立图注 |
| `<thead>` / `<tbody>` / `<colgroup>` | 表格分组标签不被支持 | 表头行直接作为首个 `<tr>` |
| `table-layout:fixed` | 列宽均分,小屏中文压成竖条 | 不写(按内容自适应)或逐列显式设宽 |
| `display:flex` / `grid` | 布局属性被吞,内容堆叠 | 用 `<section>` + `padding` 模拟 |
| `display:inline-block` | 非常规 display 值,支持不稳定 | 尽量用行内 `<span>` + padding |
| `float` / `position` | 定位失效,元素错位 | 不用定位,用块级流式布局 |
| `linear-gradient` | 渐变被静默丢弃,退化成无背景 | 纯色 `background` |
| `box-shadow` | 阴影被丢弃 | 不用阴影;层次靠底色 + 左边框 |
| `rgba()` / `hsla()` / `opacity` | 透明度不支持 | 纯色十六进制 |
| `-webkit-*` 私有属性 | 非标准属性 | 不用 |
| 表头 `white-space:nowrap` | 内容溢出 | `word-break:break-word` |
**圆角(`border-radius`)是「优雅降级」例外**:可能被丢弃,丢了只是变直角,
不破坏结构与可读性。可以用,但**不要依赖圆角做视觉区分**——卡片之间的区别必须
同时有底色或左边框,否则圆角一丢就分不清了。
**三样最可靠的手段**:纯色 `background` + 大圆角 + 字号/颜色(无衬条)。
它们能覆盖 90% 的排版需求,且不会静默失效。
**本地预览页的宽度约束**要写进 `<head><style>`(粘进公众号时会被剥离),
正文内联样式始终保持百分比宽度——否则预览好看、粘贴后告警。
## 8. 粘贴方式
- 从浏览器复制渲染后的富文本,粘贴进编辑器可保留内联样式
- 直接粘贴 HTML 源码会被当成纯文本
- 不要用脚本直接注入剪贴板(`execCommand('copy')` 在预览页里可用,
但外部程序注入的 CF_HTML 微信识别率低,会退回纯文本)
- 推荐:本地 HTML 预览页 → 点「复制正文」或全选正文 → 复制 → 粘贴
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |