Jekyll - CMS для статичных сайтов

Спиок разделов

Jekyll - это типичный генератор статичных сайтов. На вход он берет статьи в формате markdown, а на выходе отдает пачку HTML-файлов. Он по умолчанию работает на серверах Github Pages, значит отпадает необходимость запускать сборку самостоятельно. Все произойдет автоматически - тебе остается только наблюдать за этим как за магией

Первый запуск сайта

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

Все, сайт будет доступен по адресу username.github.io. Можно переходить к наполнению. Обрати внимание, что username надо заменить на твой логин на сайте (напоминание для ракушек)

Темы оформления

Jekyll собирает страницы на основе шаблонов. Они хранятся в папке _layouts. Шаблон представляет собой html-каркас, в который как кирпичики вставляются остальные данные. Дефолтный шаблон - /_layouts/default.html. Темы представляют из себя заготовки структуры сайта. Их можно менять или создать свою на основе предложенных. На моем сайте установлена немного модифицированная тема “Cyan”.

Отладка локально

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

Установить:

Запустить:

При изменении любого из файлов исходников, сайт будет тут же перегенерирован прямо на лету. Очень удобно для отладки. Собранный сайт хранится в папке /_site/. Github Desktop будет выгружать на сервер только исходники - сборка происходит на стороне сервера. В принципе можно заархивировать папку с .html и залить собранный сайт на ближайший хостинг - все будет работать.

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

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

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

Gemfile 
source "https://rubygems.org"

gem "jekyll"

group :jekyll_plugins do
  gem "jekyll-feed"
  gem "jekyll-seo-tag"
  gem "tzinfo"
  gem "tzinfo-data"
  gem "jekyll-theme-cayman"
  gem "jekyll-redirect-from"
  gem "jemoji"
  gem "jekyll-paginate"
  gem "jekyll-gist"
  gem "jekyll-relative-links"
  gem "jekyll-optional-front-matter"
  gem "jekyll-titles-from-headings"
  
end
gem "webrick", "~> 1.7"
# gem 'eventmachine', '1.2.7', git: 'https://github.com/eventmachine/eventmachine.git', tag: 'v1.2.7'
gem 'wdm', '>= 0.1.0'

Настройки сайта хранятся в файле /_config.yml. По умолчанию он пустой, или может содержит одну строку с названием выбранной темы theme: jekyll-theme-cayman. Если какай-то параметр не задан, применяется дефолтное значение. Ниже привожу свой файл конфигурации с комментариями. Я старался максимально заполнить неявно заданные параметры. Вот ссылка на текущий (рабочий) конфиг: перейти

Файл конфигурации 
# Глобальные переменные
title: Домик
#url: ""
#baseurl: ""

# Конфигурация
theme: jekyll-theme-cayman
timezone: Europe/Kiev
markdown: kramdown
highlighter: rouge

# Разрешить рендерить markdown внутри html-тегов
# Но для единичных случаев лучше внедрить html-атрибут {: markdown="1" } или "0"
kramdown:
  parse_span_html: true
  parse_block_html: true
  
# Заранее заданные переменные для файлов
defaults:
- scope:
    type: pages
  values:
    layout: default

# Модули. Список поддерживаемых гитхабом: https://pages.github.com/versions/
plugins:
  - jekyll-redirect-from
  - jemoji
  - jekyll-paginate
  - jekyll-gist
  - rouge
# for github pages compatibility
  - jekyll-optional-front-matter
  - jekyll-titles-from-headings
  - jekyll-relative-links
#  - jekyll-readme-index
#  - jekyll-coffeescript
#  - jekyll-gist
#  - jekyll-github-metadata
#  - jekyll-default-layout

kramdown

kramdown - парсер текстовых файлов с разметкой markdown. В целом нормально работает. У него есть важные особенности, про которые стоит знать. Например можно экранировать служебные символы markdown, что бы вывести их буквальное значение. Для этого перед каждым символом нужно поставить бэкслэш: \*, \_, \-, \`

Содержание - позволяет вывести список разделов на странице.
Заголовки, которые не нужно вносить в содержание, следует пометить классом .no_toc

- ToC
{: toc }
## Этот заголовок попадет в содержание
## А этот будет проигнорирован
{: .no_toc }

Встроить парметр внутрь HTML-тэга

## Include parameters to HTML-tag
{: #id .class markdown="1" }

Отключить парсинг локально. Иногда парсер конфликтует с кусками сырого HTML-кода. В данном случае нужно явно задать нужно ли парсить текст внутри блока.

<details markdown="1"><summary markdown="0">Заголовок спойлера</summary>
Спрятанный внутри спойлера текст
</details>

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

https://kramdown.gettalong.org/options.html

https://www.jekyll.com.cn/docs/configuration/markdown/

Liquid-скрипты

Liquid - язык написания шаблонов. Синтаксис очень похож на TPL-шаблоны в OpenCart, возможно, это одно и то же.

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

Через Liquid реализованы:

Часто используемые скрипты удобно вынести в отдельный файл и подключать черед инклюд:

{% include dir-ls.md %}

Дока от Jekyll: https://jekyllrb.com/docs/liquid/
Доки на оф.сайте (Shopify): https://shopify.github.io/liquid/

Переменные

Вывести переменную: {{ page.title }}. В условиях/циклах использовать без фигурных скобочек

Задать переменную можно так:

Полезное:

Условия

Условия работают через опереатор IF и другие.
Поддерживаемые логические опреаторы: ==, !=, >, <, >=, <=, or, and, contains

{% if site.theme == "manima" and page.layout %}
На странице используется тема Minima со стандартным шаблоном
{% endif %}

Фильтры

Фильтры модифицируют содержимое переменной. Это пожалуй самое мощное средство автоматизации в Jekyll.
Через них можно делать что угодно, от разворачивания массива до кодирования url. Разве что циклы ими н еполучится заменить.

Пример:

{{ "Feelcame" | prepend: "github.com/" }}

github.com/Feelcame

Дока от Jekyll:https://jekyllrb.com/docs/liquid/filters/
Дока от Shopify: https://shopify.github.io/liquid/ (слева в навигации)

Циклы

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

<ul>
  {% for page in site.pages %}
  <li>
	<h2><a href="{{ page.url }}">{{ page.title }}</a></h2>
  </li>
  {% endfor %}
</ul>

Мой скрипт навигации: исходники и пример работы

Экранирование и комментарии

Экранирования блоков кода. Когда нужно отобразить Liquid-скрипт в исходном виде, без его выполнения. Данная штука может экранировать что угодно, кроме себя самого, но есть хак ;-)

{% raw %}
```
{{ page.title }}
```
{% endraw %}

Коментарии
Шаблонизатор Liquid предоставляет возможность отменить вывод части страницы, при этом весь код в нем тоже не будет выполнен.

{% comment %}Этот комментарий никогда не попадет на страницу {% endcomment %}

Подсветка синтаксиса

Чтобы подсветить синтаксис нужно указать язык после открытия блока кода. Список доступных на официальном сайте хайлайтера Rouge. Пример ниже:

``` html
<strong id="test">Hello world!</strong>
```

<strong id="test">Hello world!</strong>

Через liquid-скрипт:

{% highlight html linenos %}
<strong>Hello world!</strong>
{% endhighlight %}

<strong id="test">Hello world!</strong>

Без разукрашивания:

Переадресация

Есть два путя… Первый - permalink, жесткое изменение ссылки на статью. Прямая ссылка автоматически переадесует на permalink. Доки: https://jekyllrb.com/docs/permalinks/

permalink: /:basename

Второй - через плагин jekyll-redirect-from. Для начала нужно его активировать (_config.yml):

plugins:
  - jekyll-redirect-from

Задать переадресацию так:

redirect_from: 
  - /soft/windows/
  - /soft/windows
redirect_to: https://google.com

По указанному пути будут созданы файлы-заглушки с переадресацией. Указывать можно несколько путей сразу. В примере первая строчка (со слешем в конце) создаст страницу index.html внутри папки, а вторая создаст файл windows.html. Этот плагин позволяет также делать переадресацию из текущей страницы

Полезные ссылки

Сторонние темы

💬 Показать комментрарии
или открыть в telegram