在 GitHub 上写作的快速入门

通过为你的 GitHub 个人资料创建自述文件来学习高级格式化功能。

本文内容

简介

Markdown 是一种易于阅读、易于书写的纯文本格式化语言。你可以使用 Markdown 语法以及一些额外的 HTML 标签，在 GitHub 上格式化你的写作，例如存储库自述文件以及对拉取请求和问题的评论。在本指南中，你将通过创建或编辑你的 GitHub 个人资料自述文件来学习一些高级格式化功能。

如果你不熟悉 Markdown，你可能需要从“基本写作和格式化语法”或 使用 Markdown 进行交流 GitHub 技能课程开始。

如果你已经有一个个人资料自述文件，你可以通过向现有自述文件添加一些功能或创建一个名为 about-me.md 的 Markdown 文件的 gist 来遵循本指南。有关更多信息，请参阅“创建 gist”。

创建或编辑你的个人资料自述文件

您的个人资料自述文件让您能够与 GitHub.com 上的社区分享有关您自己的信息。自述文件显示在您的个人资料页面的顶部。

如果您还没有个人资料自述文件，可以添加一个。

  1. 创建一个与您的 GitHub 用户名同名的存储库，使用 README.md 文件初始化存储库。有关详细信息，请参阅“管理您的个人资料自述文件”。
  2. 编辑 README.md 文件并删除创建文件时自动添加的模板文本（以 ### Hi there 开头）。

如果您已有个人资料自述文件，则可以从您的个人资料页面进行编辑。

  1. 在任何 GitHub 页面的右上角，单击您的个人资料照片，然后单击您的个人资料。

  2. 单击 在您的个人资料自述文件的旁边。

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

添加适合您访客的图片

您可以在 GitHub 上的通信中包含图片。在这里，您将向个人资料自述文件的顶部添加一个响应式图片，例如横幅。

通过将 HTML <picture> 元素与 prefers-color-scheme 媒体功能结合使用，您可以添加一张图片，该图片会根据访客使用的是浅色模式还是深色模式而改变。有关详细信息，请参阅“管理您的主题设置”。

  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。

    • 用要为使用深色模式的访客显示的图片的 URL 替换 YOUR-DARKMODE-IMAGE。
    • 用要为使用浅色模式的访客显示的图片的 URL 替换 YOUR-LIGHTMODE-IMAGE。
    • 用要显示的图片的 URL 替换 YOUR-DEFAULT-IMAGE，以防无法匹配其他图片，例如，如果访客使用的是不支持 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

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 替换为“语言”、“爱好”或其他任何内容，并在列中填写你的内容列表。

  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. 或者，若要使该部分默认显示为打开状态，请将 open 属性添加到 <details> 标记。

    <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 分支将使你的更改对个人资料上的任何访问者可见。如果你想保存你的工作，但尚未准备好让它在个人资料上可见，你可以选择为此提交创建一个新分支并启动一个请求合并。

后续步骤