Как завести блог на Jekyll

Jekyll — генератор статичных сайтов. Грубо говоря, он просто помогает собрать из шаблонов и текстов набор HTML-файлов, которые можно разместить на любом веб-сервере. Этот сайт — Hexlet Guides — работает на Jekyll.

• Обзор
• Установка Jekyll на локальную машину
  • Прямая установка и запуск Jekyll
  • Установка и запуск Jekyll через Docker
• Файловая структура
• Конфигурация
  • _config.yml
  • Настройка темы
  • Front Matter
• Создание постов
• Создание страниц
• Публикация в интернете
  • Публикация HTML-файлов на веб-сервере
  • Публикация на Github Pages с поддержкой Jekyll
  • Публикация на Github Pages без поддержки Jekyll
  • Подключение своего домена
• Дополнительные возможности

В отличие от движков для блогов или CMS вроде Wordpress или Ghost, конечный результат работы Jekyll — это не исполняемые программы на языке программирования, а статичные HTML-файлы. Поэтому для размещения сайта не нужен PHP, Node, базы данных и мощный хостинг. Раздача статических файлов создает минимальную нагрузку на сервер, поэтому чаще всего достаточно самого дешевого хостинга.

Jekyll-сайт можно разместить бесплатно на Github Pages, чем мы и займемся в этом руководстве.

Обзор

Рассмотрим схему работы Jekyll и схему публикации сайта вкратце:

1. Вы создаёте шаблоны для вашего сайта: как выглядит главная страница, как выглядят страницы постов, категорий, шапки, подвалы и другие блоки сайта.
2. Вы пишете посты в формате Markdown (доступны и другие форматы).
3. Jekyll генерирует конечные HTML-страницы на основе шаблонов и Markdown-файлов.
4. Вы публикуете HTML на веб-сервере и сайт становится доступным в интернете.

GitHub Pages позволяет размещать любые HTML-страницы, но он также поддерживает Jekyll на своей стороне. Это означает, что вы можете не отправлять сгенерированный HTML в Github, а отправлять только папку с вашим Jekyll-проектом и Markdown-файлами, а Github сам запустит генерацию HTML и разместит их у себя.

Установка Jekyll на локальную машину

Есть два способа работы с Jekyll на локальной машине: напрямую или через Docker. Второй способ намного проще и быстрее, но может быть непривычен, если вы никогда раньше не работали с Докером.

Прямая установка и запуск Jekyll

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

В зависимости от операционной системы, у вас может быть уже установлен Ruby.

В Windows можно использовать RubyInstaller. Работать с Jekyll нужно через командную строку. Для подготовки необходимого окружения в Windows используйте наш гайд Как начать разрабатывать в Windows.

В официальной документации Jekyll есть раздел, посвященный разным способам установки Ruby и Jekyll на Windows.

В macOS Ruby есть в комплекте. Проверьте его версию:

ruby -v
ruby 2.3.3p222 (2016-11-21 revision 56859) [x86_64-darwin16]

Нужна версия 2.0 и выше. Если у вас по какой-то причине более ранняя версия, то обновите Ruby командой sudo gem install ruby.

Теперь установите Bundler. Это менеджер пакетов, именно через него мы в итоге установим Jekyll и другие необходимые для него пакеты:

gem install bundler

Теперь установите Jekyll:

gem install jekyll

Теперь создайте блог:

jekyll new myblog
cd myblog
bundle exec jekyll serve

Откройте в браузере http://localhost:4000.

Установка и запуск Jekyll через Docker

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

Официальный Докер-образ Jekyll — jekyll/jekyll.

Самый простой способ начать — использовать наш пакет с готовой темой, основанной на Bootstrap 4.

git clone git@github.com:hexlet-boilerplates/jekyll-bootstrap4-docker.git
cd 
make serve

Откройте в браузере http://localhost:4000.

Файловая структура

Базовая структура директории с сайтом выглядит так:

.
├── _config.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.md
|   └── on-simplicity-in-technology.md
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-hello.md
|   └── 2009-04-26-good-stuff.md
├── _sass
|   ├── _base.scss
|   └── _layout.scss
├── _site
└── index.html

Вкратце:

• ваши посты (например, в формате Markdown находятся в папке _posts.
• шаблоны страниц — в папке _layouts
• используемые в шаблонах повторяющиеся блоки — в папке _includes
• главная страница сайта — в index.html

Jekyll берет за основу шаблон, генерирует для каждого поста соответствующие страницы и собирает весь сайт в папке _site.

Конфигурация

_config.yml

В файле _config.yml описана конфигурация сайта.

title:       "Page title"
header_title: "Header Title"
email:       your@ema.il
author:      Your Name
description: "My blog description"
baseurl:     ""
url:         "https://myblog.com"
date_format: "%-d.%m.%Y"

Важная деталь: url — адрес вашего корневого сайта, а baseurl — путь к Jekyll-сайту.

https://hello.goo.com/myblog/
|--------------------|======|
         |              |
        url          baseurl

Если ваш сайт находится в корне, то baseurl будет пустым.

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

twitter_username: hexlet

Параметр используется в файле _includes/header.html:

{% raw %}{% if site.twitter_username %}
  <li class="nav-item">
    <a class="nav-link" href="https://twitter.com/{{ site.twitter_username }}">
      <span class="mr-1 fa fa-twitter"></span>
    </a>
  </li>
{% endif %}{% endraw %}

Здесь сказано «если в конфигурации есть параметр twitter_username с непустым значением, то вывести ссылку на Твиттер».

Настройка темы

Jekyll идет в комплекте с базовой темой оформления. Наш пакет основан на популярном фреймворке Bootstrap 4.

Рассмотрим наш пример поближе:

• _includes — блоки, используемые в нескольких местах
  • head.html — элемент <head>, где подключаются стили, указываются мета-теги и так далее
  • header.html — шапка сайта
  • footer.html — подвал сайта
  • post_footer.html — показывается под постом на странице поста (включается в конфигурации)
  • share_buttons.html — кнопки шеринга в соц. сетях под постом на странице поста (включаются и настраивается в конфигурации)
  • social_links.html — ссылки на соц. сети, показываются в шапке сайта (включается и настраиваются в конфигурации)
• _layouts — основные шаблоны сайта
  • default.html — главный шаблон, используется на главной странице
  • post.html — шаблон поста, используется на странице поста
• css — стили
  • style.css — основной файл стилей сайта
  • likely.css — стили для кнопок шеринга в соц. сетях
• js — скрипты
  • likely.js — скрипт для кнопок шеринга в соц. сетях
• images — изображения

Front Matter

Любой файл, содержащий блок Front Matter в формате YAML будет обработан Jekyll'ом как особый файл. Блок Front Matter должен идти в самом начале файла.

Например, страница index.html — главная страница сайта — содержит такие строчки в начале:

---
layout: default
---

А так выглядит сам default layout (файл _layouts/default.html):

{% raw %}<!DOCTYPE html>
<html>
{% include head.html %}
<body>
  {% include header.html %}
  <div class="container">
    <div class="row">
      <div class="col">{{ content }}</div>
    </div>
    {% include footer.html %}
  </div>
</body>
</html>{% endraw %}

Таким образом Jekyll при сборке берет содержание файла index.html, вставляет в {% raw %}{{ content }}{% endraw %} шаблона и создает конечный index.html.

Создание постов

Посты находятся в папке _posts. Мы используем формат по умолчанию — Markdown. Пример названия файла: 2017-12-18-features.md. Как видно, дата публикации указана в названии файла. После даты идёт название, используемое для URL. Этот пост будет доступен по адресу mysite.com/features.

Пост также начинается с блока front matter:

---
layout: post
title: Features
cover_url: "/images/tree.jpg"
---

Здесь могут содержаться как переменные Jekyll'а, так и наши собственные переменные. Здесь мы указали две собственных переменных: title и cover_url. Они используются в шаблонах:

В файле _layouts/post.html:

<h1>{% raw %}{{ page.title }}{% endraw %}</h1>

В файле _includes/head.html:

<meta property="og:image" content="{{ page.cover_url | prepend: site.baseurl | prepend: site.url }}">

Здесь задаётся полный адрес обложки для социальных сетей. Подробнее об og-тегах можно узнать из урока «Интеграция с соц. сетями и семантический веб» бесплатного курса Основы HTML, CSS и веб-дизайна на Хекслете.

Вы можете помещать картинки в любую директорию и включать их в посты и в front matter по относительному пути.

Создание страниц

Вы можете создавать любые директории и HTML-файлы самостоятельно, по аналогии с файлом index.html.

Например, если создать директорию works и положить внутрь новый файл index.html (который может даже не содержать front matter, а быть полностью независимым статическим файлом), то страница будет доступна по адресу вроде mysite.com/works (в зависимости от значений url и baseurl в конфигурации)

Публикация в интернете

Публикация HTML-файлов на веб-сервере

Файлы из папки _site достаточно разместить на веб-сервере. Для этого подойдет практически любой хостинг. Подробнее о хостингах можно узнать из бесплатного курса Введение в веб-разработку на Хекслете.

Публикация на Github Pages с поддержкой Jekyll

Github — популярный хостинг git-репозиториев — поддерживает Jekyll. Это значит, что вы можете разместить всю папку со своим Jekyll-проектом в репозитории, и Github сам будет генерировать HTML-страницы. При этом вам не нужно включать папку _site в репозиторий. Конечные HTML-файлы не будут видны в репозитории ни в каком виде. Этот сервис называется Github Pages.

Подробнее о Git и работе с Github можно узнать из бесплатного курса Системы контроля версий (GIT) на Хекслете.

1. Зарегистрируйтесь на https://github.com/ если еще не сделали этого.
2. Создайте новый репозиторий с именем username.github.io, где username — ваш ник на Github.
3. Инициализируйте репозиторий в директории с Jekyll: git init
4. Добавьте remote: git remote add origin git@github.com:YOUR_USERNAME/YOUR_REPO.git

5. Сделайте коммит и отправьте его в github:

   git add --all
   git commit -m "Initial commit"
   git push -u origin master
   

6. Через несколько мгновений страница станет доступна по вашему адресу https://YOUR_USERNAME.github.io

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

Публикация на Github Pages без поддержки Jekyll

Github Pages позволяет размещать любые HTML-файлы и не работать с Jekyll на стороне Github. Это означает, что вы можете просто размещать на Github свою папку _site. Такой способ позволяет вам использовать любые плагины, потому что генерация конечных файлов происходит на вашем компьютере, а Github выступает в роли простого веб-сервера.

Схема работы идентичная, просто храните в репозитории конечные HTML-файлы вместо Jekyll-проекта.

Подробнее о всех вариантах создания размещения сайтов можно узнать на странице pages.github.com.

Подключение своего домена

Github Pages позволяет подключить сторонний домен. При этом будет работать автоматический редирект 301 с адреса https://YOUR_USERNAME.github.io на ваш домен.

1. Добавьте в репозиторий файл CNAME (без расширения), и внесите в него домен без указания протокола. Например, myblog.com.
2. Если используете домен второго уровня, то на стороне своего DNS-провайдера выставьте ему запись типа ALIAS или ANAME со значением YOUR_USERNAME.github.io; или две записи типа A со значениями 192.30.252.153 и 192.30.252.154. Если используете домен третьего уровня, то добавьте ему запись типа CNAME со значением YOUR_USERNAME.github.io. Подробнее о своих доменах в официальной документации.

Дополнительные возможности

Всё описанное в этом руководстве касается базовых возможностей и настроек по умолчанию. Официальная документация описывает множество дополнительных возможностей, таких как:

• создание «коллекций» постов и страниц
• пагинация
• миграция из других блог-платформ
• подсветка кода и поддержка математических формул в постах
• плагины
• темы
• теги
• парсинг файлов с данными (YAML, JSON, CSV)
• continuous integration

А плагины позволяют еще сильнее расширить возможности системы.