Использование Jekyll

Russian (Pусский) translation by Anna k.Ivanova (you can also view the original English article)

В предыдущей статье я рассказывал о GitHub Pages и о том, как настроить их в своем репозитории на GitHub. Мы использовали генератор сайта, и я упомянул, что GitHub Pages также поддерживает Jekyll.

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

Что такое Jekyll?

Что такое Jekyll? Вот описание на его сайте:

Jekyll - простой, основанный на блогах, статический генератор сайта.

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

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

Возможно, самое главное что стоит отметить, так это то что в Jekyll постоянные ссылки, категории, страницы, посты и пользовательские шаблоны - все является отдельными независимыми частями.

Вы также можете локально создавать и просматривать свой сайт.

Установка

Jekyll базируется на Ruby, поэтому самый простой способ установить его - использовать RubyGems. Если вы работаете на Mac или Linux, вы можете установить Jekyll через командную строку, запустив gem install jekyll. Если у вас возникнут проблемы во время этой установки, я бы посоветовал проверить руководство по установке.

Если вы работаете в Windows, тогда вам нужна страница документации, относящееся к Windows.

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

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

# Dependencies
markdown:         rdiscount
pygments:         true

# Permalinks
permalink:        pretty

# Server
destination:      _gh_pages
host:             0.0.0.0
port:             9001
baseurl:          /
encoding:         UTF-8

Теперь, когда мы добавили наш файл конфигурации, давайте продолжим настройку структуры проекта.

Структура проекта

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

_layouts

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

Идем дальше и создаем папку _layouts в корне вашего проекта. Далее предположим, что вы хотите создать макет по умолчанию. Вам нужно создать файл default.html внутри папки _layouts. Затем вы сможете ссылаться на макет по умолчанию на разных страницах.

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

<h1>{{page.title}}</h1>

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

{{ content }}

Они используются в файле default.html в примере проекта.

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

_includes

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

Предположим, вы хотите, чтобы заголовок документа был подключаемым компонентом. Сначала вам нужно добавить файл head.html в папку _includes. Затем вы добавляете все, что вам нужно для заголовка документа, как например doctype, метаданные, скрипты и т.д.

Затем вам нужно будет указать этот файл head.html в файле макета default.html. Вы делаете это, используя следующий синтаксис:

{% Include head.html%}

Вы можете видеть, что это используется в файле default.html в примере проекта.

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

Настройка ваших страниц

Теперь, когда у нас есть макет по умолчанию, давайте сделаем нашу первую страницу. Идем дальше и создаем файл index.html в корневой папке вашего проекта. Не беспокойтесь, он не будет переопределять файл index.php вашей темы, если вы используете это для документирования темы WordPress.

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

layout - шаблон, который вы хотите использовать на этой странице
title - заголовок страницы
slug - красивая постоянная ссылка для страницы

Ниже приведен пример добавления в верхнюю часть вашего файла index.html:

---
layout: default
title: Tuts+ GitHub Pages
slug: tuts-github-pages
---

Теперь, когда ваша страница настроена, все, что нам нужно сделать, это добавить контент. Просто добавьте весь HTML-код, который вы хотите отобразить на своей странице.

Создание и обслуживание ваших страниц

Создание и обслуживание ваших страниц осуществляется через командную строку. Откройте свой инструмент командной строки, введите команду jekyll server и нажмите Enter. Вы должны увидеть следующий результат:

Если вы видите правильный вывод, ваши страницы будут созданы и готовы к просмотру. Теперь вы можете просматривать свои страницы, перейдя в своем браузере по адресу http://localhost:9001 или любой другой порт, указанный в файле _config.yml.

Заключение

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

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