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 可访问，并連結到具体工具頁。

發布后，用一两条聚焦的推广文案解释除錯問題，不要到处发同一段泛泛广告。