完整 README、常見錯誤、風格指南 — Practice
最後一單元：把前面學的全部串起來，寫一份「夠水準」的 README， 並建立一套長期適用的寫作習慣。
一份好的 README 通常包含：專案名、一句話簡介、功能清單、安裝與使用、License。下面是中英對照的完整示範：
# My Awesome Tool A CLI tool that turns Markdown into PDF. ## Features - Converts `.md` to `.pdf` - Supports GFM tables - Batch processing ## Install ```bash npm install -g my-tool ``` ## Usage ```bash my-tool build docs/ -o out.pdf ``` ## License MIT
標題用一級標題放專案名。
一句話簡介——讓人不需讀原始碼就知道這工具做什麼。
Features 清單——用無序清單條列賣點。
Install / Usage——用 fenced code block 放指令，方便複製。
License——直接寫檔名，附上授權全文連結。
| 錯誤 | 後果 | 修正 |
|---|---|---|
| 段落之間忘了空行 | 被合併成同一段 | 段落間留一個空行 |
| 行尾想換行卻只按 Enter | 沒有效果 | 行尾兩個空格，或直接開新段落 |
# 後面沒空格 | 可能不被當標題 | # 標題 加空格 |
標題下直接寫 --- | 變成二級標題 | 分隔線前留空行 |
| 表格欄位數不一致 | 渲染錯亂 | 每列欄位數對齊 |
中文與 ** 之間沒空格 | 粗體可能失效 | **重點** 兩側加空格 |
| 連結網址含空格 | 連結截斷 | 網址用 %20 或重寫 |
- 或 *，別混用。## 直接跳到 ####，維持層級完整。docs/。```bash 比裸 ``` 好。像程式碼有 linter，Markdown 也有：
| 工具 | 說明 |
|---|---|
| markdownlint | VS Code 外掛／CLI，檢查縮排、標題層級、行長度 |
| markdownlint-cli2 | 可接進 CI，PR 自動檢查 |
| prettier | 自動排版 Markdown |
寫給團隊或自己的文件，可以先約定：
> 標示。完成這 8 個單元，你已經掌握：