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

О структуре сайта 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 см. раздел AUTOTITLE в репозитории github/docs.

Включение различных языков

По умолчанию локальный сервер не работает со всеми поддерживаемыми языками. Если необходимо запустить локальный сервер с определенным языком, можно временно изменитьstart скриптpackage.json и обновитьENABLED_LANGUAGES переменную.

Например, чтобы включить японский и португальский в дополнение к английскому языку, можно изменитьpackage.json и задатьENABLED_LANGUAGES='en,ja,pt' в скриптеstart . Затем перезапустите сервер, чтобы изменения вступили в силу.

Примечание.

Перед фиксацией изменений необходимо вернутьpackage.json файл в исходное состояние.

Поддерживаемые коды языка определены вsrc/languages/lib/languages.ts.

Использование GitHub Codespaces

В качестве альтернативы локальному выполнению GitHub Docs можно использовать GitHub Codespaces. GitHub Codespaces позволяет изменять, просматривать и тестировать изменения непосредственно из браузера.

Дополнительные сведения об использовании пространства кода для работы с документацией GitHub см. в разделеРабота с документами GitHub в пространстве кода.

В этой статье