[其他] 什麼是 Markdown (.md)？初學者指南 (Gemini CLI 文檔)

如果你是程式初學者，剛開始接觸開發工具，像是需要為 Gemini CLI 寫規格文件，那麼你一定會遇到 .md 檔案。別擔心，這篇文章會用最簡單的方式解釋什麼是 Markdown (.md)，並教你如何用它來寫出清楚的規格文檔。讓我們一步步來！

Markdown 是什麼？

Markdown 是一種「輕量級標記語言」（lightweight markup language），它讓你可以用簡單的文字符號來格式化內容，而不需要複雜的 HTML 程式碼。它的檔案副檔名通常是 .md（來自 Markdown 的縮寫）。

想像一下，你在寫筆記或文件時，想加粗文字、做清單或插入程式碼區塊。Markdown 讓這些變得超簡單！它最初是由 John Gruber 在 2004 年發明的，現在廣泛用在 GitHub 的 README.md、部落格文章、甚至是像 Gemini CLI 這樣的工具規格文件中。

為什麼適合程式初學者？因為 Markdown 不需要學太多規則，就能快速寫出專業的文檔。尤其是當你用 Gemini CLI 時，規格文件通常是用 .md 格式，方便工具讀取和顯示。

為什麼需要用 Markdown 寫規格給 Gemini CLI？

Gemini CLI（假設你是用 Google 的 AI 工具 CLI 版本）常常要求輸入規格文件來生成程式碼、API 或其他輸出。這些規格用 .md 寫，因為：

  • 易讀性高：人類和機器都能輕鬆理解。
  • 版本控制友好：用 Git 管理時，.md 檔案小巧且易追蹤變化。
  • 跨平台：可以用任何文字編輯器（如 Notepad、VS Code）編寫，不需要特殊軟體。

例如，你可能需要寫一個 API 規格的 .md 文件，描述端點、參數和範例，然後餵給 Gemini CLI 讓它幫你生成程式碼。

Markdown 的基本語法

讓我們來看一些常用語法。記住，Markdown 是用純文字寫的，符號會自動轉換成格式。以下是初學者必學的：

1. 標題（Headers）

用 # 符號來表示層級。越多 #，標題越小。

# 這是一級標題
## 這是二級標題
### 這是三級標題

顯示效果：

這是一級標題

這是二級標題

這是三級標題

2. 粗體和斜體（Bold & Italic）

用 * 或 ** 包住文字。

**粗體文字**
*斜體文字*
***粗斜體***

顯示： 粗體文字， 斜體文字， 粗斜體。

3. 清單（Lists）

無序清單用 - 或 *，有序用數字。

- 項目一
- 項目二

1. 第一步
2. 第二步

顯示：

  • 項目一
  • 項目二
  1. 第一步
  2. 第二步

4. 連結和圖片（Links & Images）

連結用 [文字](網址)，圖片加 ! 在前面。

[Google](https://www.google.com)
![圖片描述](https://example.com/image.jpg)

顯示： Google，和一張圖片（如果有網址）。

5. 程式碼區塊（Code Blocks）

這對程式規格超重要！用三個反引號 ``` 包住程式碼，還可以指定語言。

```python
def hello():
    print("Hello, World!")
```

顯示：

def hello():
    print("Hello, World!")

在 Gemini CLI 的規格中，你可以用這個來放範例程式碼。

6. 表格（Tables）

用 | 和 - 來畫表格。

| 欄位 | 描述 |
|-------|------|
| 名稱 | 王小明 |
| 學歷 | 台大資工系 |
| 年齡 | 30 |

顯示：

欄位 描述
名稱 王小明
學歷 台大資工系
年齡 30

如何開始寫你的第一個 .md 文件？

  1. 開啟文字編輯器（如 VS Code，推薦安裝 Markdown 擴充套件預覽）。
  2. 新建檔案，存成 something.md。
  3. 用以上語法寫內容，例如規格的介紹、需求清單和程式碼範例。
  4. 餵給 Gemini CLI：根據工具說明，像是 gemini-cli --spec yourfile.md。

小提示：練習時，可以用在線工具如 Dillinger.io 來即時預覽你的 Markdown。

常見錯誤與Tips

  • 記得空格：清單或表格需要正確對齊。
  • 不要混用 HTML：Markdown 是為了取代它，除非必要。
  • 版本差異：有些平台（如 GitHub）支援額外功能，測試一下。
  • 對 Gemini CLI：確保規格清晰，用標題分段，程式碼區塊放範例。

Markdown 學會後，你會愛上它的簡單！如果你是程式初學者，從現在開始練習寫 .md 規格吧。它不只幫你用 Gemini CLI，還能在未來專案中大放異彩。有問題？歡迎留言討論！

（本文適合 2026 年初學者，基於標準 Markdown 語法。如有更新，請查官方文件。）