Создание локальной среды

О структуре сайта GitHub Docs

Сайт GitHub Docs изначально был веб-приложением Ruby on Rails. Некоторое время спустя он был преобразован в статический сайт, управляемый Jekyll. Через несколько лет после этого он был перенесен в Nanoc, другой генератор статических сайтов Ruby.

Сегодня это динамический Node.js веб-сервер, управляемый Express, с помощью по промежуточного слоя для поддержки соответствующих перенаправлений HTTP, обнаружения заголовков языка и динамического создания содержимого для поддержки различных вариантов документации по продуктам GitHub, например GitHub.com и 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 в пространстве кода".