Пошаговое руководство, которое поможет вам сэкономить время и усилия

В этой статье я поделюсь процессом создания личного сайта и портфолио с помощью Jekyll. Jekyll — это Ruby Gem, используемый для простого создания статических веб-сайтов, содержимое которых предопределено во время сборки и не зависит от каких-либо действий пользователя или подключения к базе данных.

Поскольку я не веб-дизайнер и не хотел тратить время на разработку CSS и HTML, я искал красивый и впечатляющий шаблон и наткнулся на Beautiful Jekyll (https://beautifuljekyll.com/) Дина Аталли, который я буду настраивать в этом посте. Это мой сайт — https://erap129.github.io, который мы и научимся создавать, а это репозиторий сайта — https://github.com/erap129/erap129.github.io .

Эта статья будет организована следующим образом:

  1. Требования — что мне нужно/хочу от моего сайта
  2. Настройки и установки
  3. Создание веб-сайта
  4. Развертывание веб-сайта

Часть 1. Требования

Прежде чем я начал работать, я определил свои основные цели для этого сайта. Должно:

  • Предоставлять общую информацию обо мне потенциальным и существующим клиентам/сотрудникам/работодателям, например, мои интересы, проекты и хобби.
  • Содержать страницу, содержащую превью всех моих статей на Medium и ссылку на них на платформе Medium. Эта страница не должна создаваться вручную, так как я планирую продолжать писать на Medium, и я не хочу каждый раз копировать и вставлять свои сообщения на свой личный сайт. Кроме того, он должен обновляться автоматически, чтобы мне не приходилось обновлять свой сайт всякий раз, когда я публикую сообщения на Medium.
  • Содержите дополнительные статические страницы — например, мои научные публикации, вклады в общедоступный код и, возможно, что-то еще.

Часть 2 — Настройки и установки

Важно сказать — Beautiful-Jekyll — отличный шаблон. Если структура сайта, определенная этим шаблоном, вам подходит и вам не нужна интеграция с Medium — просто пропустите мою статью и следуйте официальным инструкциям.

Мне очень понравился дизайн этого шаблона, но для создания интеграции с Medium мне пришлось немного его настроить. Для этого мне понадобилась возможность развернуть сайт локально, что является целью следующих установок:

Этот документ — https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll предоставляет отличное объяснение того, как настроить вашу среду для работы с Jekyll и Github Pages, но здесь я также рассмотрю основные шаги. Я предполагаю, что вы используете Ubuntu Linux (если это не так — следуйте инструкциям по ссылке выше в соответствии с вашей ОС).

  • Прежде всего, установите Ruby — sudo apt-get install ruby-full
  • Теперь устанавливаем Bundler — sudo gem install bundler
  • Форк Beautiful-Jekyll — шаги написаны здесь — https://github.com/daattali/beautiful-jekyll#readme. Вот они:
    1. Разветвите проект как <yourusername>.github.io
    2. Клонируйте проект на свой компьютер.
  • Чтобы запустить веб-сайт локально, перейдите в папку локального репозитория в терминале и запустите bundle install. Это установит необходимое программное обеспечение Ruby, используемое для запуска и обслуживания Jekyll. Теперь каждый раз, когда вы хотите обслуживать веб-сайт локально, запускайте bundle exec jekyll serve. Поздравляю! Сайт будет доступен https://localhost:4000

Часть 3 — Создание веб-сайта

Вот что я сделаю, чтобы настроить шаблон Jekyll под свои нужды:

  1. Создайте страницу «Сообщения в блоге», которая будет интегрирована в Medium.
  2. Создайте дополнительные страницы на основе уценки: Главная и Публикации

Давайте начнем!

Создайте страницу «Сообщения в блоге»

Первый вопрос — как мы получаем информацию от Medium? Ответ — RSS! У Medium есть RSS-канал для каждого автора, что позволяет мне получать всю информацию о моих статьях с помощью простого URL-адреса (для меня это — https://medium.com/feed/@erap129).

Мне очень понравилось, как посты отображаются в Beautiful Jekyll, но в моем случае я хочу, чтобы каждый превью не ссылался на внутренний пост, а на исходный пост на Medium.

Для динамической генерации контента в Jekyll нам потребуется создать плагин-генератор. Плагины в Jekyll — это фрагменты кода Ruby, которые запускаются при создании веб-сайта и выполняют различные функции. Наш генератор соберет всю информацию о моих сообщениях на Medium и сохранит ее в коллекции, которую мы будем использовать в HTML-коде нашего сайта.

Давайте создадим папку с именем _plugins в главном каталоге нашего репозитория и создадим файл с именем jekyll-display-medium-posts-json.rb со следующим содержимым:

Этот плагин является расширением/модификацией плагина, представленного в сообщении Джеймса Хаммана — https://medium.com/@jameshamann/displaying-medium-posts-on-your-jekyll-website. -7eef230309e4».

Пройдемся по коду:

  • В строке 10 мы создаем новую коллекцию с именем medium_posts_json. Мы можем использовать это имя в коде сайта для доступа к нашим сообщениям.
  • В строке 12 мы вызываем API rss2json. Формат JSON дает нам лучший контроль над контентом, который мы получаем от Medium, и поэтому мы используем этот API для преобразования формата XML Medium в JSON.
  • В строках 18–33 мы собираем информацию, которую будем использовать на нашей странице «Сообщения в блоге» — название статьи, изображение, ссылку и дату (мы также собираем категории, но не используем их).
  • Обратите внимание, что мы используем гем nokogiri Ruby для обхода содержимого HTML в строке 31. Почему? Поскольку описание каждого поста в RSS-канале представляет собой необработанный HTML, здесь мы хотим создать краткий отрывок из постов. Чтобы пропустить заголовки и изображения — извлекаем только абзацы (которые находятся в тегах p в HTML).

Важно добавить следующий фрагмент в _config.yaml. В противном случае коллекция, созданная генератором, не будет доступна для использования на сайте:

collections:
- medium_posts_json

Теперь нам нужно создать макет, который будет использовать эту информацию и преобразовывать ее в HTML-код, отображаемый браузером. Мы создадим новый файл с именем blog.html в каталоге _layouts со следующим содержимым:

Этот макет представляет собой урезанную версию оригинального макета в Beautiful-Jekyll — https://github.com/daattali/beautiful-jekyll/blob/master/_layouts/home.html. Единственные изменения, которые я внес, заключались в удалении ненужного контента и использовании в макете коллекции, которую я создал ранее — site.medium_posts_json.

  • Обратите внимание, что в строке 5 мы перебираем коллекцию, созданную с помощью нашего плагина, и добавляем необходимый HTML-код для каждого элемента. Jekyll использует синтаксис Liquid для создания этого контента. Подробнее о Liquid можно прочитать здесь — https://shopify.github.io/liquid/.

Теперь все, что нам нужно сделать, это создать новый файл с именем blogposts.md в главном каталоге и использовать созданный нами новый макет — blog.

---
layout: blog
title: Blog Posts
subtitle: This is what keeps my mind busy
---

Кроме того, отредактируйте раздел navbar-links в _config.yaml, чтобы включить новую страницу сообщений в блоге.

Большой! Если теперь я буду обслуживать свой веб-сайт локально, используя bundle exec jekyll serve, я смогу получить доступ к своему сайту в https://localhost:4000 и увидеть внесенные изменения.

2. Создайте дополнительные страницы на основе уценки

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

Таким образом, мы удалим index.html и заменим его на index.md. Я добавил личную информацию о себе на этой странице, но вы можете делать все, что пожелаете. Я также добавил страницу publications.md, на которой я перечисляю свои научные публикации. Раздел navbar-links в моем _config.yaml выглядит так:

navbar-links:
Home: "index"
Blog Posts: "blogposts"
Publications: "publications"

Часть 4 — Развертывание веб-сайта

Как только мы достигли стадии, когда мы запускаем bundle exec jekyll serve и нам нравится то, что мы видим, мы готовы к развертыванию.

Мы хотим, чтобы наш сайт развертывался в двух случаях:

  1. Когда мы помещаем новый/обновленный контент в главную ветку репозитория
  2. Каждый раз, когда на Medium добавляется новый пост, мы хотим интегрироваться в сайт.

1 будет легко, а для 2 мы сделаем это ежедневным процессом. Это означает, что каждый день в установленное время будет создаваться процесс сборки веб-сайта, и если я добавлю новый контент в свой профиль на Medium, он будет загружен на веб-сайт.

Мы не можем полагаться на действия по развертыванию страницы GitHub по умолчанию, потому что мы используем настраиваемые плагины, которые страницы GitHub официально не поддерживают. Кроме того, мы хотим, чтобы процесс сборки был своевременным, а не основывался только на отправке в основную ветку. С этой целью мы будем использовать это пользовательское действие GitHub из торговой площадки под названием Jekyll Actions — https://github.com/marketplace/actions/jekyll-actions.

По ссылке выше есть довольно полезный учебник, но я все же проведу вас через шаги, необходимые для активации этого действия. В корневом каталоге сайта я создал следующий файл: .github/workflows/github-pages.yml со следующим содержимым:

Давайте рассмотрим то, что мы здесь видим (интересные моменты)

  • В строках 4–8 мы определяем, когда будет происходить развертывание сайта — по push-событию в ветку master и каждый день в полночь. Я делаю это, чтобы редактировать свой веб-сайт вручную, если захочу, но если я опубликую новый контент на Medium, мне не обязательно придется его редактировать.
  • Обратите внимание, что в строках 23 и 26 я ссылаюсь на секрет под названием JEKYLL_PAT. Чтобы настроить это, я создал токен личного доступа GitHub — https://github.com/settings/tokens с полным доступом к репозиторию и добавил его в качестве секрета в настройки моего проекта (страница репо -> настройки -> секреты - › действия).
  • Остальной код был взят из оригинального экшена GitHub и подробно описан здесь — https://github.com/marketplace/actions/jekyll-actions.

Еще один важный шаг — установить ветку развертывания на gh-pages (ветвь, в которую помещается статическое содержимое), чтобы GitHub знал, что нужно размещать файлы из этой ветки. Я хочу выразить особую благодарность Кристиану из StackOverflow, который помог мне решить проблему, связанную с этим — https://stackoverflow.com/questions/74244454/helaili-jekyll-action-does-not-update-the-browser- with-gh-pages-branch-content. Делается это через настройки репозитория вот так:

Вот и все!

Конечно, вы можете бесконечно настраивать свой веб-сайт, и я не стал рассматривать тривиальные вещи, которые, я уверен, вы сможете понять, такие как изменение названия веб-сайта, добавление собственной фотографии и многое другое. Файл _config.yaml не требует пояснений и позволяет легко манипулировать и настраивать его.

Спасибо, ребята! Ваше здоровье.

Бонусный совет:

Соответствующие ссылки: