О файлах README

Можно добавить файл сведений в репозиторий, чтобы сообщить другим людям, чем полезен проект, что они могут с ним делать и как его использовать.

В этой статье

О файлах README

Дополнительные сведения о предоставлении рекомендаций для проекта см. в статье "[AUTOTITLE" и "Настройка проекта для внесения действенных вкладов](/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)".

Файл README часто является первым объектом, который пользователь видит в репозитории. Файлы README обычно включают в себя следующие сведения:

  • что делает проект;
  • почему проект полезен;
  • как пользователи могут приступить к работе с проектом;
  • где пользователи могут получить помощь по проекту;
  • кто поддерживает проект и вносит вклад в проект.

Если поместить файл README в скрытый каталог .github, корневой каталог или каталог docs, GitHub Enterprise Cloud распознает и автоматически отобразит файл README для посетителей репозитория.

Если репозиторий содержит несколько файлов README, файл для отображения выбирается из расположений в следующем порядке: каталог .github, корневой каталог репозитория и, наконец, каталог docs.

Если вы добавите файл README в корневой каталог общедоступного репозитория с тем же именем, что и имя пользователя, файл README будет автоматически отображаться на странице профиля. Можно изменить файл README профиля с помощью GitHub Flavored Markdown, чтобы создать персонализированный раздел профиля. Дополнительные сведения см. в разделе Управление файлом сведений о профиле.

Автоматическое оглавление для файлов README

Для просмотра любого файла Markdown в репозитории, включая файлы README, GitHub Enterprise Cloud автоматически создаст оглавление на основе заголовков разделов. Вы можете просмотреть оглавление файла README, щелкнув значок меню в левом верхнем углу отрисовки страницы.

Снимок экрана: README для репозитория. В левом верхнем углу раскрывающееся меню, помеченное значком списка, разворачивается, чтобы отобразить оглавление.

Вы можете связаться непосредственно с разделом в отрисованном файле, наведите указатель мыши на заголовок раздела, чтобы предоставить .

Снимок экрана: README для репозитория. Слева от заголовка раздела значок ссылки описан в темно-оранжевый.

Вы можете определить относительные ссылки и пути к изображениям в отображаемых файлах, чтобы читателям было проще переходить к другим файлам в репозитории.

Относительная ссылка — это ссылка, заданная относительно текущего файла. Например, если есть файл сведений в корне репозитория и еще один файл в docs/CONTRIBUTING.md, относительная ссылка на CONTRIBUTING.md в файле сведений может выглядеть следующим образом:

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

GitHub Enterprise Cloud автоматически преобразует относительную ссылку или путь к изображению с учетом текущей ветви, чтобы ссылка или путь всегда работали. Путь ссылки будет относительным к текущему файлу. Ссылки, начинающиеся с /, будут относительными к корневому каталогу репозитория. Можно использовать любые операнды относительных ссылок, например ./ и ../.

Текст ссылки должен находиться в одной строке. Приведенный ниже пример не будет работать.

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

Относительные ссылки удобнее для пользователей, которые клонируют репозиторий. Абсолютные ссылки могут не работать в клонах репозитория. Мы рекомендуем использовать относительные ссылки на другие файлы в репозитории.

Вики-страницы

Файл README должен содержать только ту информацию, которая необходима разработчикам, чтобы приступить к использованию проекта и внести свой вклад в проект. Более длинную документацию удобнее размещать на вики-сайтах. Дополнительные сведения см. в разделе Сведения о вики-сайтах.

Дополнительные материалы