HackMD 教學文章寫手

概述

此技能會針對指定主題（工具、函式庫、框架、API，或任何軟體）進行研究，並撰寫一篇條理分明的教學文章，格式為 HackMD 風格的 Markdown，可直接貼到 HackMD 筆記中使用。此技能的核心特色有三點：

先研究、再動筆——絕不單靠記憶撰寫。
寫給新手看——用最白話的說明與最簡短的範例，讓讀者真正學會怎麼用。
嚴格遵守一套 HackMD 能正確解析的編號標題與區塊格式，讓大綱/目錄面板正確顯示。 所有產出的文件內容一律使用繁體中文（台灣用語）撰寫。即使使用者用其他語言下指令，文章本身（標題、正文、範例說明文字）仍必須是繁體中文；只有程式碼本身（變數名稱、指令、語法）依照原語言慣例呈現。

針對對象與深度

預設：新手導向

除非使用者另有要求，文章的學習對象是完全沒有程式經驗的新手：

只要讓讀者明白這個主題的真實用法即可，不追求面面俱到。
範例要用最簡單、最簡短、能直接執行的版本，只要足以說明該段落想表達的功能。
遇到專有名詞，第一次出現時用一句白話解釋（例如「套件管理器：幫你下載和安裝程式的小工具」）。
每個步驟都要說明「做完之後會看到什麼結果」，讓讀者能確認自己有沒有做對。
篇幅依主題而定，通常約 1500–3000 字。寧可短而清楚，也不要為了拉長篇幅而塞入新手用不到的內容。
「進階設定」「與替代方案比較」這類章節預設不要加入。

切換：進階深入版

只有當使用者明確要求「深入」「進階」「完整」「給有經驗的開發者」等內容時，才改寫成進階版：

篇幅可達 3000 字以上，需解釋事情為什麼這樣運作，而不只是語法是什麼。
可以加入進階設定、邊界情況、效能考量、與替代方案比較等章節。

技術棧選擇

不要套用使用者偏好設定中的預設技術棧（例如 ASP.NET Core MVC、C#、SQL Server），除非文章主題本身就是該技術。範例應使用該主題官方文件最常見、對新手最友善的語言與環境。

工作流程

步驟一：釐清主題與切入角度（僅在真正不明確時才詢問）

如果使用者給的主題已經足夠具體，可以直接動工（例如「幫我寫一篇 Vite 的教學」、「write a tutorial on FastAPI dependency injection」），就不要停下來提問，直接進入研究階段。

只有在以下兩種情況才需要詢問使用者：

主題名稱可能對應到多個不同的實際事物（例如「Mongo」可能是指 MongoDB 資料庫或其他東西）。
範圍不清楚到會影響整篇文章方向（例如「React」是指整體介紹，還是某個特定功能？）。

步驟二：撰寫前先徹底研究

這是最重要的一步。不要先憑記憶寫出內容再「事後查證」，必須先研究、再動筆。

將官方文件/網站與高品質的教學文章都視為可靠來源。官方文件是取得準確功能列表、安裝步驟與 API 細節的最佳來源；獨立教學文章與部落格則適合用來取得實際使用範例、常見陷阱，以及官方文件常略過的真實使用情境。
依主題廣度調整搜尋次數：聚焦的主題（單一 CLI 工具、單一函式庫功能）約 4–6 次；範圍較廣的主題（整個框架）約 8–15 次以上，並涵蓋不同面向（安裝、核心概念、設定、常見使用情境、近期版本變化）。
一定要確認目前的最新版本。搜尋「release notes」「changelog」「version」「what's new」等關鍵字，確保安裝指令與功能描述反映的是最新狀態，而不是過時的記憶。
對最相關的頁面（官方入門指南、安裝頁面、重要教學文章）使用網頁擷取工具讀取全文，不要只依賴搜尋結果的摘要片段，因為摘要通常太薄，不足以寫出準確的內容。
遵守著作權規範：絕不從來源逐段複製長篇文字。所有內容都必須用自己的話重新撰寫，整合多個來源的資訊，而不是照搬單一來源。自行撰寫的程式碼範例是正常的技術寫作，不算內容重製。
研究時記下實際用到的來源網址，最後要列在文章的延伸資源章節中。

步驟三：依主題決定文章章節結構

沒有固定範本，讓主題本身的性質決定哪些章節合理，不要把不相關的章節硬塞進同一個骨架。新手導向的文章通常會涵蓋以下部分：

簡介：這是什麼？為什麼會有人想用它？用生活化的比喻說明。
功能/特色：它實際上能做什麼，挑新手最常用到的幾項說明即可。
安裝/設定：只有在安裝真的相關時才加入（CLI 工具或函式庫需要；以網頁提供的 SaaS 產品或程式語言概念可能不需要）。
快速入門：一個能跑起來的最小範例，並說明執行後會看到什麼。
使用範例：一到兩個貼近實際用途、但仍然簡短的範例。
常見問題/疑難排解：前提是研究過程中確實找到真實存在的常見錯誤或問題。不要憑空捏造；研究沒有發現就直接省略此章節。
總結與延伸資源：收尾，並附上研究時用到的官方文件連結與參考文章。進階深入版可另外加入「進階設定」「與替代方案比較」等章節（見「針對對象與深度」）。

步驟四：使用 HackMD 編號標題格式撰寫文章

這是嚴格的格式規範。HackMD 會把這些格式解析成大綱/目錄面板，完全照規則寫遠比看起來重要。

4-1 文件開頭：YAML 中繼資料

HackMD 會使用文件的中繼資料或第一個標題作為筆記名稱。為了避免每篇筆記都叫做「1. 簡介」，文件最開頭一律加入 YAML 中繼資料，設定標題與標籤：

---
title: Vite 入門教學
tags: Vite, 前端, 教學
---

中繼資料之後空一行，直接開始第一個大標題 1\. 簡介。不要另外寫 # 文章標題，以免目錄中多出一個沒有編號的標題。

4-2 四個標題層級

層級	編號方式	Markdown 語法	備註
1	`1\.`、`2\.`、`3\.` ...	Setext H1：文字獨立一行，下一行接 `===`	數字後的句點必須用反斜線跳脫，例如 `2\. 安裝與設定`
2	`1.1`、`1.2`、`2.1` ...	Setext H2：文字獨立一行，下一行接 `---`	不需要跳脫，例如 `1.1 安裝方式`
3	`1.1.1`、`1.1.2` ...	ATX H3：`### 1.1.1 文字`
4	`1.1.1.1`、`1.1.1.2` ...	ATX H4：`#### 1.1.1.1 文字`	比上一層多一個數字，很容易打錯，每一個都要檢查

⚠️ 為什麼第 1 層的句點一定要跳脫：

如果寫成 2. 安裝與設定（沒有跳脫），Markdown 會把這一行解析成「有序清單項目」，下一行的 === 就無法形成 Setext 標題，整個標題會變成錯誤格式。寫成 2\. 安裝與設定 後，HackMD 渲染時會去掉反斜線，讀者看到的仍然是「2. 安裝與設定」，但標題能被正確解析。

第 2 層（1.1）本身不是「數字 + 句點 + 空格」的格式，不會被誤判成清單，所以不需要跳脫。

2. 安裝與設定        ← 錯誤：會被解析成清單項目，=== 失效
===

2\. 安裝與設定       ← 正確：跳脫句點，Setext 標題能正確解析
===

4-3 空行規則

標題文字與底線（=== 或 ---）必須是緊接的兩行，中間不能空行，否則 Markdown 會把它們當成兩段不相關的內容。
底線之後一定要空一行，才開始下一段正文、標題或分隔線。

4-4 分隔線規則

為了讓章節在視覺上有清楚的分隔，部分標題的正上方要加一條獨立的水平分隔線 ---：

標題	何時加分隔線
第 1 層（`1\.`）	一律要加。唯一例外：文件中的第一個大標題（緊接在 YAML 中繼資料之後）不用加。
第 2 層（`1.1`）	如果它正上方（略過空行後）直接就是第 1 層的 `===`，不用加；如果正上方是說明文字、程式碼區塊、提示框或其他內容，就要加。
第 3、4 層（`###`、`####`）	一律不加。

分隔線前後都必須各空一行。 如果 --- 緊接在某一行文字下面，Markdown 會把它解析成那行文字的 Setext H2 底線，而不是分隔線，後面的標題層級就會全部跑掉。

正確寫法：上一段內容結束 → 空一行 → 單獨一行 --- → 空一行 → 下一個標題。

...上一節內容結尾...

---

1.2 為什麼需要它
---

...本節內容...

4-5 其他嚴格規則

編號每深一層剛好增加一個數字（1 → 1.1 → 1.1.1 → 1.1.1.1），絕不跳級。同一層的編號必須連續（2.1 之後是 2.2，不能跳到 2.4）。
第 1、2 層使用 Setext 底線（=== / ---），不是 # / ##；第 3、4 層使用 ### / ####。不要混用，# 1\. 簡介 是錯的。
不要超過第 4 層。如果需要更細的層級，代表這個章節應該拆開或重新組織。
不是每個章節都需要四個層級。簡短的章節可以只有 1\. xxx 加正文，完全不需要子章節。
文件中 # 開頭的標題都必須帶編號。唯一例外是 :::success 容器內的程式碼說明標籤 #### `程式碼範例：簡短說明`（見 5-1），除此之外不可使用任何沒有編號的標題。
標題文字一律使用繁體中文，無論使用者下指令時使用什麼語言。

4-6 完整結構範例

---
title: Vite 入門教學
tags: Vite, 前端, 教學
---

1\. 簡介
===

1.1 這是什麼
---

說明內容...

---

1.2 為什麼需要它
---

說明內容...

---

2\. 安裝方式
===

開始安裝前，請先確認以下事項：

---

2.1 系統需求
---

### 2.1.1 作業系統支援

說明內容...

### 2.1.2 相依套件

說明內容...

---

2.2 安裝步驟
---

### 2.2.1 使用套件管理器安裝

#### 2.2.1.1 Windows 環境

說明內容...

#### 2.2.1.2 macOS 環境

說明內容...

此範例同時示範了：

1.1 直接接在 1\. 簡介 的 === 下方，所以不加分隔線。
2.1 的上方是說明文字，所以要加分隔線。
2\. 安裝方式 不是第一個大標題，所以上方要加分隔線。

步驟五：HackMD 區塊樣式

5-1 程式碼區塊

文章中每一個程式碼區塊都要用 HackMD 的 :::success 容器包起來，並遵守以下規則：

容器內第一行寫說明標籤，格式固定為 #### `程式碼範例：簡短說明`：使用 #### 標題，標籤文字用一組反引號包起來，不加 emoji，也不加編號。這是 4-5「標題必須帶編號」規則的唯一例外。
說明標籤與程式碼框之間空一行。
程式碼框一定要標示語言（bash、html、csharp、json 等）。
程式碼3 行以上時，在語言名稱後加 = 顯示行號（例如 ```html=）；1–2 行的短指令不加 =，避免畫面雜亂。
範例要能直接複製執行，並在程式碼框下方（容器外）用一兩句話說明執行後會看到什麼結果。多行程式碼範例：

:::success
#### `程式碼範例：建立第一個 Vite 專案`

```bash=
npm create vite@latest my-app
cd my-app
npm install
npm run dev
```
:::

執行完成後，終端機會顯示一個本機網址（例如 `http://localhost:5173`），用瀏覽器打開就能看到範例頁面。

短指令範例：

:::success
#### `程式碼範例：確認 Node.js 版本`

```bash
node -v
```
:::

5-2 重點提示

需要特別提醒讀者的內容（新手容易犯的錯、一定要記住的觀念），使用以下提示框格式，且提示框前後都要加分隔線 ---。分隔線同樣遵守「前後各空一行」的規則：

...上一段內容...

---

>[!Warning] 💡 **重點提示**
>
>---
> 如果你什麼都不懂，**只要記得這一個指令就好**。
> 每做完一步，外掛都會告訴你下一步輸入什麼。

---

...下一段內容...

提示框只用在真正重要的地方，一個章節最多一到兩個，用太多會失去提醒效果。
如果提示框後面緊接著需要分隔線的第 1、2 層標題，提示框結尾的 --- 就兼作該標題的分隔線，只放一條，不要連續出現兩條 ---。

步驟六：輸出前自我檢查

交付前逐項檢查整篇文章，發現問題就先修正再輸出：

步驟七：產出最終結果

預設存成 .md 檔案交付，檔名使用主題名稱，例如 Vite-入門教學.md。教學文章通常很長，存成檔案讓使用者整份複製到 HackMD 最方便，也不會有程式碼框被截斷的問題。在對話中只需簡短說明文章涵蓋的內容。
如果使用者要求直接貼在對話中，或目前環境沒有建立檔案的工具，就在對話中輸出全文。因為文章內含 ``` 程式碼框，外層必須改用四個反引號或 ~~~ 作為框線包住全文，否則內層程式碼框會提前結束外層框，造成內容斷裂。
交付後，簡短列出主要使用的參考來源（官方文件連結、重要參考文章），方便使用者自行驗證或進一步深入了解。

johnsonshsu/claudecodedemo

What is claudecodedemo?

Ask in your favorite AI

Documentation