О структуре сайта GitHub Docs
Сайт GitHub Docs изначально был веб-приложением Ruby on Rails. Некоторое время спустя он был преобразован в статический сайт, управляемый Jekyll. Через несколько лет после этого он был перенесен в Nanoc, другой генератор статических сайтов Ruby.
Сегодня это динамический Node.js веб-сервер, управляемый Express, с помощью по промежуточного слоя для поддержки соответствующих перенаправлений HTTP, обнаружения заголовков языка и динамического создания содержимого для поддержки различных вариантов документации по продуктам GitHub, таких как бесплатная, pro и GitHub Enterprise Server.
Инструменты для этого сайта изменились на протяжении многих лет, но многие из проверенных и истинных соглашений по разработке исходного сайта Jekyll были сохранены.
- Содержимое записывается в файлы Markdown, которые живут в каталоге
content
.
- Файлы в
data
каталоге доступны для шаблонов с помощью тега{% data %}
. - Файлы Markdown могут содержать frontmatter.
- Поддерживается поведение подключаемого
redirect_from
модуля Jekyll.
Настройка локальной среды
Вы можете клонировать репозиторий GitHub Docs и запустить приложение локально на компьютере после первоначальной настройки.
Установка Node.js
Сайт GitHub Docs используется Node.js. Он работает в средах macOS, Windows и Linux.
Чтобы запустить сайт, вам потребуется Node.js. Чтобы установить Node.js, скачайте установщик LTS из nodejs.org. Чтобы проверить нужную package.json
версию узла, можно просмотреть файл в репозитории GitHub Docs . Версия узла отображается в engine
поле, аналогично следующему примеру. Это означает, что можно использовать основную версию узла 16 или основной узел версии 18.
"engines": {
"node": "^16 || ^18"
}
Если вы используете nodenv
, ознакомьтесь nodenv
с инструкциями по переключению Node.js версий.
Запуск локального сервера GitHub Docs
После установки Node.js (который включает в себя популярный npm
диспетчер пакетов), откройте терминал и выполните следующие команды.
git clone https://github.com/github/docs
cd docs
npm ci
npm start
Теперь у вас должен быть запущенный сервер. Чтобы получить доступ к локальной предварительной среде, посетите localhost:4000 в браузере.
Когда вы будете готовы остановить локальный сервер, введите ctrl+C в окне терминала.
Примечание. Обычно необходимо npm ci
npm run build
выполнять только последнюю версию ветви.
npm ci
выполняет чистую установку зависимостей без обновленияpackage-lock.json
файла.npm run build
создает статические ресурсы, такие как JavaScript и CSS-файлы.
Дополнительные сведения об отладке и устранении неполадок приложения GitHub Docs см. в разделе "Устранение неполадок с средой" в репозитории github/docs.
Использование сочетаний клавиш браузера
Каталог src/bookmarklets
в репозитории GitHub Docs содержит ярлыки браузера, которые могут помочь в просмотре документации по GitHub. Дополнительные сведения см. в каталоге README
.
Включение различных языков
По умолчанию локальный сервер не работает со всеми поддерживаемыми языками. Если необходимо запустить локальный сервер с определенным языком, можно временно изменить start
скрипт package.json
и обновить ENABLED_LANGUAGES
переменную.
Например, чтобы включить японский и португальский в дополнение к английскому языку, можно изменить package.json
и задать ENABLED_LANGUAGES='en,ja,pt'
в скрипте start
. Затем перезапустите сервер, чтобы изменения вступили в силу.
Примечание. Перед фиксацией изменений необходимо вернуть package.json
файл в исходное состояние.
Поддерживаемые коды языка определены в src/languages/lib/languages.js
.
Использование GitHub Codespaces
В качестве альтернативы локальному выполнению GitHub Docs можно использовать GitHub Codespaces. GitHub Codespaces позволяет изменять, просматривать и тестировать изменения непосредственно из браузера.
Дополнительные сведения об использовании пространства кода для работы с документацией GitHub см. в разделе "Работа с документами GitHub в пространстве кода".