登录
返回训练营在 GitHub 上查看

使用 Markdown 进行沟通

Markdown 是一种轻量级纯文本标记语言。在 GitHub 上，Markdown 几乎无处不在，它被用来编写文档、表达想法、发表评论。

这是一个交互式课程，需要在 GitHub 上实际操作来完成学习。本页面为静态预览，仅方便您一次性阅读所有步骤内容。

前往 GitHub 开始学习 →

📖课程概览

English | 中文

本课程翻译自 Github Skills，全部课程请点击 这里查看

使用 Markdown 进行沟通

Markdown 是一种轻量级纯文本标记语言。在 GitHub 上，Markdown 几乎无处不在，它被用来编写文档、表达想法、发表评论。

欢迎

GitHub 不仅仅是一个代码托管平台，更是一个开发者协作与交流的重要社区。 Markdown 作为一种轻量级标记语言，具备易读、易写的特点，能够帮助开发者在 GitHub 中更清晰地表达想法、发表评论以及编写文档。

本课程将带你逐步掌握 Markdown 的常见用法，包括如何更清晰地组织标题结构、使用列表梳理思路、通过任务清单追踪进度，甚至还能借助表情符号、图片和链接，让内容表达更加生动直观。

  • 目标人群: 初级开发者，GitHub 新用户和学生
  • 学习内容: 掌握在评论或文本文件中使用 Markdown 添加列表、图片与链接的方法
  • 您将完成：对一个纯文本文件使用 Markdown 格式重写，并可基于该文件进一步搭建个人 GitHub Pages 页面
  • 先决条件：课程中会涉及 pull request 和文件编辑。如果你对这些还不熟悉，建议先学习 GitHub 入门课程！
  • 学习时长：不到一个小时

在本课程中，你将完成以下任务：

  1. 添加标题
  2. 插入图片
  3. 编写代码示例
  4. 创建任务清单
  5. 合并你的 pull request

如何开始课程

点击下方的 COPY EXERCISE 按钮，将练习代码复制到你的账号下。 仓库创建完毕后，请给你亲爱的小猫咪（Mona，GitHub吉祥物）约20秒时间来你准备第一节课内容，然后刷新页面即可。

遇到问题？ 🤷

复制练习时，我们建议使用以下设置：

如果 20 秒后练习仍未准备好，请查看 Actions tab 页。

  • 检查是否有作业(job)正在运行，有时可能需要更长时间。

  • 如果页面显示作业失败，请提交 issue。太好了，你发现了一个 Bug！🐛

© 2025 GitHub • Code of Conduct • MIT License

🎯课程步骤

GitHub

步骤 1: 添加标题

什么是 Markdown？ Markdown 是 GitHub 使用的一种轻量级文本标记语言。 通过它，你可以对文本进行格式化处理，例如插入标题、列表、加粗、斜体、表格以及其他样式。在 GitHub 的许多场景中都可以使用 Markdown，例如：

什么是 标题 ? 标题是用来标识某一部分内容主题的较大字号文本，和我们常用的 Word 类似一共分为六级。

示例

# 这是 `<h1>` 一级标题，字号最大

## 这是 `<h2>` 二级标题

###### 这是 `<h6>` 六级标题，字号最小

这是 <h1> 一级标题，字号最大

这是 <h2> 二级标题

这是 <h6> 六级标题，字号最小

⌨️ 实操环节: 创建 Markdown 文件

  1. 打开一个新的浏览器标签页，并在另一个标签页中边阅读说明边完成操作。

  2. 在顶部导航栏中选择 Code（代码） tab页。

  3. 创建一个新分支，名称如下：

    start-blog

  4. 在文件列表上方，点击 Add file（添加文件） 按钮，并选择 Create new file（创建新文件）。

  5. 输入文件名：

    day-1.md

  6. 在编辑器第一行使用一级标题，为页面添加标题：

    # Daily Learning

  7. 添加两个二级标题，用于区分不同的博客内容：

    ## Morning Planning

## Review

  8. 点击编辑器上方的 Preview（预览），查看渲染效果。

  9. 在右上角点击 Commit changes（提交更改），并直接提交到 start-blog 分支。

  10. 完成标题创建并提交后，Mona 会开始检查你的内容，并准备下一步任务。

遇到问题? 🤷
  • 确认当前编辑的文件和分支是否正确。
  • 仔细检查你的语法。# 和第一个单词之间必须有一个空格。
GitHub

步骤 2: 创建列表

Markdown 支持 3 种常见列表类型：

无序列表

无序列表用于展示不强调顺序的条目，每一项前面使用 -、* 或 + 即可。

- Item 1
- Item 2
- Item 3
  • Item 1
  • Item 2
  • Item 3

有序列表

有序列表用于表示有顺序的步骤或流程。只需使用数字编号即可，Markdown 会自动帮你处理排序。

1. Step 1
1. Step 2
1. Step 3
  1. Step 1
  2. Step 2
  3. Step 3

任务列表

任务列表是在无序列表基础上扩展而来的，用于表示任务进度。

  • 使用 [ ] 表示未完成任务
  • 使用 [x] 表示已完成任务

注意：中括号内部需要有一个空格（未完成状态）

- [x] This task is complete
- [ ] This task is not complete
  • This task is complete
  • This task is not complete

[!TIP] 在 Issue 和 Pull Request 中，也可以使用任务列表语法来直观展示进度。

⌨️ 实操环节: 为晨间计划添加目标

  1. 在 start-blog 分支中，打开 day-1.md 文件进行编辑。

  2. 在 Morning Planning（二级标题） 下方添加以下任务清单，用于记录当天目标：

- [ ] 查看 [GitHub Blog](https://github.blog/) 获取选题灵感  
- [ ] 学习 [GitHub Pages](https://skills.github.com/#first-day-on-github) 的使用方法  
- [ ] 将我的第一篇博客转换为网页形式

  1. 切换到 Preview（预览） 标签页，检查 Markdown 是否正确渲染。

  2. 点击右上角 Commit changes（提交更改），并直接提交到 start-blog 分支。

  3. 提交完成后，Mona 会继续为你准备下一步内容。

遇到问题? 🤷
  • 确认当前编辑的文件和分支是否正确。
  • 请仔细检查语法。对于任务列表，[ ] 内部必须包含一个空格。
GitHub

步骤 3: 添加代码示例

接下来，我们来学习如何使用 代码块（code blocks） 以及如何根据不同编程语言实现语法高亮。

[!TIP] Markdown 支持多种编程语言的语法高亮效果，你也可以尝试其他语言类型看看显示效果。

示例：终端命令

```bash
git clone https://github.com/skills/communicate-using-markdown
```

git clone https://github.com/skills/communicate-using-markdown

示例: Javascript 代码

```js
var myVar = "Hello, world!";
```

var myVar = "Hello, world!";

⌨️ 实操环节

  1. 切换到 start-blog 分支，并打开 day-1.md 文件进行编辑。

  2. 在二级标题 Review 下方，添加以下内容，用来记录你刚从 GitHub Blog 学到的一段实用代码。

    使用 [ffmpeg](https://www.ffmpeg.org) 将图片或视频从深色模式转换为浅色模式

```bash
ffmpeg -i input.mp4 -vf "negate,hue=h=180,eq=contrast=1.2:saturation=1.1" output.mp4
```

  3. 点击 Preview（预览） 标签页，检查 Markdown 的显示效果是否正确。

  4. 在页面右上角点击 Commit changes（提交更改），并直接提交到 start-blog 分支。

  5. 提交完成后，Mona 会开始检查你的内容，并为下一步课程做好准备。

遇到问题？🤷
  • 确认当前编辑的文件和分支是否正确。
  • 注意代码块语法：使用的是三个反引号 ```，而不是三个单引号 '''
GitHub

步骤 4: 添加图片

接下来我们学习如何在 Markdown 中插入图片，包括使用相对路径、绝对路径、图片尺寸控制，以及基础排版方式。

常规 Markdown

在 Markdown 中，可以通过相对路径（仓库内文件）或绝对路径（图片外接）来插入图片。

图片方括号中的说明文字（alt 文本）在图片无法加载时会显示，同时也会被屏幕阅读器读取，用于提升可访问性。

注意：Markdown 本身不支持直接调整图片大小。

示例

使用仓库内相对路径插入图片：

![Mona the Octocat](https://raw.githubusercontent.com/gitcn-org/communicate-using-markdown/main/.github/steps/myrepo/original.png)

使用外部URL，绝对路径接插入图片：

![Mona the Octocat](https://octodex.github.com/images/original.png)
Mona the Octocat

HTML 写法

在实际使用中，经常需要控制图片大小或排版（比如和文字并排）。这时可以使用 HTML 语法获得更高的灵活性。

  • alt：图片无法显示时的替代文本
  • src：图片来源地址
  • width / height：控制尺寸（像素）
  • align：控制对齐方式（left / right）
<img alt="Mona the Octocat" src="https://octodex.github.com/images/original.png"
width="200" align="right">

⌨️ 实操环节

目前我们的博客还比较简单，这一步我们来加一点视觉元素，让页面更生动。

  1. 在 start-blog 分支中，打开 day-1.md 文件进行编辑。

  2. 在 Morning Planning（二级标题） 下方插入一张图片：

    ![Cloudy morning](https://octodex.github.com/images/cloud.jpg)

  3. 切换到 Preview（预览），检查效果。

    • 注意：图片尺寸偏大，不太适合当前布局。

  4. 将其替换为 HTML 版本，并控制大小与位置：

    <img alt="Cloudy morning" src="https://octodex.github.com/images/cloud.jpg" width="100" align="right">

  5. 点击右上角 Commit changes（提交更改），并直接提交到 start-blog 分支。

  6. 提交完成后，Mona 会继续检查你的内容，并准备下一步学习任务。

遇到问题? 🤷
  • 请确认当前编辑的文件和分支是否正确
  • 请仔细检查你的语法。HTML 图片标签必须以 img 开头，并包含 src 属性。
GitHub

步骤 5: 完成任务

现在，我们的第一篇博客内容已经完成，接下来将它合并到 main 主分支中。

⌨️ 实操练习: 合并博客内容

  1. 在顶部导航栏中，点击 Pull requests 标签页。

  2. 创建一个新的 Pull Request，并设置：

    • 基础分支（base）：main
    • 对比分支（compare）：start-blog

  3. （可选）为此次 Pull Request 填写一个清晰的标题和描述。

  4. 向下滚动页面，点击 Merge 按钮。

  5. 接着点击 Merge pull request，完成合并。

  6. Pull Request 合并完成后，Mona 会开始准备最后的检查工作。干得漂亮！你已经完成本课程啦！🎉

GitHub

课程回顾

celebrate

恭喜你完成本次练习！

下面简单回顾一下你在本次练习中完成的内容：

  1. 你添加了标题，用来更好地组织内容结构。
  2. 你创建了任务清单，用来规划和跟踪待办事项。
  3. 你在 Review 部分保存了一段代码示例，方便后续参考。
  4. 你在计划中插入了图片，让内容更直观、更生动。
  5. 最后，你用 Markdown 语法完成了一篇完整的博客内容。

接下来可以做什么?

步骤导航

关于 GitHub Skills

GitHub Skills 是 GitHub 官方提供的交互式学习平台。 原始课程需要在 GitHub 上执行操作，通过 GitHub Actions 自动检测进度。

本页面将所有步骤展示在一个页面中，方便您一次性阅读全部内容。

前往 GitHub 实操练习