关于自述文件

您可以将自述文件添加到仓库，告知其他人您的项目为什么有用，他们可以对您的项目做什么，以及他们可以如何使用。

本文内容

关于自述文件

您可以将 README 文件添加到仓库来交流有关您项目的重要信息。 自述文件以及存储库许可证、引文文件、贡献指南、行为准则传达了对项目的期望，并有助于管理贡献。

有关为项目提供指南的详细信息，请参阅“为项目添加行为准则”和“设置项目的健康贡献”。

自述文件通常是访问者在访问仓库时看到的第一个项目。 自述文件通常包含以下信息：

  • 项目做什么
  • 项目为什么有用
  • 用户如何使用项目
  • 用户能从何处获取项目的帮助
  • 谁维护和参与项目

如果将自述文件放在存储库隐藏的 .github 目录、根目录或 docs 目录中，GitHub 将识别自述文件并自动向存储库访问者显示。

如果存储库包含多个自述文件，则按以下顺序从各位置中选择显示的文件：.github 目录，然后是存储库的根目录，最后是 docs 目录。

在 GitHub 上查看 README 时，任何超过 500 KiB 的内容都会被截断。

如果将 README 文件添加到与用户名同名的公共仓库的根目录，则该 README 将自动显示在您的个人资料页面上。 您可以使用 GitHub Flavored Markdown 编辑您的个人资料以在您的个人资料 README，以在您的个人资料上创建个性化的区域。 有关详细信息，请参阅“管理个人资料自述文件”。

为 README 文件自动生成的目录

对于仓库中任何 Markdown 文件（包括 README 文件）的视图，GitHub 将自动生成基于章节标题的目录。 你可以通过单击渲染页面左上侧的 菜单图标来查看自述文件的目录。

存储库的自述文件的屏幕截图。 在左上角，展开了一个标有列表图标的下拉菜单以显示目录。

可以直接链接到具有标题的任何章节。 若要查看呈现文件中自动生成的定位点，请将鼠标悬停在章节标题上方以显示 图标，然后单击图标以在浏览器中显示定位点。

存储库的自述文件的屏幕截图。 在部分标题的左侧，链接图标以深橙色标出。

有关章节链接的更多详细信息，请参阅“章节链接”。

您可以在渲染的文件中定义相对链接和图像路径，以帮助读者导航到仓库中的其他文件。

相对链接是相对于当前文件的链接。 例如，如果在仓库根目录下有一个自述文件，而在 docs/CONTRIBUTING.md 中有另一个文件，则自述文件中的 CONTRIBUTING.md 的相关链接如下所示 ：

[Contribution guidelines for this project](docs/CONTRIBUTING.md)

GitHub 将根据您当前使用的分支自动转换相对链接或图像路径，从而使链接或路径始终有效。 链接的路径将相对于当前文件。 以 / 开头的链接将相对于存储库根目录。 可使用所有相对链接操作数，例如 ./ 和 ../。

链接文本应位于一行上。 下面的示例将不起作用。

[Contribution 
guidelines for this project](docs/CONTRIBUTING.md)

相对链接更便于用户克隆仓库。 绝对链接可能无法用于仓库的克隆 - 建议使用相对链接引用仓库中的其他文件。

Wiki

自述文件应仅包含开发人员开始使用和参与项目的必要信息。 较长的文档最适合维基。 有关详细信息，请参阅“关于 wikis”。

延伸阅读