Страницы GitHub - отличный способ создать и управлять веб-сайтом для вашего пользователя GitHub, организации или проекта БЕСПЛАТНО. Помимо поддержки обычного HTML-контента, он также поддерживает Jekyll, популярный генератор статических сайтов. Если вы еще этого не сделали, вам следует ознакомиться как с GitHub Pages, так и с Jekyll. Существует не так много способов ускорить работу статического веб-сайта, но у GitHub Pages действительно есть свой набор ограничений. Хотя GitHub Pages работает на Jekyll, все сайты создаются с использованием параметра --safe, который запрещает любые пользовательские плагины, согласно документации Jekyll. Когда я решил включить данные репозитория GitHub из репозитория, который был размещен за пределами моей организации, я быстро обнаружил, насколько ограничивает параметр --safe. Не волнуйтесь, с помощью Travis CI мы сами создадим страницы сайта, а затем опубликуем статический сайт на GitHub Pages.
По умолчанию GitHub Pages делает метаданные репозитория доступными для сайтов Jekyll, которые он создает. Эти данные доступны в объекте site.github и включают такую информацию, как общедоступные репозитории (если вы создаете сайт пользователя или организации). Для обновленного мной сайта организации было одно хранилище, размещенное внутри другой организации. Сборка --safe сделала это так, что у меня не было возможности получить какие-либо метаданные репозитория извне. Сайты Jekyll создаются из данных JSON, а API GitHub делает метаданные репозитория доступными в формате JSON. Я знал, что должен быть способ добавить метаданные стороннего репозитория в метаданные, уже предоставленные GitHub. Войдите в плагин Jekyll-Get. Этот плагин извлекает данные JSON из внешних источников и делает их доступными для генератора сайта. Теперь у меня был способ получить метаданные JSON. Все, что мне нужно было сделать, это создать свой собственный процесс сборки и опубликовать этот статический сайт в репозитории GitHub.
Чтобы получить максимальную отдачу от этого руководства, я предлагаю вам уже создать сайт GitHub Pages. В этом руководстве не рассматриваются основы начала работы со страницами GitHub. Если вам нужно создать новый сайт, начните здесь. Хотя это руководство ориентировано на решение конкретной проблемы, упомянутой выше, описанные шаги будут работать с любым плагином или пользовательским процессом сборки Jekyll.
Что мы рассмотрим
- Использование сборки Jekyll вместо сборки GitHub Pages
--safe - Установка и использование плагина Jekyll-Get для получения данных JSON
- Организация репозитория для нового процесса сборки
- Настройка Travis CI для создания и развертывания сайта
Использование сборки Jekyll вместо страниц GitHub - безопасная сборка
Первое, что нам нужно сделать, это заменить зависимость GitHub Pages на Jekyll в Gemfile. Откройте Gemfile, найдите
gem "github-pages", group::jekyll_pluginsи замените его на:
gem "jekyll" gem "json" gem "hash-joiner"
Затем из командной строки запустите:
bundle install; bundle exec jekyll serve;На этом этапе ваш сайт, скорее всего, будет пустым, потому что метаданные GitHub не извлекаются. Давайте добавим это сейчас.
Установка и использование плагина Jekyll-Get для получения данных JSON
Согласно инструкции по установке плагина Jekyll-Get: «Добавьте этот файл в _plugins в корне вашего сайта Jekyll». Из интерфейса командной строки в корне вашего сайта Jekyll:
mkdir _plugins curl -o ./_plugins/jekyll_get.rb https://raw.githubusercontent.com/18F/jekyll-get/master/jekyll_get.rb
Добавьте следующую строку в файл _config.yml в корневой папке сайта:
plugins_dir: ./_plugins
Теперь вы можете указать, какие данные GitHub JSON нужно извлекать. Добавьте этот раздел под строкой, добавленной выше, и замените <ORG_NAME> на свою организацию:
jekyll_get:
- data: github
json: 'https://api.github.com/orgs/<ORG_NAME>/repos'
cache: false
Если ваша страница GitHub предназначена для пользователя, а не для репозитория, используйте это вместо этого и замените <USER_NAME> своим собственным именем пользователя:
jekyll_get:
- data: github
json: 'https://api.github.com/users/<USER_NAME>/repos'
cache: false
Поскольку при построении страниц GitHub по умолчанию используется public_repositories как набор доступных данных в site.github, вам нужно будет заменить экземпляры site.github.public_repositories на site.data.github в файле index.html. Если вам нужны данные, отличные от репозиториев, просмотрите GitHub API и найдите правильный URL-адрес запроса для нужных вам данных.
Организация репозитория для нового процесса сборки
Если вы создаете сайт для пользователя или организации, GitHub Pages будет публиковать контент только из ветки master. Поскольку мы больше не используем гем github-pages, нам нужно настроить репозиторий так, чтобы сгенерированный контент сайта публиковался в master. Чтобы решить эту проблему, я создал ветку release и запросил все свои изменения в этой ветке. Я также установил ветвь release как ветку по умолчанию.
Ниже мы настроим Travis CI для сборки при появлении обновлений в ветке release и опубликуем статический сайт в master. У меня получился репозиторий с 3 защищенными ветками:
master <- generated static site content release <- Jekyll code to be generated into site develop <- Branch that contains changes until merged into release
Настройка Travis CI для создания и развертывания сайта
Сейчас мы находимся в точке, где конфигурация Jekyll строится без параметра --safe, контент извлекается через API-интерфейсы JSON, а репозиторий готов к отправке обновлений в ветку master, но GitHub Pages не знает, как строить сайт больше. Не волнуйтесь, мы настроим Travis CI для создания и публикации созданного сайта в репозиторий. Если вы еще этого не сделали, перейдите в Travis CI и создайте учетную запись. Как только ваша учетная запись Travis CI сможет синхронизировать репозитории с GitHub, найдите репозиторий и нажмите кнопку, чтобы активировать этот репозиторий.
Затем вы можете нажать Настройки и настроить свой проект по своему усмотрению. Мне лично нравится активная функция Строить выталкиваемые ветки и деактивировать Построение выталкиваемых запросов. Нам потребуется добавить токен GitHub для Travis CI, чтобы иметь возможность опубликовать созданный сайт на master. Перейдите на https://github.com/settings/tokens и создайте личный токен доступа. Дайте токену имя, установите флажок, чтобы предоставить токену доступ к Репо, а затем нажмите Создать токен.
Получив сгенерированный токен, не забудьте скопировать его немедленно, поскольку на этот раз он будет доступен только один раз. Верните этот скопированный токен обратно на страницу настроек в Travis CI, создайте переменную среды с именем GITHUB_TOKEN, вставьте токен в поле значения, убедитесь, что параметр «Отображать значение в журнале сборки» не установлен, затем нажмите "Добавить".
Чтобы Travis CI знал, как построить ваш проект, ему нужен .travis.yml файл. Создайте пустой в корне вашего проекта:
touch .travis.yml
Затем вставьте в файл .travis.yml следующее содержимое:
language: ruby cache: bundler branches: only: - release script: - JEKYLL_ENV=production bundle exec jekyll build --destination site deploy: provider: pages local-dir: ./site target-branch: master email: [email protected] name: Deployment Bot skip-cleanup: true github-token: $GITHUB_TOKEN keep-history: true on: branch: release
Зафиксируйте этот файл, поместите его в ветку release в GitHub. Это нажатие вызовет сборку Travis CI. Вот что делает .travis.yml.
language: ruby cache: bundler
Это настраивает среду для Travis CI и сообщает ему, что мы используем Ruby и Bundler для сборки.
branches: only: - release
Мы хотим генерировать контент сайта только из ветки release.
script: - JEKYLL_ENV=production bundle exec jekyll build --destination site
Здесь мы убираем флаг --safe из сборки Jekyll. Это устанавливает рабочую среду и создает содержимое сайта в папке site.
deploy: provider: pages local-dir: ./site target-branch: master email: [email protected] name: Deployment Bot skip-cleanup: true github-token: $GITHUB_TOKEN keep-history: true on: branch: release
Здесь мы используем GitHub Провайдер развертывания страниц для Travis CI. Поскольку на предыдущем шаге мы создали сайт в папке site, нам нужно установить соответствующее значение. Другая важная деталь: skip-cleanup должно быть истинным, иначе ресурсы, созданные на предыдущем этапе сборки, будут удалены и не будут развернуты на GitHub.
Дополнительный кредит
Если вы загружаете динамический контент из репозиториев GitHub, например количество звездочек или количество вилок, вероятно, вы захотите, чтобы это регулярно обновлялось. Вернитесь к настройкам Travis CI и настройте ежедневную сборку для ветки release в разделе Cron Jobs.
Подведение итогов
Это руководство было предназначено, чтобы показать вам, как я решил определенную проблему. Если вы хотите использовать GitHub Pages для размещения статических сайтов, скорее всего, вы довольно быстро перерастете гем github-pages и вам нужно будет начать использовать плагины Jekyll. GitHub Pages - отличный сервис, а с плагинами Jekyll и Travis CI нет ограничений на контент, который вы можете создавать.
