Markdown 與 MD 檔入門

返回 Codex 教學總目錄

目標與開始之前

Markdown 是純文字的排版語法，.md 是常見副檔名。檔案本身可以用一般編輯器讀寫，預覽工具才把井字、星號和括號呈現成標題、清單與連結。把一個 Word 文件改名成 .md 不會轉換格式；同樣地，寫進程式碼區塊的命令也不會因為開啟預覽就執行。先認識文字與顯示的差別，才知道該修改哪裡。

步驟一：建立真正的純文字檔

在新的 codex-md-lab 資料夾開啟 VS Code，從檔案總管新增 README.md 與 notes.md。Windows、macOS、Linux 都使用相同檔名與大小寫，不要存成 README.md.txt。使用其他編輯器也可以，但要選純文字與 UTF-8；如果編輯器自動加 .txt，存檔後回檔案清單核對完整名稱。這次只用新資料夾，不覆寫正式專案既有 README。

將下面整段複製到 README.md，再儲存。外面顯示的程式碼框只是本網站讓你複製的容器，不必另外把它的外框加進文件；內容裡那三個反引號則是練習檔的一部分，必須保留。共同範例固定用英文檔名與文字，讓五語讀者可以對照同一份成果。

# Small Steps notebook

## Purpose

Keep a short record of this practice project.

## Working steps

1. Read the request.
2. Make one focused change.
3. Verify the result.

- Keep original files.
- Record checks that have not run.

[Open task notes](./notes.md)

## Example command

```sh
node --version
```

> This command is an example, not a record of execution.

接著在 notes.md 放入下一段並儲存。兩份文件放同一層，README 的 ./notes.md 表示從 README 所在資料夾找到 notes.md；notes 的 ./README.md 則回到原文件。這就是小型目錄與分篇互相連結的起點，不需要資料庫，也不需要先做網頁路由。

# Task notes

[Back to the notebook](./README.md)

## Accepted result

- **Completed** shows only finished tasks.
- `Read` is the sample task title.
- Empty titles must be rejected.

## Pending checks

The browser check has not run yet.

步驟二：看懂六種常用語法

# 後面有空格，表示主要標題；## 是下一層。這份筆記只有一個主標題，讓閱讀者先知道文件用途，再看段落。把所有句子都寫成大標題會失去結構，不是越醒目越好。標題文字改了以後，若其他地方有連到該章節，也要一起檢查；章節網址的產生方式可能因預覽工具而異。

編號清單適合步驟，減號清單適合彼此並列的條件。段落之間保留空白行，讓原始碼和預覽都容易閱讀。Completed 的兩組星號表示強調，單反引號包住 Read 表示行內程式文字；這些符號只改變呈現，不會讓 Codex 自動給該詞更高權限。引用符號 > 則用來區分說明或摘錄，不是「已經證實」的標章。

連結用方括號寫讀者看到的名稱，圓括號放目的地。本例用相對檔案路徑，外部網站則用完整 https 網址。不要把自己的 C:\Users 路徑寫成全站讀者都能開的連結，也不要把不存在的 notes.md 當成已完成文件。文字名稱可以不同，但目標路徑必須精確，尤其在區分大小寫的系統上。

程式碼區塊以相同組數的反引號開啟和結束，開頭的 sh 是語言標籤，幫助預覽顯示語法。node --version 必須保持在區塊內，底下的引用說明則在區塊外。若忘了結尾，之後整篇可能都變成等寬文字；修正的是少掉的分隔線，不是重裝 Markdown。檔案名稱或命令要保留半形符號，不要把反引號換成一般引號。

把 Markdown 程式碼框當成範例展示

在 notes.md 最後新增下列完整片段並儲存。這次外層四個反引號也是要存入檔案的內容；它把內層三個反引號當成普通文字展示。與前面直接呈現命令不同，讀者在預覽裡應看得見開頭的三個反引號及 sh，還有結尾的三個反引號，而最後一句仍是框外段落。這是GitHub 官方說明所示的巢狀寫法。

## Show the Markdown source

````markdown
```sh
node --version
```
````

This paragraph is outside the example.

若最後一句仍被包在程式碼框裡，先數外層結尾是否確實有四個反引號；三個不能結束四個開頭的框。只修結尾並重新預覽。要取消這項延伸練習，移除剛追加的整個章節，原有兩份文件與雙向連結保留。

步驟三：預覽、點連結與故障練習

在 VS Code 打開 README.md，使用命令面板的 Markdown: Open Preview；也可用 Windows／Linux 的 Ctrl＋Shift＋V，macOS 的 Command＋Shift＋V。原始碼與預覽是同一個檔案的兩種視圖，不是兩份獨立內容。先存檔，再確認主標題、工作步驟、兩項條件與命令區塊都有正確呈現。

快捷鍵可能被個人設定或擴充套件改過。若沒有開啟預覽，從命令面板查找 Markdown: Open Preview，查看該命令在本機顯示的按鍵或直接執行；不要改用另一個快捷鍵表猜測。未親自操作的作業系統仍標為依官方文件查證。

在預覽點 Open task notes，確認開啟的是同資料夾 notes.md，再從 Back to the notebook 回來。若工具在新編輯分頁開文件，重新對該檔開預覽即可；不要只看標題相同就當連結正確。接著故意將 README 的目的地改成 ./missing.md，存檔並點一次，預期無法找到目標；把路徑改回 ./notes.md 後再確認雙向都能走通。

如果想多練一次，先複製 README.md 作為備份，只刪除命令區塊的結尾反引號，觀察後面的引用如何被包含進去，再把分隔線補回並比對備份。不要在同一次練習同時改路徑、標題與結尾，否則不知道是哪個變動造成結果。這個小故障練習也適合用來學除錯流程。

步驟四：讓 Codex 讀取文件

用桌面版、CLI或IDE 擴充套件開啟 codex-md-lab，確認這個工作目錄，再送出下列要求。這次只讀檔與比較，不執行 README 中的命令。能看到一個檔名，不代表 Codex 已讀過內容；要求它引用具體檔案及尚未完成的檢查，才能核對理解是否正確。

Read README.md and notes.md in this practice folder. Explain the purpose, the accepted result, and the checks explicitly still pending. Identify each source file. Verify both relative file links point to existing files. Do not edit anything or execute the example command.

合格回答應說 README 記錄工作流程，notes 定義 Completed、範例 Read 與空白標題限制，而且瀏覽器檢查尚未執行。若它把 example command 說成已跑過，請要求更正並指出依據；文件裡有命令或成功條件，不等於實際執行紀錄。完成後保存這次讀取結果與你自己點通連結的確認。

一般 .md 與 AGENTS.md 的差別

本次沒有建立 AGENTS.md，因此不能聲稱 Codex 已自動載入這份規則。接著依AGENTS.md 專篇設定作用範圍與驗證，技能則看SKILL.md。Markdown 負責讓文件可讀，特定工具如何發現和使用檔案，是另一層規則。這個區分也能避免將別人的專案筆記直接當成你的操作指令。

完成時應有兩個真實 .md 檔、雙向可用連結、正確的程式碼區塊、修復過的一次缺檔或缺結尾故障，以及 Codex 能分開辨認已寫條件與未跑檢查的結果。預覽可能因工具樣式不同而有字型與間距差異，重點是結構、內容和目的地一致。本文查證 VS Code 官方預覽與連結文件；範例內容是原創，網站編譯與複製會另外核對內外層程式碼分隔，避免多語轉換改動樣本。

返回 Codex 教學總目錄

閱讀完整文字說明

Plain text to README.md to Preview

• AI 工具
• 教學
• Codex