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