Markdown 模板

Markdown 模板是什麼

用 Markdown 寫東西的時候，你有沒有遇到過這種情況——每次新建檔案都要從頭搭建結構，標題層級、目錄格式、程式碼區塊風格……反覆敲一遍。

Markdown 模板就是解決這個問題的。它是一套預先定義好結構的 Markdown 檔案框架，你可以直接複製過來，填上自己的內容就走人。不管是寫專案 README、技術文件、會議記錄還是週報，都有對應的模板可以直接用。

說實話，我自己用了好幾年 Markdown，真正體會到模板的威力是在維護一個多人文件倉庫的時候。當時團隊裡每個人寫的文件格式都不一樣——有人用三級標題開頭，有人上來就放表格。後來統一用了一套文件模板，整個倉庫的閱讀體驗立刻就上了一個檔次。

常用 Markdown 模板大全

下面這些模板我都實際用過或者見過不錯的設計，每種模板都給出了完整程式碼，直接複製就能用。

README 模板

GitHub 專案的門面，一個好的 README markdown template 能讓訪客 30 秒內搞清楚你的專案是做什麼的。


> 一句話描述你的專案做什麼

## 功能特色

- 特色一：簡要說明
- 特色二：簡要說明
- 特色三：簡要說明

## 快速開始

### 安裝

```bash
npm install your-package

使用

import { something } from 'your-package'

something.init()

設定說明

參數	類型	預設值	說明
option1	string	'default'	參數說明
option2	number	100	參數說明

常見問題

Q: 遇到 XX 問題怎麼辦？

A: 檢查你的設定檔是否正確。

貢獻指南

Fork 本倉庫
建立特性分支 (git checkout -b feature/amazing-feature)
提交改動 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
提交 Pull Request

授權條款

MIT License


### 技術文件模板

寫技術文件最怕的就是結構混亂，讀者翻半天找不到想看的內容。下面這個模板參考了社群裡比較成熟的技術文件結構，適合 API 文件、系統設計文件等場景。

```markdown
# 文件標題

## 概述

簡要描述本文件的目的、適用範圍和目標讀者。

## 目錄

- [背景](#背景)
- [設計方案](#設計方案)
- [使用方法](#使用方法)
- [範例](#範例)
- [常見問題](#常見問題)

## 背景

描述問題背景、需求和現有方案的不足。

## 設計方案

### 整體架構

描述系統的整體架構和核心元件。

### 技術選型

| 方案 | 優點 | 缺點 |
|------|------|------|
| 方案 A | 簡單直接 | 擴展性差 |
| 方案 B | 效能好 | 實作複雜 |

## 使用方法

### 前置條件

- Node.js >= 18
- npm >= 9

### 安裝步驟

1. 複製倉庫
2. 安裝依賴
3. 啟動服務

## 範例

```bash
# 啟動開發伺服器
npm run dev

常見問題

問題 1

症狀：XXX 不運作

原因：XXX 設定有誤

解決：修改 XXX 設定項

更新日誌

日期	版本	變更內容
2025-01-15	v1.0.0	初始版本


### 變更日誌（Changelog）模板

[Keep a Changelog](https://keepachangelog.com) 是社群公認的變更日誌標準格式。我之前在團隊專案裡推行這個格式，最大的感受是——它讓 changelog 終於變得對人類友善了，不再是 git log 的複製貼上。

```markdown
# Changelog

本檔案記錄專案所有重要變更。

格式基於 [Keep a Changelog](https://keepachangelog.com/)，
版本號遵循 [語意化版本](https://semver.org/)。

## [Unreleased]

### Added
- 新增 XXX 功能

### Changed
- 修改了 XXX 的行為

### Fixed
- 修復了 XXX 問題

## [1.0.0] - 2025-01-15

### Added
- 初始發布版本
- 支援基本的 XXX 功能
- 完整的 API 文件

會議記錄模板

這個模板我用了大概兩年，幾經調整才變成現在這個樣子。關鍵是資訊密度要夠——開會不是聊天，每條討論項都要有結論或後續動作。

# 會議記錄：{會議主題}

- **日期**：YYYY-MM-DD
- **出席人員**：張三、李四、王五
- **記錄人**：張三

## 議題一：{議題名稱}

**背景**：為什麼要討論這個

**討論要點**：
- 要點 1
- 要點 2

**結論**：XXX

**後續行動**：

| 負責人 | 任務 | 截止日期 |
|--------|------|----------|
| 張三 | 完成 A 任務 | 01-20 |
| 李四 | 完成 B 任務 | 01-25 |

## 議題二：{議題名稱}

**背景**：簡要說明

**討論要點**：
- 要點 1

**結論**：XXX

**後續行動**：
- 張三：跟進 XX 事項

## 下次會議

- 時間：YYYY-MM-DD
- 預計議題：XXX

週報/工作彙報模板

# 週報 — {姓名} — 第 {N} 週

## 本週完成

- [x] 任務 A：完成了 XXX
- [x] 任務 B：完成了 XXX
- [ ] 任務 C：進行中（進度 70%）

## 遇到的問題

1. **問題描述**：XXX
   - 影響範圍：XXX
   - 目前狀態：已解決 / 跟進中

## 下週計畫

- [ ] 任務 D
- [ ] 任務 E

## 需要的支援

- 需要團隊 B 配合 XXX

怎麼建立自己的 Markdown 模板

上面那些現成模板可以直接用，但很多時候你需要根據自己的需求做調整，甚至從零建立。這裡講一下我的方法。

確定模板結構

建立模板之前，先想清楚三個問題：

誰會看這個文件 — 是給自己看的筆記，還是給團隊看的文件，還是給外部使用者看的說明
核心資訊是什麼 — 這個文件必須包含哪些內容，不能少
更新頻率 — 是一次性的還是需要反覆更新

比如寫部落格文章模板和寫 API 文件模板，結構就完全不同。部落格文章可能只需要標題、正文和標籤，但 API 文件需要請求參數表、回傳值說明、錯誤碼列表。

用 Front Matter 添加詮釋資料

如果你用 Hugo、Jekyll 這類靜態網站產生器，或者 Obsidian 這類筆記工具，Front Matter 基本上是標配。它放在檔案最開頭，用 --- 包裹，用來定義文件的詮釋資訊：

---
title: 文章標題
date: 2025-01-15
tags: [markdown, tutorial]
author: 張三
draft: false
---

## 正文從這裡開始

我之前從 Hexo 遷移到 Hugo 的時候，才發現兩個平台對 Front Matter 的處理方式不一樣——Hugo 預設用 TOML 格式（+++ 包裹），Jekyll 用 YAML 格式（--- 包裹）。後來我統一用 YAML，因為相容性更好，大多數工具都認。

模板變數的使用

當模板裡需要動態內容時，可以用變數佔位符。不同工具用的語法不一樣：

工具/引擎	變數語法	範例
GitHub Issues/PR	`{{變數名}}`	`{{title}}`
Jekyll/Liquid	`{{ page.title }}`	`{{ page.title }}`
Hugo	`{{ .Title }}`	`{{ .Title }}`
Handlebars/Mustache	`{{變數名}}`	`{{name}}`
Jinja2 (Python)	`{{ 變數名 }}`	`{{ title }}`

舉個例子，GitHub 的 Issue 模板可以用 YAML Front Matter 定義表單欄位，配合 Markdown 正文：

---
name: Bug 報告
about: 回報一個 bug
title: '[BUG] '
labels: bug
---

## Bug 描述

簡要描述遇到的問題。

## 重現步驟

1. 進入 XXX 頁面
2. 點擊 XXX 按鈕
3. 看到 XXX 錯誤

## 預期行為

應該出現什麼

## 實際行為

實際出現了什麼

## 環境

- 作業系統：
- 瀏覽器：
- 版本號：

保存和重複使用模板

模板建好之後，有幾種常見的重複使用方式：

本機檔案：把模板放在一個固定目錄（比如 ~/templates/），需要的時候複製過來
GitHub：建一個 dotfiles 或 markdown-templates 倉庫統一管理
編輯器片段（Snippet）：VS Code 支援使用者自訂程式碼片段，可以把模板綁定到快速鍵上
CLI 工具：用 cookiecutter 這類工具，一條命令從模板產生專案骨架

對了，VS Code 的 Snippet 功能可能很多人沒用過。在 VS Code 裡按 Ctrl+Shift+P，搜 "Configure User Snippets"，選 markdown.json，就可以定義自己的 Markdown 模板片段了。比如定義一個 readme 快捷命令，輸入後自動展開成完整的 README 模板結構。

不同平台的 Markdown 模板

Markdown 本身是個很寬鬆的規範，各平台的「方言」差別挺大。同一個模板在 GitHub 上好好的，搬到別的平台可能就出問題了。

GitHub 模板

GitHub 是 Markdown 模板用得最多的地方。除了 README 模板，GitHub 還支援：

Issue 模板：放在 .github/ISSUE_TEMPLATE/ 目錄下
PR 模板：放在 .github/PULL_REQUEST_TEMPLATE.md
討論模板：放在 .github/DISCUSSION_TEMPLATE/ 目錄下

GitHub 用的是 GitHub Flavored Markdown（GFM），在標準 Markdown 基礎上擴展了表格、任務列表、刪除線、自動連結等功能。

Obsidian 筆記模板

Obsidian 的核心外掛裡有專門的「模板」功能。你可以在設定裡指定一個模板資料夾，然後透過快速鍵或命令面板插入模板內容。

Obsidian 模板支援日期變數，比如 {{date}} 和 {{time}}，還可以搭配 Templater 社群外掛實現更強大的動態模板。

VS Code 中的模板

除了前面說的 Snippet，VS Code 還有一些擴展專門做 Markdown 模板管理，比如 "Markdown All in One" 就提供了快捷操作。如果你經常寫 Markdown，這個擴展基本上是必裝的。

常見問題

Markdown 模板和普通 Markdown 檔案有什麼區別？

本質上沒有區別——模板就是一個普通的 Markdown 檔案，只是它預留了佔位符和結構骨架，方便你重複使用。你可以把任何寫得不錯的 Markdown 文件改造成模板，只需要把具體內容替換成通用描述或變數就行。

為什麼我的模板在 GitHub 上顯示正常，到其他平台就亂了？

因為各平台的 Markdown 解析器不一樣。GitHub 用的是 GFM，支援表格、任務列表、註腳等擴展語法。但有些平台（比如一些電子郵件用戶端）只支援基本 Markdown。寫通用模板時，盡量用基礎語法，少用平台特有的擴展。

怎麼讓團隊統一使用模板？

最簡單的辦法是把它放到專案倉庫裡。比如在團隊倉庫的根目錄放一個 docs/templates/ 資料夾，新人文件或 PR 模板從這裡複製。再搭配 CI 檢查（比如用 markdownlint 檢查格式），就能逐步統一。

參考來源

Basic Syntax - Markdown Guide — Markdown 基礎語法權威參考
GitHub Docs - Writing on GitHub — GitHub Flavored Markdown 官方文件
Keep a Changelog — 變更日誌格式的社群標準
CommonMark Spec — Markdown 標準規範
GitHub Markdown Templates — GitHub 上的 Markdown 模板合集