О файлах README
Дополнительные сведения о предоставлении рекомендаций для проекта см. в статье "[AUTOTITLE" и "Настройка проекта для внесения действенных вкладов](/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)".
Файл README часто является первым объектом, который пользователь видит в репозитории. Файлы README обычно включают в себя следующие сведения:
- что делает проект;
- почему проект полезен;
- как пользователи могут приступить к работе с проектом;
- где пользователи могут получить помощь по проекту;
- кто поддерживает проект и вносит вклад в проект.
Если поместить файл README в скрытый каталог .github, корневой каталог или каталог docs, GitHub распознает и автоматически отобразит файл README для посетителей репозитория.
Если репозиторий содержит несколько файлов README, файл для отображения выбирается из расположений в следующем порядке: каталог .github, корневой каталог репозитория и, наконец, каталог docs.
При просмотре README на сайте GitHub все содержимое, превышающее 500 КиБ, будет усечено.
Если вы добавите файл README в корневой каталог общедоступного репозитория с тем же именем, что и имя пользователя, файл README будет автоматически отображаться на странице профиля. Можно изменить файл README профиля с помощью GitHub Flavored Markdown, чтобы создать персонализированный раздел профиля. Дополнительные сведения см. в разделе Управление файлом сведений о профиле.
Автоматическое оглавление для файлов README
Для просмотра любого файла Markdown в репозитории, включая файлы README, GitHub автоматически создаст оглавление на основе заголовков разделов. Вы можете просмотреть оглавление файла README, щелкнув значок меню в левом верхнем углу отрисовки страницы.
Ссылки на разделы в файлах README и на страницах BLOB-объектов
Вы можете связаться непосредственно с любым разделом с заголовком. Чтобы просмотреть автоматически созданную привязку в отрисованном файле, наведите указатель мыши на заголовок раздела, чтобы предоставить значок и щелкните значок, чтобы отобразить привязку в браузере.
Дополнительные сведения о ссылках на разделы см. в разделе "Ссылки разделов".
Относительные ссылки и пути к изображениям в файлах README
Вы можете определить относительные ссылки и пути к изображениям в отображаемых файлах, чтобы читателям было проще переходить к другим файлам в репозитории.
Относительная ссылка — это ссылка, заданная относительно текущего файла. Например, если есть файл сведений в корне репозитория и еще один файл в docs/CONTRIBUTING.md, относительная ссылка на CONTRIBUTING.md в файле сведений может выглядеть следующим образом:
[Contribution guidelines for this project](docs/CONTRIBUTING.md)
GitHub автоматически преобразует относительную ссылку или путь к изображению с учетом текущей ветви, чтобы ссылка или путь всегда работали. Путь ссылки будет относительным к текущему файлу. Ссылки, начинающиеся с /, будут относительными к корневому каталогу репозитория. Можно использовать любые операнды относительных ссылок, например ./ и ../.
Текст ссылки должен находиться в одной строке. Приведенный ниже пример не будет работать.
[Contribution
guidelines for this project](docs/CONTRIBUTING.md)
Относительные ссылки удобнее для пользователей, которые клонируют репозиторий. Абсолютные ссылки могут не работать в клонах репозитория. Мы рекомендуем использовать относительные ссылки на другие файлы в репозитории.
Вики-страницы
Файл README должен содержать только ту информацию, которая необходима разработчикам, чтобы приступить к использованию проекта и внести свой вклад в проект. Более длинную документацию удобнее размещать на вики-сайтах. Дополнительные сведения см. в разделе Сведения о вики-сайтах.