навигация выше
+ Спиок разделов

Что оно делает

Jekyll преобразовывает человекочитаемые markdown-тексты в обычный HTML.

Про Markdown у меня есть целая статья. Что бы не повторяться, скажу лишь он значительно ускоряет написание статей. Когда технологии шагнут так далеко, что не смогут обработать весь сегодняшний джаваскрипт, то потомкам останутся читабельные исходники в формате .md.

На GitHub Pages, который предоставляет энтузиастам бесплатный хостинг для документации, используется именно Jekyll. Грех этим не пользоваться! Этот сайт тоже хостится на гитхабе.

Не глядя на то что jekyll всего лишь конвертирует md в html, это вполне себе CMS. Официально предлагается использовать сайт как блог (читай доки), но можно все перестроить под себя. Он не генерирует страницу из БД при каждом запросе пользователя. И это плюс: статика держит невероятные нагрузки!

Минимум для работы с Github Pages

Что бы захостить свой сайт на Github Pages, необходимо:

Еще желательно чуть-чуть разбираться как работает Jekyll и Liquid-скрипты.

Документация по Jekyll: https://jekyllrb.com/docs/pages/

Шаблоны страниц

При создании html, за основу берутся шаблоны. Они хранятся в папке _layouts. Когда выбираешь тему оформления в настройках, то в репозиторий сайта, по сути копируются все файлы темы.

Основной шаблон, который используется по умолчанию для генерации страниц: /_layouts/default.html.
Показательный пример шаблона из темы Cyan: cyan/_layouts/default.html

Полную структуру каталогов можно посмотреть в исходниках тем.
Вот для примера репозиторий темы minima.
Про назначение папок читай на оф.сайте: https://jekyllrb.com/docs/structure/

Инклюд

Некоторые мелкие скрипты удобно подключать черед инклюд

{% include directory-listing.md %}

Файл конфигураци (_config.yml)

В файле _config.yml задаются все основные настройки сайта. Формат написания конфигов YAML. Все заданные здесь параметры будут доступны из любого места сайта через переменную. Например { { site.theme }} выведет название активированной темы. Такие переменныен активно используются в шаблонах страниц.

Через файл _config.yaml можно очень тонко настраивать сайт. Например изменяя парсер markdown файлов или добавляя модули - эдакие доп. обработчики содержимого перед публикацией. На Github Pages поддерживается строго ограниченный список модулей: ссылка

Модули

plugins:
  - jemoji
  - jekyll-paginate
  - jekyll-gist

Параметры Если нужно задать правило для всего сайта. Например разрешить парсинг markdown внутри html

kramdown:
  parse_span_html: true
  parse_block_html: true

Но что бы не сломать сайт, для единичных случаев лучше использоать html-атрибут markdown.

<div markdown="1">_markdown_ **разрешен**</div>

markdown=”1”: markdown разрешен
markdown=”0” _markdown_ **запрещен**

Программирование

Шаблонизация страниц - отнюдь не новая задача. Шаблоны широко используются в популярных CMS. А конструкторы сайтов на них основаны. В Jekyll принципы сохранились прежние, хоть работает немного по другому.

При генерации страниц Jekyll может исполнить сценарии, так называемые liquid-скрипты. Их придумали и реализовали в компании Shopify.

Через Liquid реализованы: Переменные, Условия, Логика, Фильтры, Циклы… В обзем все, что нужно программисту для счастья.

Shopify использовали их для своего eCommerce решения. Пользователям понравилось, вот и Jekyll тоже перенял этот опыт. Liquid напомнил мне о шаблонах TPL в OpenCart, которая написана на языке PHP. Там тоже используются вставки типа { { page.title }}, возможно, это одно и то же.

Дока от Jekyll: https://jekyllrb.com/docs/liquid/
Дока Shopify: https://shopify.github.io/liquid/

Переменные

Дока от Jekyll: https://jekyllrb.com/docs/variables/
Дока от Shopify: https://shopify.github.io/liquid/tags/variable/
Про переменную site.github

Условия, Логика

Условия работают через опереатор 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>

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

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

  1. Экранирования одного символа обратным слешем \*md\*. Распространяется на большинство служебных символов: (* - `)
  2. Экранирования блоков кода { % raw %}{ % endraw %}

Экранировать Liquid скрипт можно обернув его в блок { % raw %}. Этот тег может экранировать что угодно, кроме себя самого :)

{% raw %}	

```
{{ page.title }}
```

{% raw %}	

Коментарии

  1. Нативные комментарии Jekyll { % comment %}{ % endcomment %}
  2. Комментарий HTML <!-- -->
  3. Однострочный комментарий [//]: # "This is comment
{% comment %}Этот комментарий никогда не попадет на страницу {% endcomment %}
<!-- Комментарий HTML не будет отображаться браузером, но сохранится в исходниках страницы. -->

Открой исходник страницы что бы увидеть пасхалку.

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

Полезные фишки

Спойлеры с markdown

<details markdown="1"><summary markdown="0">+ Заголовок спойлера</summary>
Спрятанный внутри текст. Может содержать в себе <b>HTML</b> или **Markdown** разметку
</details>
+ Нажми на меня

Спрятанный внутри текст. Может содержать в себе HTML или Markdown разметку

Содержание

## Содержание
{: .no_toc }
* Table of Content  
{: toc }

Пример для данной страницы в самом верху. Заголовки, которые не нужно вносить в содержание, следует пометить классом {: .no_toc }

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

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

Три символа обратного ударения ( ``` )
Добавлять нужно в начале и в конце блока кода. Это самый простой вариант вставить код на страницу. Чтобы работала подсветка, после трех кавычек нужно указать язык ( ``` html ). Список доступных на официальном сайте.

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

Четыре поробела перед каждой строчкой кода
Что бы добавить сами кавычки, как часть кода, мне пришлось комбинировать методы вставки кода. Перед каждой строчкой добавлены по четыре пробела: cкриншот

Блок highlight

{% highlight html linenos %}
<strong>Hello world!</strong>
{% endhighlight %}
<strong id="test">Hello world!</strong>

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

Комментарии: