Развертывание блога jekyll на страницах github с помощью пользовательских плагинов и TravisCI

1. Основные настройки
2. Автоматическое развертывание сайта с TravisCI
3. Настройка Github Branch
4. Личный токен Github
5. Конфигурация сайта Jekyll
6. Настройка TravisCI
7. Дополнительно: пользовательские домены
8. Необязательно: Включить html_proofer
9. Заключительные мысли

Развертывание нового блога с помощью Github Pages очень просто. Все, что вам нужно, это новый репозиторий, названный в честь вашего имени пользователя Github, и сайт jekyll в вашей главной ветке.

Github также предоставляет несколько плагинов из белого списка для простоты использования, которые можно найти здесь , К сожалению, некоторые из них немного устарели (я смотрю на вас, jekyll-paginate). Еще одна плохая новость заключается в том, что, поскольку плагины находятся в белом списке, вы не можете использовать другие плагины.

Мы разработчики, хотя, как белый список остановит нас ...

Основные настройки

Если вы просто хотите иметь очень простой сайт Github Pages и не заботитесь о пользовательских плагинах, руководство, которое предоставляет Github Вот будет более чем адекватным.

Если вы заинтересованы в более упрощенном процессе, продолжайте читать, и я проведу вас через автоматизацию процесса сборки / развертывания.

Автоматическое развертывание сайта с TravisCI

Чтобы обойти ограничение плагинов, мы автоматически создадим наш сайт на TravisCI, используя сборку jekyll, а затем перенесем статический сайт в нашу главную ветку на Github. Это простой процесс, но он может стать утомительным, если вы будете делать это каждый раз, когда пишете новое сообщение. Рабочий процесс описан в блок-схеме ниже.

Настройка Github Branch

Первое, что мы хотим сделать, это создать новую ветку от master с именем source . (Названия здесь не важны, но выберите то, что вы помните). После того, как вы создали свою ветку с исходным кодом, больше не нужно будет использовать основную ветку для этого репо.

Источник будет там, где вы пишете свои записи в блогах, а мастер останется там, откуда Github Pages загружает ваш статический сайт. Например, master будет включать только каталог site /, а source будет иметь весь проект jekyll.

Я настоятельно рекомендую изменить ветку по умолчанию в вашем репозитории на источник . При желании вы можете сделать исходную ветвь защищенной, чтобы предотвратить ее случайное удаление или переопределение.

Личный токен Github

Далее, мы хотим дать TravisCI что-то для аутентификации, чтобы выполнить git push для нас. Для этого создадим токен личного доступа.

Заметка

Вы также можете безопасно передать свой личный токен доступа, зашифровав его в свой файл .travis.yml.

Сначала щелкните меню « Настройки» , расположенное под вашим профилем в правом верхнем углу Github.

Затем найдите Настройки разработчика на левой боковой панели и щелкните по ней.

После этого перейдите к токенам личного доступа и нажмите кнопку « Создать новый токен» . Назовите токен чем-нибудь запоминающимся (я использую Travis CI) и установите области разрешений для всего репо .

Обязательно скопируйте новый токен в буфер обмена, так как он понадобится нам позже.

Конфигурация сайта Jekyll

Нам нужно настроить несколько вещей, чтобы наш сайт Jekyll функционировал надлежащим образом с TravisCI.

Сначала добавьте следующее в ваш Gemfile.

source "https://rubygems.org" ruby ​​RUBY_VERSION # Нам понадобится rake для создания нашего сайта в travisCI gem "rake", "~> 12" gem "jekyll" # Необязательно: Добавьте сюда любые пользовательские плагины. # Ниже перечислены некоторые полезные примеры: jekyll_plugins do gem "jekyll-feed" gem "jekyll-sitemap" gem "jekyll-paginate-v2" gem "jekyll-seo-tag" gem "jekyll-compose", "~> 0.5 "gem" jekyll-redirect-from "end

Любые плагины, которые мы используем выше в нашем Gemfile, мы также хотим перечислить в файле _config.yml сайта Jekyll.

Кроме того, мы хотим исключить определенные файлы и каталоги, чтобы они не попадали в основную ветвь после того, как TravisCI создаст исходную ветвь.

Используя приведенный выше пример, ваш _config.yml может выглядеть так:

title: заголовок вашего блога email: [email protected] # множество других настроек # ... # Все плагины в группе jekyll_plugin из плагинов Gemfile: - jekyll-feed - jekyll-sitemap - jekyll-paginate-v2 - jekyll-seo -tag - jekyll-compose - jekyll-redirect-from # Исключить эти файлы из результатов процесса сборки. # Не позволяет им появляться в главной ветке, # которая является живым сайтом. исключить: - поставщик - Gemfile - Gemfile.lock - ЛИЦЕНЗИЯ - README.md - Rakefile

Поскольку мы используем нашу основную ветку для отображения нашего статически сгенерированного сайта, мы хотим удалить сайт / каталог из отслеживания.

Добавьте это к вашему .gitignore.

, sass - кеш. Джекилл - метаданные _сайт

Далее, и самое главное, нам нужен файл .travis.yml, чтобы TravisCI знал, как мы хотим, чтобы он работал. Я собираюсь пробежаться по нему построчно с объяснениями настроек.

язык: ruby ​​rvm: - 2.3.1 установить: - установить пакет развернуть: провайдер: страницы skip_cleanup: true github_token: $ GITHUB_TOKEN local_dir: _site target_branch: master on: branch: source

язык: ruby ​​использовать язык ruby

rvm: - 2.3.1 Используйте RVM для установки версии ruby ​​на 2.3.1

установить: - установить пакет Запустить пакетную установку, чтобы установить все гемы.

провайдер: страницы Использование провайдера TravisCI Github Pages

skip_cleanup: true Сохранить файлы, созданные на этапе сборки.

github_token: $ GITHUB_TOKEN Наш личный токен доступа. В настоящее время это ссылка на переменную среды, которая будет добавлена ​​в разделе настройки TravisCI ниже.

local_dir: _site Используйте все файлы, найденные в этом каталоге, для развертывания.

target_branch: master Перенесите полученные файлы сборки в эту ветку на Github.

on: branch: source Запустите TravisCI только для этой ветви.

Вы можете найти дополнительную информацию из документация по развертыванию ,

Все это вместе в основном говорит: «Используя исходную ветку из этого репо, переместите все файлы, найденные в каталоге сайта, в основную ветку репо». Это работает только при использовании следующего Rakefile для ручной сборки сайта.

# filename: задача Rakefile: по умолчанию do ставит «Выполняемые задачи CI ...» # Запускает команду сборки jekyll для производства # TravisCI теперь будет иметь каталог сайта с нашими # статически сгенерированными файлами. sh ("JEKYLL_ENV = exec jekyll build производственного комплекта") ставит конец "Jekyll успешно собран"

Rakefile выше запускается на каждой сборке. Из-за этого вы можете добавить другие проверки к этому процессу, такие как html_proofer , Они должны будут пройти без сбоев, прежде чем TravisCI развернет сборку.

Давайте перейдем к последнему шагу. Настройка TravisCI для Github Pages.

Настройка TravisCI

Теперь, когда у нас есть настройки нашего сайта, нам нужно подключить его к TravisCI.

Сначала вы захотите войти в TravisCI, используя свой аккаунт на github. Это даст вам список всех ваших репозиториев.

Найдите свой репозиторий и включите его . Это должно быть в формате username.github.io .

Как показано выше, щелкните значок шестеренки рядом с вновь включенным хранилищем, чтобы перейти на страницу настроек.

Помнишь, когда я это сказал?

Обязательно скопируйте новый токен в буфер обмена, так как он понадобится нам позже.

Пришло время снова выкопать этот токен-код.

GITHUB_TOKEN должен соответствовать строке вашего файла .travis.yml github_token: $ GITHUB_TOKEN для правильной аутентификации использования.

Получив код, создайте новую переменную среды с именем GITHUB_TOKEN на странице настроек TravisCI.

Вот скриншот общих настроек, которые я рекомендую использовать для вашего процесса сборки.

После того, как у вас все настроено, попробуйте добавить новый коммит в ветку исходного кода . Вы должны увидеть запуск, прохождение сборки TravisCI и, в конечном итоге, если вы перейдете на username.github.io, ваш сайт будет работать! Если по какой-то причине ваша сборка не удалась, просмотрите журнал заданий на предмет подробностей об ошибках. Я был бы рад помочь устранить их в комментариях.

Это оно! Начните вести блог.

Дополнительно: пользовательские домены

Вы можете предоставить своим читателям более специализированный опыт, предоставив им собственный домен для навигации. Это достигается указанием вашего сайта username.github.io на регистраторе домена, где вы приобрели доменное имя. (например joshfrankel.me )

Не волнуйтесь, если это звучит страшно. Это на самом деле легко настроить. Namecheap имеет отличную статью, которая проведет вас через весь процесс ,

Что вам нужно сделать, это сначала создать файл CNAME в вашем хранилище Github. Файл CNAME должен содержать ваше доменное имя. Например мой ниже:

# имя файла: CNAME joshfrankel. мне

Это говорит Github Pages, где ваш сайт публикуется.

Ниже я перечислил основные настройки того, что вам нужно сделать для других регистраторов доменов. (Из документации по Namecheap)

• Запись для @, указывающая на 192.30.252.153
• Запись для @, указывающая на 192.30.252.154
• Запись CNAME для www, указывающая на ваше имя пользователя.github.io (имя пользователя должно быть заменено вашим реальным именем пользователя учетной записи GitHub):

Github обновил свои серверы, и поэтому вам нужно будет указать свой DNS на следующие IP-адреса. Как и выше, вы захотите создать записи A, указывающие на @ для каждого из указанных ниже IP-адресов. Вот соответствующая документация ,

Если вы настроили записи A через своего провайдера DNS, ваши записи A должны указывать в вашем настраиваемом домене следующие IP-адреса:

• 185.199.108.153
• 185.199.109.153
• 185.199.110.153
• 185.199.111.153

Если вы сейчас перейдете на страницу настроек вашего репозитория, вы должны увидеть что-то вроде этого:

Примечание . Мелкий шрифт вокруг включения https утверждает, что в настоящее время он недоступен для пользовательских доменов. Тем не менее, есть дополнительные ресурсы и руководства для настройка сторонних сервисов, таких как CloudFlare, для включения https для Github Pages , Это также может быть возможно через другие DNS-хосты, такие как Namecheap (который я использую).

Необязательно: Включить html_proofer

… Вы можете добавить другие проверки к этому процессу, такие как html_proofer , Они должны будут пройти без сбоев, прежде чем TravisCI развернет сборку.

Как я упоминал выше, одним из преимуществ Rakefile является то, что пользовательские проверки должны пройти, прежде чем сборка будет отправлена ​​для развертывания. Одним из них является действительно полезный гем под названием html_proofer, который позволяет тестировать визуализированный HTML- код на предмет достоверности.

Мы можем настроить это с помощью нескольких простых шагов. Сначала мы хотим добавить html_proofer в наш Gemfile.

# Gemfile gem "rake", "~> 12" gem "jekyll" # За пределами гема группы плагинов jekyll "html-proofer"

Затем мы добавим несколько строк и конфигурацию в наш существующий Rakefile, чтобы начать тестирование содержимого встроенной папки _site.

require "html-proofer" # Требуется gem для использования в задачах: по умолчанию do ставит "Выполнение задач CI ..." sh ("JEKYLL_ENV = exe сборка exec jekyll производства") # Добавить HTMLProofer.check_directory ("./_ site") .run для начала проверки # на недопустимый HTMLProofer HTML. check_directory ("./_site", url_ignore: [/linkedin.com|php-fig.org|bower.io|bost.ocks.org|elementary.io/]). запустить ставит конец "Джекилл успешно построен"

Вызов html_proofer должен произойти после того, как сайт jekyll будет построен из строки сборки JEKYLL_ENV = exe jecyll для производственного комплекта. Это гарантирует, что есть вновь созданные файлы для проверки в соответствии с настройками линтера.

Основной код для получения этой работы: HTMLProofer.check_directory ("./_ site"). Run. Это заставляет html_proofer просматривать каталог _site и запускать все доступные линтеры.

Мы можем проверить все это локально, выполнив следующую команду rake в нашем каталоге разработки. Команда rake запускает задачу по умолчанию, найденную в Rakefile.

> rake Выполнение задач CI ... JEKYLL_ENV = рабочий комплект exec jekyll build Файл конфигурации: /home/josh/Development/joshmfrankel.github.io/_config.yml Источник: /home/josh/Development/joshmfrankel.github.io Пункт назначения: /home/josh/Development/joshmfrankel.github.io/_site Инкрементная сборка: отключена. Включить с --incremental Generating ... AutoPages: отключено / не настроено в site.config. Разбивка на страницы: полная, обработанная 1 страница (-ов) разбивки на страницы, выполненная за 0,819 секунды. Авто-регенерация: отключена. Используйте --watch для включения. Запуск ["ImageCheck", "ScriptCheck", "LinkCheck"] на ["./_site"] на * .html ... Проверка 65 внешних ссылок ... Выполнено на 53 файлах! HTML-Proofer успешно завершен. Джекилл успешно построен

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

Как вы можете видеть из моего примера выше, html_proofer имеет много дополнительных опций конфигурации. Один из которых является url_ignore. Это особенно полезно для игнорирования ошибок связывания, связанных с SSL, необходимыми входами в систему и платными сетями. Например, у меня на сайте есть значок социальной сети, который ссылается на https://www.linkedin.com/in/joshmfrankel , LinkedIn требует, чтобы пользователь вошел в систему для просмотра активных профилей. Из-за этого проверка html_proofer завершится неудачей. Поэтому я добавил его в черный список URL-адресов, чтобы игнорировать их во время линтинга.

Заключительные мысли

Есть ли что-то, что я мог бы объяснить больше? Легко ли было выполнить вышеперечисленные шаги? У вас есть плагин Jekyll, который вы копаете? Я хотел бы услышать об этом в комментариях ниже.

Спасибо за прочтение.

Похожие

Комментарии