О файлах README
Дополнительные сведения о предоставлении рекомендаций для проекта см. в статье [AUTOTITLE и Добавление правил поведения в проект](/communities/setting-up-your-project-for-healthy-contributions).
Файл README часто является первым объектом, который пользователь видит в репозитории. Файлы README обычно включают в себя следующие сведения:
- что делает проект;
- почему проект полезен;
- как пользователи могут приступить к работе с проектом;
- где пользователи могут получить помощь по проекту;
- кто поддерживает проект и вносит вклад в проект.
Если вы помещаете файл README в скрытый .github, корневой каталог или docs каталог репозитория, GitHub распознает и автоматически обнажите приложение README для посетителей репозитория.
Если репозиторий содержит несколько файлов README, файл для отображения выбирается из расположений в следующем порядке: каталог .github, корневой каталог репозитория и, наконец, каталог docs.
Когда ваш README просматривается на GitHub, любой контент свыше 500 KiB будет урезан.
Если вы добавите файл README в корневой каталог общедоступного репозитория с тем же именем, что и имя пользователя, файл README будет автоматически отображаться на странице профиля. Можно изменить файл README профиля с помощью GitHub Flavored Markdown, чтобы создать персонализированный раздел профиля. Дополнительные сведения см. в разделе Управление файлом сведений о профиле.
Автоматическое создание оглавления для файлов markdown
Для отрисованного представления любого файла Markdown в репозитории, включая файлы README, GitHub автоматически создает оглавление на основе заголовков разделов. Вы можете просмотреть оглавление файла README, нажав на значок меню «Outline» в верхнем углу отрисованной страницы.
Ссылки на разделы в файлах Markdown и страницах BLOB-объектов
Вы можете связаться непосредственно с любым разделом с заголовком. Чтобы просмотреть автоматически созданную привязку в отрисованном файле, наведите указатель мыши на заголовок раздела, чтобы предоставить значок и щелкните значок, чтобы отобразить привязку в браузере.
Дополнительные сведения о ссылках на разделы см . по ссылкам раздела.
Относительные ссылки и пути изображений в файлах Markdown
Вы можете определить относительные ссылки и пути к изображениям в отображаемых файлах, чтобы читателям было проще переходить к другим файлам в репозитории.
Относительная ссылка — это ссылка, заданная относительно текущего файла. Например, если есть файл сведений в корне репозитория и еще один файл в docs/CONTRIBUTING.md, относительная ссылка на CONTRIBUTING.md в файле сведений может выглядеть следующим образом:
[Contribution guidelines for this project](docs/CONTRIBUTING.md)
GitHub автоматически преобразует относительную ссылку или путь изображения на основе любой ветви, в которую вы находитесь в данный момент, чтобы ссылка или путь всегда работали. Путь ссылки будет относительным к текущему файлу. Ссылки, начинающиеся с /, будут относительными к корневому каталогу репозитория. Можно использовать любые операнды относительных ссылок, например ./ и ../.
Текст ссылки должен находиться в одной строке. Приведенный ниже пример не будет работать.
[Contribution
guidelines for this project](docs/CONTRIBUTING.md)
Относительные ссылки удобнее для пользователей, которые клонируют репозиторий. Абсолютные ссылки могут не работать в клонах репозитория. Мы рекомендуем использовать относительные ссылки на другие файлы в репозитории.
Вики-страницы
ReadME должен содержать только сведения, необходимые разработчикам для начала работы с проектом и участия в нем. Более длинную документацию удобнее размещать на вики-сайтах. Дополнительные сведения см. в разделе Сведения о вики-сайтах.
Дополнительные материалы
-
[AUTOTITLE](/repositories/working-with-files/managing-files/adding-a-file-to-a-repository) -
[5 советов по созданию страницы профиля GitHub в](https://github.blog/2023-10-26-5-tips-for-making-your-github-profile-page-accessible/) блоге GitHub -
[AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/adding-a-codespaces-badge)