返回博客
一般文章

好用的 github markdown 语法

挑五种 GitHub Markdown 实用语法,让 README 的进度、警告和补充说明更好读。

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。

markdown
> [!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 上渲染后,就会呈现不同的底色与图标,以区分注解、重要说明与警告等内容。

如果有多行内容需要加入警报框,只要在每行前面加上 > 符号即可,例如:

markdown
> [!TIP]
> This is a tip.
>
> This is another tip.

效果展示

GitHub 的实际显示效果如下:

三、脚注

在写作长篇说明文档或论文式文本时,常需要加入参考来源或补充说明。

GitHub Markdown 提供了脚注功能,可在文档中以链接的方式调用补充信息,让文本保持整洁。

写法示范

markdown
在這個步驟中,會使用到特別的功能[^1]。

[^1]: 這裡可以寫更詳細的補充說明,也可以加入外部連結。

渲染后,文档正文中会有一个小型上标编号,读者点击后即可跳转到文档下方的详细注解。

效果展示

在这个步骤中,会使用到特别的功能1。(可以点开上标看看。)

四、转义字符

文档若要直接显示星号(*)、反引号(`)等 Markdown 指令符号,可使用「跳脱」(Escaping),避免它们被当成格式语法。

写法示范

markdown
如果要顯示 `*` 號記號,可在前面加上反斜線:\*

Let's rename \*our-new-project\* to \*our-old-project\*.

效果展示

如果要显示 * 号记号,可在前面加上反斜线:*

Let's rename *our-new-project* to *our-old-project*.

五、自订锚点

标题会自动生成锚点;若要连到特定段落或表格,可手动加入 HTML 锚点标签。

写法示范

  1. 连到标题:

    markdown
    [連到「腳註」的章節](#三腳註footnotes)
    
  2. 连到自定义的段落:

    markdown
    <a name="my-custom-anchor"></a>
    這裡是一個可從文件內部直接連過來的段落。
    
    [連到自定義的段落](#my-custom-anchor)
    

无论是撰写技术文档或教学指南,善用锚点都能有效提升用户跳转阅读的效率。

效果展示

点我,连到「脚注」的章节


这里是一个可从文档内部直接连过来的段落。

结语

任务列表适合标示进度;警告框能让风险浮出来;脚注与锚点则让补充信息有地方可放。写 README 时,选真正有助阅读的语法即可,无须把每种效果都用上一遍。

参考数据

脚注

  1. 示范给脚注章节用的补充说明。 ↩