Просмотр Project README в Orbit

Вкладка «Docs» отображает README вашего репозитория внутри KPanel, поэтому документация проекта находится в одном щелчке от его развёртываний, а не в отдельной вкладке браузера, которую кому-то нужно искать.

Где находится вкладка Docs

Откройте Orbit, нажмите на проект и выберите Docs в группе Overview на полосе вкладок проекта.

Настраивать нечего. Если проект имеет подключённый репозиторий с README в его корне, вкладка его отображает.

Какой файл отображается

Orbit получает README из основной ветви подключённого репозитория.

На GitHub он пробует несколько традиционных имён по очереди: README.md, readme.md, README.MD, README и readme.txt, выбирая первый существующий. На GitLab и Bitbucket он ищет README.md.

Проверяется только корень репозитория. README в подпапке, включая корневую папку приложения monorepo, не будет обнаружен.

Что отображается

README отображается как markdown: заголовки, списки, таблицы, ссылки, встроенный код и блоки кода в ограде отображаются так, как и ожидалось.

Относительные пути к изображениям внутри README указывают на репозиторий, а не на KPanel, поэтому изображения, которые работают на сайте вашего поставщика, могут не загружаться здесь. Если изображение важно, используйте абсолютный URL.

Пустые состояния

Два состояния заменяют содержимое, когда нечего показывать:

• No repository connected (Репозиторий не подключен) с кнопкой Connect repository (Подключить репозиторий). Сначала подключите его: см. Подключение репозитория GitHub, Подключение репозитория GitLab или Подключение репозитория Bitbucket.
• No README found (README не найден), предлагая добавить README.md в корень вашего репозитория, со ссылкой для создания одного на вашем поставщике.

Обе ссылки ведут к поставщику, чтобы вы могли действовать немедленно, а заполненное представление имеет ссылку View on (Посмотреть на) на сам файл для случаев, когда вы хотите его отредактировать.

Написание README, достойного отображения

Поскольку эта вкладка находится рядом с историей развёртываний, наиболее полезный README для проекта Orbit является операционным. Кто-то открывает его, потому что ему только что передали проект и нужно безопасно что-то изменить.

Структура, которая работает:

Что это такое. Один абзац. Что делает проект и кому он служит.

Запуск локально. Точные команды, включая менеджер пакетов. pnpm install && pnpm dev лучше, чем абзац, описывающий то же самое.

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

Как он развёртывается. Какая ветвь является production, развёртываются ли теги и какие ограничения действуют. Укажите на вкладку Orbit Deployment Pipeline вместо дублирования, потому что вкладка не может устаревать, а ваш README может.

Как откатить. Два предложения и ссылка на Rolling Back a Deployment. Это то, что люди нужно в их худший момент, и это должно быть там, где они будут искать.

Кто это ведает. Команда или человек. Проекты пережидают людей, которые их создали.

Добавление значка состояния в режиме реального времени

Поскольку README отображается здесь и у вашего поставщика, стоит добавить значок состояния развёртывания. Orbit публикует его для каждого проекта.

Откройте Settings и найдите карточку Status badge. Она показывает предпросмотр в реальном времени и три кнопки копирования: URL значка, фрагмент markdown и фрагмент HTML. Вставьте markdown в начало вашего README.

Значок это небольшой SVG, который показывает текущий статус production среды проекта: deployed (развёрнуто), building (строится), failed (не удалось), queued (в очереди) или no deployments (нет развёртываний). Он не требует аутентификации, поэтому отображается для всех, читающих репозиторий, и ссылается обратно на проект в KPanel.

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

Поддержание его честности

README, который описывает настройку, которую проект больше не имеет, хуже, чем отсутствие README, потому что люди ему верят. Две привычки поддерживают его точность:

• Ссылайтесь, а не дублируйте. Всё, что видно в KPanel, такое как параметры сборки, ограничения и конфигурация окружения, должно быть связано с ним, а не пересказываться.
• Обновляйте его в одном pull request. Если изменение изменяет способ запуска проекта, изменение README должно быть в этом pull request, а не в более позднем упорядочивании.

Устранение неполадок

На вкладке отображается старая версия. Кэш на пять минут. Подождите и перезагрузите.

README не найден, но он есть. Проверьте, находится ли он в корне репозитория и называется ли README.md. На GitLab и Bitbucket имя должно совпадать в точности.

Репозиторий подключен, но вкладка говорит, что нет. Соединение могло потерять доступ, например если интеграция была удалена на стороне поставщика. Переподключите его из параметров проекта.

Изображения не загружаются. Относительные пути здесь не разрешаются. Используйте абсолютные URL.

Значок показывает отсутствие развёртываний. Production среда никогда не имела успешного развёртывания. Развёртесь один раз и он обновится.

Что дальше

• Orbit Deployment Pipeline, живая версия того, что README обычно пытается описать.
• Orbit Project Settings для значка состояния и остальной конфигурации.
• Переменные окружения в Orbit для значений, которые README никогда не должен содержать.