# Tech Blog Writing

> Guides writing and editing technical blog posts for recca0120.github.io (Hugo + Stack theme, bilingual zh-hant-tw + en). Covers article structure, SEO, frontmatter conventions, cover image generation, internal links via Hugo ref shortcode, plain blockquote callouts (for cross-post compatibility), and humanized zh-hant writing style. Use this skill whenever the user writes, drafts, edits, translates, or restructures any article on this blog — even if they don't explicitly say "blog post" (e.g. "幫我整理成一篇", "改寫這段", "翻成英文版").

- Skill: `recca0120/tech-blog-writing` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add recca0120/tech-blog-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/recca0120/tech-blog-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: recca0120 (https://skillmd.com/u/recca0120)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/recca0120/tech-blog-writing

---


# 技術部落格文章撰寫規範

## 專案資訊

- Hugo + Stack 主題
- 設定檔：`config/_default/` 下多個 `.toml`
- 文章放在：`content/post/{slug}/index.md`
- 部署：push 到 `main` 分支自動透過 GitHub Actions 部署到 GitHub Pages
- 網址：https://recca0120.github.io/

## 寫作流程

1. 建立目錄 `content/post/{slug}/`
2. 確認主題和目標讀者
3. 想一個帶數字或具體成果的標題
4. 寫 3 句 hook 開場（痛點、數據或場景）
5. 列出起承轉合的大綱
6. 寫繁體中文初稿 `index.md`（目標 1,500-2,500 字）
7. 套用 humanizer-zh 規則檢查 AI 痕跡
8. 確認程式碼可讀、有註解、可複製貼上
9. 加入相關文章的內部連結（格式：`[標題]({{< ref "/post/slug" >}})`，詳見 `writing-style.md`）
10. 需要補充、提示、警告時用純 blockquote（`> text`）— 避免 GitHub Alerts，因為 dev.to / Hashnode 不渲染
11. 文章末尾加入 `## 參考資源` 區塊（見參考資源規範）
12. 確認 frontmatter 格式正確（見 `frontmatter-reference.md`）
13. 寫英文版 `index.en.md`（完整翻譯，不是摘要）
14. 用 Cloudflare Workers AI 產封面圖（見 `cover-image.md`）
15. `hugo --gc --minify` 確認建置無錯誤
16. commit 並 push 到 `main`

## 文章結構：起承轉合

每篇文章必須有明確的敘事線。

- **起（問題或情境）**：直接描述狀況或目標，貼出錯誤訊息或觸發條件
- **承（原因分析）**：用一兩句話說明技術原因，貼關鍵原始碼片段
- **轉（解決方案）**：具體可操作的步驟，程式碼有語言標記和中文註解
- **合（補充）**：注意事項或替代方案。有就寫，沒有就不寫
- **參考資源**：文章末尾固定加上參考資源區塊（見下方規範）

## 參考資源區塊

每篇文章結尾必須加上 `## 參考資源` 區塊，列出撰寫本文時參考的官方文件、GitHub repo、相關教學等。

格式：

```markdown
## 參考資源

- [官方文件標題](https://official-docs-url)
- [GitHub Repo 名稱](https://github.com/org/repo)
- [相關文章或教學標題](https://url)
```

規則：
- 只列實際參考過的資源，不堆砌無關連結
- 連結文字用描述性短句，不要只寫 "官方文件" 或 URL
- 優先列：官方文件 > GitHub repo > 官方部落格文章 > 其他教學
- 英文版對應到相同資源的英文版頁面（如果有）
- 最少 2 個，最多 8 個

## 關鍵原則

### 語氣（詳見 `writing-style.md`）

- 用「我」描述自己的經驗，直接陳述事實
- 句子長短交錯，技術名詞保留英文，中英文之間空一格
- 禁止 AI 填充詞、聊天機器人語氣、三段式列舉

### SEO

- H1 包含主要關鍵字，前 100 字內出現主要關鍵字
- `description` 150-160 字元，包含關鍵字和價值主張
- 相關文章之間互相連結，用描述性錨點文字

### 套件介紹規範

- 首次提到套件名稱時，附上官方連結（GitHub repo、npm、Packagist 等）
- 文章介紹或深度使用的套件，加入 `tags`
- 介紹套件的文章必須包含安裝指令

### Agent 使用規則

- 批次處理文章時，使用 Agent tool 並行處理
- Agent 的 model 參數至少指定 `sonnet`，不要用 `haiku`
- 每個 agent 處理 10-15 篇為一批

## 參考文件

- `frontmatter-reference.md` — Frontmatter 格式、title/description/slug 規則、分類與標籤
- `cover-image.md` — Cloudflare Workers AI 封面圖產生
- `writing-style.md` — 語氣規範、高參與度寫作原則