Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Сведения о файлах сведений

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

Сведения о файлах сведений

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

Дополнительные сведения о предоставлении рекомендаций для проекта см. в разделе "Настройка вашего проекта для эффективного внесения вклада."

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

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

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

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

Главная страница репозитория github/scientist и его файл README

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

Файл README в репозитории username/username

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

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

Файл README с автоматически созданным оглавлением

Ссылки на разделы в файлах README и на страницах BLOB-объектов

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

Ссылка на раздел в файле README для репозитория github/scientist

Относительные ссылки и пути к изображениям в файлах README

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

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

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

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

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

Вики

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

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