2026-06-1614 分钟阅读

发布技术文档前，先预览 Markdown、SVG、Open Graph 和截图

一篇技术文章发布前 checklist，覆盖 Markdown 预览、SVG 封面检查、Open Graph 卡片、截图、代码示例和常见发布错误。

发布质量也是产品质量的一部分

一篇技术文章即使内容正确，也可能因为代码块换行难看、封面图不清楚、Open Graph 标题被截断、截图没有展示有效结果而表现很差。

这条工作流把发布当成预览问题：先预览 Markdown，再检查 SVG 封面，再看 Open Graph，最后补真实截图。

技术文章发布前预览工作流 — 发布前预览应该覆盖正文、封面、社交卡片和最终截图。

Demo 1：Markdown 里必须有真实代码

不要只写营销文案。每篇教程至少放一个读者可以直接复制到工具里的代码片段。

Markdown 预览能提前发现标题层级、代码块、表格和链接问题。

markdown

## Debug a JSON response with jq

```text
.users[].email
---
{"users":[{"email":"ada@example.com"}]}
```

Expected result: one email string in the preview output.

有用的文章应该说明运行 demo 后读者会看到什么。

Demo 2：预览 SVG 封面源码

生成 SVG 封面很方便，但也可能出现文字断行、对比度不够、viewBox 太大或带有不安全脚本。发布前要先预览和清理。

如果 SVG 只是中间产物，博客和社交卡片建议使用导出的 PNG。

svg

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 630">
  <rect width="1200" height="630" rx="32" fill="#0f172a"/>
  <text x="80" y="170" font-size="64" fill="white">jq vs JSONPath</text>
  <text x="80" y="250" font-size="32" fill="#bfdbfe">API response debugging workflow</text>
</svg>

用 Open Graph 同比例预览封面，能提前发现裁切和排版问题。

Demo 3：检查 Open Graph 卡片

社交卡片应该描述这篇教程，而不是只写网站名称。图片 URL 也必须是平台可抓取的绝对地址。

发到开发者社区、newsletter 或产品更新页之前，先预览卡片。

html

<meta property="og:title" content="jq vs JSONPath: API response debugging workflow" />
<meta property="og:description" content="Copyable jq and JSONPath demos for inspecting large API payloads." />
<meta property="og:image" content="https://diagrampreview.com/blog/jq-vs-jsonpath-api-debugging-workflow.png" />

具体的 OG 文案通常比泛泛的产品口号更有效。

Demo 4：加入一张能证明工具可用的截图

生成封面不够。正文里至少要有一张 demo 图或截图，展示左侧源码、右侧预览结果。

对开发者来说，这张图回答的是：我粘贴这段代码后会发生什么。

常见错误

封面图看不出文章主题；代码示例无法运行；没有写预期输出；链接到首页而不是具体工具页；OG 图片还是本地地址。

修掉这些问题，文章才更像文档，而不是广告。

最终发布 checklist

预览 Markdown，运行代码示例，预览 SVG 或生成图，检查 Open Graph，确认图片 URL 可访问，并链接到具体工具页。

发布后，用一两条聚焦的推广文案解释调试问题，不要到处发同一段泛泛广告。