Skip to main content
Мы публикуем частые обновления нашей документации, и перевод этой страницы может все еще выполняться. Актуальные сведения см. в документации на английском языке.
В настоящее время GitHub AE находится в ограниченном выпуске.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вики

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

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