Сведения о файлах сведений
Вы можете добавить файл README в репозиторий и указать в нем важные сведения о проекте. Файл сведений, а также лицензия репозитория, файл ссылок и рекомендации по вкладу сообщают об ожиданиях для вашего проекта и помогают управлять вкладом.
Дополнительные сведения о предоставлении рекомендаций для проекта см. в разделах "Настройка проекта для внесения действенных вкладов".
Файл README часто является первым объектом, который пользователь видит в репозитории. Файлы README обычно включают в себя следующие сведения:
- что делает проект;
- почему проект полезен;
- как пользователи могут приступить к работе с проектом;
- где пользователи могут получить помощь по проекту;
- кто поддерживает проект и вносит вклад в проект.
Если поместить файл README в скрытый каталог .github, корневой каталог или каталог docs, GitHub Enterprise Server распознает и автоматически отобразит файл README для посетителей репозитория.
Если репозиторий содержит несколько файлов README, файл для отображения выбирается из расположений в следующем порядке: каталог .github, корневой каталог репозитория и, наконец, каталог docs.
Если вы добавите файл README в корневой каталог общедоступного репозитория с тем же именем, что и имя пользователя, файл README будет автоматически отображаться на странице профиля. Можно изменить файл README профиля с помощью GitHub Flavored Markdown, чтобы создать персонализированный раздел профиля. Дополнительные сведения см. в разделе Управление файлом сведений о профиле.
Автоматическое оглавление для файлов README
Для просмотра любого файла Markdown в репозитории, включая файлы README, GitHub Enterprise Server автоматически создаст оглавление на основе заголовков разделов. Вы можете просмотреть оглавление файла README, щелкнув значок меню в левом верхнем углу отображаемой страницы.
Ссылки на разделы в файлах README и на страницах BLOB-объектов
Вы можете создать ссылку непосредственно на раздел в отрисованном файле, наведите указатель мыши на заголовок раздела, чтобы открыть .
Относительные ссылки и пути к изображениям в файлах README
Вы можете определить относительные ссылки и пути к изображениям в отображаемых файлах, чтобы читателям было проще переходить к другим файлам в репозитории.
Относительная ссылка — это ссылка, заданная относительно текущего файла. Например, если есть файл сведений в корне репозитория и еще один файл в docs/CONTRIBUTING.md, относительная ссылка на CONTRIBUTING.md в файле сведений может выглядеть следующим образом:
[Contribution guidelines for this project](docs/CONTRIBUTING.md)
GitHub Enterprise Server автоматически преобразует относительную ссылку или путь к изображению с учетом текущей ветви, чтобы ссылка или путь всегда работали. Путь ссылки будет относительным к текущему файлу. Ссылки, начинающиеся с /, будут относительными к корневому каталогу репозитория. Можно использовать любые операнды относительных ссылок, например ./ и ../.
Относительные ссылки удобнее для пользователей, которые клонируют репозиторий. Абсолютные ссылки могут не работать в клонах репозитория. Мы рекомендуем использовать относительные ссылки на другие файлы в репозитории.
Вики
Файл README должен содержать только ту информацию, которая необходима разработчикам, чтобы приступить к использованию проекта и внести свой вклад в проект. Более длинную документацию удобнее размещать на вики-сайтах. Дополнительные сведения см. в разделе Сведения о вики-сайтах.