Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
GitHub AE is currently under limited release.

关于自述文件

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

关于自述文件

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

有关为项目提供指南的详细信息,请参阅“设置健康贡献的项目”。

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

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

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

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

Github/scientist 仓库的主页面及其自述文件

用户名/用户名仓库上的自述文件

为 README 文件自动生成的目录

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

自动生成目录的自述文件

自述文件和 blob 页面中的章节链接

您可以直接链接到渲染文件中的某个部分,方法是将鼠标悬停在该部分标题上以显示链接:

github/scientiorist 仓库的自述文件中的部分链接

自述文件中的相对链接和图像路径

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

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

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

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

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

Wiki

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

延伸阅读