GitHub 上的 README 常会用到标题、清单与链接;写到项目待办、警告或较长的补充说明时,还有几种语法能让文档更容易读。这篇挑五种实用写法,附上可直接试的例子。
基础语法
先用一张表复习常见的基础语法:
| 功能 | 语法 | 示例 |
|---|---|---|
| 标题 | # 標題1, ## 標題2, ### 標題3 | # 標題1, ## 標題2, ### 標題3 |
| 粗体 | **文字** 或 __文字__ | **加粗文字** |
| 斜体 | *文字* 或 _文字_ | *斜體文字* |
| 删除线 | ~~文字~~ | ~~刪除文字~~ |
| 引用文本 | > 引用內容 | > 這是一段引用 |
| 单行程序 | `代码内容` | `print("Hello, World!")` |
| 多行程序 | ``` | print("多行代码") |
| 无序清单 | - 項目 或 * 項目 | - 無序1 或 * 無序2 |
| 有序清单 | 1. 項目 | 1. 有序1 2. 有序2 |
| 超链接 | [連結文字](網址) | [GitHub](https://github.com) |
| 分隔线 | --- 或 *** | --- 或 *** |
| 表情符号 | :表情代碼: | :smile:, :thumbsup: |
接下来的五种写法,适合需要清楚标示状态或补充脉络的文档。
一、任务列表
任务列表可以将事项规划、开发进度或待办事项以核取方框的形式呈现。
尤其在多人协作时,能够清楚显示目前完成与未完成的项目,方便追踪与分工。
写法示范
- [x] 完成專案初始設定
- [ ] 撰寫使用者需求文件
- [ ] 整合前後端程式碼
以上示例中,[x] 代表已完成,[ ] 代表尚未完成。
在 GitHub 的 Issues、Pull Requests 或 Discussions 里面,只要有人把某项工作核取完成,就能即时更新整个任务列表。
效果展示
- 完成项目初始设置
- 撰写用户需求文档
- 集成前后端代码
二、警告消息
警报可以在文档中呈现特殊的框线与图标,用以显示对读者来说「不可忽视」的重要消息。
此功能并非 Markdown 的原生语法,而是 GitHub 提供的扩充功能之一。
写法示范
GitHub 提供五种不同的警报类型,分别是 NOTE、TIP、IMPORTANT、WARNING 与 CAUTION。
> [!NOTE]
> Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
上述语法在 GitHub 上渲染后,就会呈现不同的底色与图标,以区分注解、重要说明与警告等内容。
如果有多行内容需要加入警报框,只要在每行前面加上 > 符号即可,例如:
> [!TIP]
> This is a tip.
>
> This is another tip.
效果展示
GitHub 的实际显示效果如下:
三、脚注
在写作长篇说明文档或论文式文本时,常需要加入参考来源或补充说明。
GitHub Markdown 提供了脚注功能,可在文档中以链接的方式调用补充信息,让文本保持整洁。
写法示范
在這個步驟中,會使用到特別的功能[^1]。
[^1]: 這裡可以寫更詳細的補充說明,也可以加入外部連結。
渲染后,文档正文中会有一个小型上标编号,读者点击后即可跳转到文档下方的详细注解。
效果展示
在这个步骤中,会使用到特别的功能1。(可以点开上标看看。)
四、转义字符
文档若要直接显示星号(*)、反引号(`)等 Markdown 指令符号,可使用「跳脱」(Escaping),避免它们被当成格式语法。
写法示范
如果要顯示 `*` 號記號,可在前面加上反斜線:\*
Let's rename \*our-new-project\* to \*our-old-project\*.
效果展示
如果要显示 * 号记号,可在前面加上反斜线:*
Let's rename *our-new-project* to *our-old-project*.
五、自订锚点
标题会自动生成锚点;若要连到特定段落或表格,可手动加入 HTML 锚点标签。
写法示范
-
连到标题:
[連到「腳註」的章節](#三腳註footnotes) -
连到自定义的段落:
<a name="my-custom-anchor"></a> 這裡是一個可從文件內部直接連過來的段落。 [連到自定義的段落](#my-custom-anchor)
无论是撰写技术文档或教学指南,善用锚点都能有效提升用户跳转阅读的效率。
效果展示
这里是一个可从文档内部直接连过来的段落。
结语
任务列表适合标示进度;警告框能让风险浮出来;脚注与锚点则让补充信息有地方可放。写 README 时,选真正有助阅读的语法即可,无须把每种效果都用上一遍。
参考数据
脚注
-
示范给脚注章节用的补充说明。 ↩
