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

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

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

Сегодня это динамический веб-сервер Node.js на базе Express, использующий промежуточное ПО для правильного перенаправления HTTP, обнаружения заголовков языка и динамической генерации контента для поддержки различных вариантов GitHubпродуктовой документации, таких как Free, Pro, Team и GitHub Enterprise Server.

Инструменты для этого сайта изменились на протяжении многих лет, но многие из проверенных и истинных соглашений по разработке исходного сайта Jekyll были сохранены.

Контент записывается в файлах Markdown. Они хранятся в content справочнике.
Контент может использовать язык шаблонирования Liquid. См . раздел AUTOTITLE.
Файлы в 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. Чтобы проверить, какая версия Node вам нужна, вы можете посмотреть файл 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.

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

По умолчанию локальный сервер не работает со всеми поддерживаемыми языками. Если необходимо запустить локальный сервер с определенным языком, можно временно изменить 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 в пространстве кода.

В этой статье