关于自述文件

关于自述文件

您可以将 README 文件添加到仓库来交流有关您项目的重要信息。 README 连同仓库许可 和参与指南，用于传达项目的要求，并且帮助您管理参与。

有关为项目提供指南的更多信息，请参阅 “设置健康参与的项目”。

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

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

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

为 README 文件自动生成的目录

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

自动生成的目录默认对仓库中所有 Markdown 文件启用，但您可以对您的仓库禁用此功能。

1. 在 GitHub Enterprise Server 上，导航到仓库的主页面。
2. 在仓库名称下，单击 Settings（设置）。
3. 在“Features（功能）”下，取消选择 Table of contents（目录）。

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

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

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

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

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

[此项目的参与指南](docs/CONTRIBUTING.md)

GitHub Enterprise Server 将根据您当前使用的分支自动转换相对链接或图像路径，从而使链接或路径始终有效。 您可以使用所有相对链接操作符，如 ./ 和 ../。

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

延伸阅读

• "添加文件到仓库"
• 18F 的“将自述文件设为可读”