GitHub 写作快速入门

通过为您的 GitHub 个人资料创建 README，学习高级排版功能。

谁可以使用此功能？

Markdown 可在 GitHub 网页界面中使用。

本文内容

简介

Markdown 是一种易读易写的语言，用于对纯文本进行格式化。您可以使用 Markdown 语法以及一些额外的 HTML 标签，在 GitHub 上的仓库 README、拉取请求和议题的评论等位置对撰写的内容进行格式化。在本指南中，您将通过创建或编辑 GitHub 个人资料的 README，学习一些高级排版功能。

如果您是 Markdown 新手，建议先阅读 基本写作和格式语法 或参加 使用 Markdown 进行沟通 GitHub Skills 课程。

如果您已经拥有个人资料 README，可以按照本指南向现有的 README 添加一些功能，或创建一个包含 Markdown 文件（如 about-me.md）的 gist。更多信息请参阅 创建 gist。

创建或编辑个人资料 README

您的个人资料 README 让您可以向 GitHub 社区分享关于自己的信息。README 会显示在个人资料页面的顶部。

如果您尚未拥有个人资料 README，可以添加一个。

  1. 创建一个与您的 GitHub 用户名相同的仓库，并在初始化时添加一个 README.md 文件。更多信息请参阅 管理个人资料 README。
  2. 编辑 README.md 文件，删除自动生成的模板文本（开头的 ### Hi there）。

如果您已有个人资料 README，可以从个人资料页面进行编辑。

  1. 在任意页面的右上角，点击您的头像，然后点击 您的个人资料。

  2. 点击在个人资料 README 旁边。

    Screenshot of @octocat's profile README. A pencil icon is outlined in dark orange.

添加图片以迎合访客

您可以在 GitHub 的交流中加入图片。此处，您将在个人资料 README 顶部添加一张响应式图片（如横幅）。

通过使用带有 prefers-color-scheme 媒体特性的 HTML <picture> 元素，您可以添加一张根据访客使用浅色或深色模式切换的图片。更多信息请参阅 管理主题设置。

  1. 将以下标记复制并粘贴到您的 README.md 文件中。

    HTML
    <picture>
 <source media="(prefers-color-scheme: dark)" srcset="YOUR-DARKMODE-IMAGE">
 <source media="(prefers-color-scheme: light)" srcset="YOUR-LIGHTMODE-IMAGE">
 <img alt="YOUR-ALT-TEXT" src="YOUR-DEFAULT-IMAGE">
</picture>

  2. 将标记中的占位符替换为您选择的图片 URL。或者，若想先试用此功能，可直接复制下面示例中的 URL。

    • 将 YOUR-DARKMODE-IMAGE 替换为在深色模式访客看到的图片 URL。
    • 将 YOUR-LIGHTMODE-IMAGE 替换为在浅色模式访客看到的图片 URL。
    • 将 YOUR-DEFAULT-IMAGE 替换为当其他图片均不匹配时显示的图片 URL，例如访客使用不支持 prefers-color-scheme 功能的浏览器时。

  3. 为使用屏幕阅读器的访客提供可访问性，请将 YOUR-ALT-TEXT 替换为图片的描述。

  4. 要检查图片是否正确渲染，请点击 预览 选项卡。

欲了解在 Markdown 中使用图片的更多信息，请参阅 基本写作和格式语法。

响应式图片示例

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/25423296/163456776-7f95b81a-f1ed-45f7-b7ab-8fa810d529fa.png">
  <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
  <img alt="Shows an illustrated sun in light mode and a moon with stars in dark mode." src="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
</picture>

图片呈现效果

Screenshot of the "Preview" tab of a GitHub comment, in light mode. An image of a smiling sun fills the box.

添加表格

您可以使用 Markdown 表格来组织信息。在此，您将通过对某些内容进行排名（例如最常使用的编程语言或框架、正在学习的内容或最喜欢的爱好）来介绍自己。当表格列包含数字时，使用表头下方的 --: 语法可实现右对齐。

  1. 返回 编辑文件 选项卡。

  2. 要介绍自己，请在 </picture> 标签下方两行添加一个 ## About me 标题以及关于自己的简短段落，如下所示。

    ## About me

Hi, I'm Mona. You might recognize me as GitHub's mascot.

  3. 在此段落下方两行，复制粘贴以下标记插入表格。

    Markdown
    | Rank | THING-TO-RANK |
|-----:|---------------|
|     1|               |
|     2|               |
|     3|               |

  4. 在右侧列中，将 THING-TO-RANK 替换为 “Languages”、 “Hobbies” 或其他任意内容，并在该列中填写您的列表。

  5. 要检查表格是否正确渲染，请点击 预览 选项卡。

欲了解更多信息，请参阅 使用表格组织信息。

表格示例

## About me

Hi, I'm Mona. You might recognize me as GitHub's mascot.

| Rank | Languages |
|-----:|-----------|
|     1| JavaScript|
|     2| Python    |
|     3| SQL       |

表格呈现效果

Screenshot of the "Preview" tab of a GitHub comment. Under the "About me" heading is a rendered table with a ranked list of languages.

添加可折叠部分

为保持内容整洁，您可以使用 <details> 标签创建可展开的折叠部分。

  1. 要为您创建的表格添加折叠部分，请像下面示例一样将表格包裹在 <details> 标签中。

    HTML
    <details>
<summary>My top THINGS-TO-RANK</summary>

YOUR TABLE

</details>

  2. 在 <summary> 标签之间，将 THINGS-TO-RANK 替换为您在表格中排名的内容。

  3. 如需默认展开该部分，可在 <details> 标签中添加 open 属性。

    <details open>

  4. 要检查折叠部分是否正确渲染，请点击 预览 选项卡。

折叠部分示例

<details>
<summary>My top languages</summary>

| Rank | Languages |
|-----:|-----------|
|     1| JavaScript|
|     2| Python    |
|     3| SQL       |

</details>

折叠部分呈现效果

Screenshot of the "Preview" tab of a comment. To the left of the words "Top languages" is an arrow indicating that the section can be expanded.

添加引用

Markdown 还提供了许多其他内容格式化选项。在此，您将添加水平分割线以划分页面，并使用块引用来格式化您喜爱的引用。

  1. 在文件底部、</details> 标签下方两行处，输入三个或更多连字符来添加水平分割线。

    ---

  2. 在 --- 行下方，输入如下标记添加引用。

    > QUOTE

    将 QUOTE 替换为您选择的引用内容。或者，直接复制下面示例中的引用。

  3. 要检查所有内容是否正确渲染，请点击 预览 选项卡。

引用示例

---
> If we pull together and commit ourselves, then we can push through anything.

— Mona the Octocat

引用呈现效果

Screenshot of the "Preview" tab of a GitHub comment. A quote is indented below a thick horizontal line.

添加注释

您可以使用 HTML 注释语法添加在输出中隐藏的注释。此处，您将添加一个注释，以提醒自己稍后更新 README。

  1. 在 ## About me 标题下方两行，使用以下标记插入注释。

    <!-- COMMENT -->

    将 COMMENT 替换为您提醒自己稍后要完成的 “待办” 项目（例如，向表格添加更多条目）。

  2. 要检查您的注释是否在输出中隐藏，请点击 预览 选项卡。

注释示例

## About me

<!-- TO DO: add more details about me later -->

保存您的工作

当您对更改满意后，点击 提交更改 来保存您的个人资料 README。

直接提交到 main 分支会让您的更改对所有访客可见。如果您想保存工作但尚未准备好公开，可选择 为此提交创建新分支并发起拉取请求。

后续步骤

© . This site is unofficial and not affiliated with GitHub, Inc.