有关在 GitHub 上编写的快速入门

通过为你的 GitHub 个人资料创建自述文件，了解高级格式设置功能。

谁可以使用此功能？

Markdown 可用于 GitHub Web 界面。

本文内容

简介

Markdown 是一种易于读取和编写的语言，用于设置纯文本格式。可以使用 Markdown 语法以及一些其他 HTML 标记来格式化位于存储库 README 以及有关拉取请求和问题的注释等位置的 GitHub 上的写入内容。 在本指南中，你将通过为你的 GitHub 个人资料创建自述文件来了解一些高级格式设置功能。

如果不熟悉 Markdown，可能需要通过“基本撰写和格式语法”或使用 Markdown 进行通信 GitHub Skills 课程入门。

如果已有个人资料自述文件，则可以按照本指南向现有自述文件添加一些功能，或者使用名为 about-me.md 之类的 Markdown 文件创建一个 gist。 有关详细信息，请参阅“创建 Gist”。

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

可以通过个人资料自述文件，在 GitHub 上与社区分享有关你自己的信息。 自述文件显示在个人资料页面的顶部。

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

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

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

  1. 在任意 GitHub Enterprise Server 页面的右上角，单击个人资料照片，然后单击“你的个人资料”。

  2. 单击个人资料 README 旁边的 。

    @octocat 的个人资料 README 的屏幕截图。 铅笔图标用深橙色框标出。

添加适合访问者的图像

可以在 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。

    • 将 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>

图像的外观

屏幕截图显示浅色模式下 GitHub 注释的“预览”选项卡。 一张微笑的太阳的图像填满了整个框。

添加表

可以使用 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 替换为“语言”、“爱好”或其他任何内容，然后在列中填写内容清单。

  5. 若要检查表格是否已正确呈现，请单击“预览”选项卡。

有关详细信息，请参阅“使用表格组织信息”。

表示例

## About me

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

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

表的外观

屏幕截图显示 GitHub 注释的“预览”选项卡。 “关于我”标题下是包含语言排名列表的呈现表。

创建折叠部分

若要使内容保持整洁，可以使用 <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>

折叠部分的外观

注释的“预览”选项卡的屏幕截图。 “热门语言”这几个字的左侧是一个箭头，指示该部分可以展开。

添加引文

Markdown 具有许多其他用于设置内容格式的选项。 在这里，你将添加一条水平线来分割页面，并添加一个块引用块来格式化你喜欢的引文。

  1. 在文件底部，在 </details> 标记下方两行处，通过键入三条或更多短划线来添加水平线。

    ---

  2. 在 --- 行下方，通过键入如下所示的标记来添加引文。

    > QUOTE

    将 QUOTE 替换为所选引文。 或者，请从以下示例中复制引文。

  3. 若要检查所有内容是否已正确呈现，请单击“预览”选项卡。

引用示例

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

— Mona the Octocat

引用的外观

屏幕截图显示 GitHub 注释的“预览”选项卡。 引号在粗横线下方缩进。

添加注释

可以使用 HTML 注释语法添加将在输出中隐藏的注释。 在这里，你将添加注释，以提醒自己稍后更新自述文件。

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

    <!-- COMMENT -->

    将 COMMENT 替换为“待办事项”项目，提醒自己稍后执行某些操作（例如，向表中添加更多项）。

  2. 若要检查注释是否在输出中隐藏，请单击“预览”选项卡。

注释示例

## About me

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

保存工作

如果对更改感到满意，请单击“提交更改”**** 以保存你的个人资料自述文件。

直接提交到 main 分支将使你的更改对个人资料上的任何访问者可见。 如果要保存工作，但尚未准备好使其在个人资料中可见，可以选择“为此提交创建新分支并启动拉取请求”。

后续步骤

  • 继续了解高级格式设置功能。 例如，请参阅“创建和突显代码块”。
  • 在问题、拉取请求和讨论中跨 GitHub 进行沟通时，请使用新技能。 有关详细信息，请参阅“在 GitHub 上通信”。