Как использовать jekyll в проектах


Начнем с самого основного, что такое jekyll? Jekyll - генератор статических сайтов. Это означает, что на вход ему даётся какая-либо информация, а на выходе получается набор HTML-страничек.

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

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

app
--css
----libs
----fonts.min.css
----header.min.css
----main.min.css
--fonts
--img
--jekyll
--js
--libs // Библиотеки js в production не используются, компануются в gulpfile в задаче scripts

html
--modules
----blocks
----content
----system
--index.html

js

sass
--bem
--libs
--_media.sass
--_vars.sass
--fonts.sass
--header.sass
--main.sass

Папками разработки являются html, sass, js непосредственно в корне проекта

Установка gulp проекта

Для наших проектов пред jekyll'овская подготовка включает в себя создание страниц шаблонов, стилизация и подключение всех необходимых файлов.

Готовая gulp сборка размещена на github и имеет следующие команды для управления.

$ npm i -g gulp // Устанавливаем глобально сборщик gulp

Затем в корне проекта необходимо подтянуть зависимости выполнив команду

$ npm i

Для работы над проектом следует запустить сервер и конфигурации

$ gulp default // Запускается локальный сервер и механизм распознавания изменений, компиляция sass, js, html и минификация. Сохранение происходит в папке app

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

_data
_includes
--system
_layouts
_plugins
_site
content
css
--libs
--fonts.min.css
--header.min.css
--main.min.css
fonts
img
js
404.html
Gemfile
index.md

_data - папка в которой хранятся данные, например глобальная навигация

_includes - куски html кода с некоторой функциональностью и в которые можно передавать параметры

_layouts - шаблоны по которым будут выстраиваться страницы

_plugins - хранение плагинов, которые позволяют расширить функционал

_site - здесь размещается готовая сборка проекта

content - страницы сайта в любой иерархии

Установка jekyll проекта

Следующим шагом является установка Ruby, если у вас Windows или Linux, подробнее об этом на официальном сайте. Для mac os установка не требуется, Ruby присутствует из коробки.

Для Ubuntu:

sudo apt-get install ruby-full

Сама установка jekyll простая.

$ gem install bundler jekyll

Затем необходимо перейти в папку где находиться jekyll проект. Получаем так же доступ к командам для управления jekyll

$ bundle install // Подтягиваем все зависимости
$ bundle exec jekyll serve // Запускает сервер и следит за компиляцией статических файлов

Синтаксис jekyll

Jekyll на генерирования страниц использует такие технологии, как Liquid, более подробно можно ознакомиться можно здесь.

Переменные страниц

layout: название шаблона, который находиться в папке _layouts
title: отображение заголовка страницы в браузере SEO (meta)
description: описание страницы для поисковых систем SEO (meta)
view-title: Заголовок страницы во view
view-description: Описание страницы во view
image: Имя файла изображения с расширением для отображения во view
crumbtitle: Заголовок страницы в хлебных крошках
menus: Создание объекта навигации

menus:
  main: Вместо main используется название навигации, следующие параметры относятся к main
    title: Название страницы в навигации
    weight: Порядок страницы в навигации
    identifier: Идентификатор этого пункта меню


Дочерние страницы

menus:
  global: Здесь используется identifier родителя вместо global


Навигация внутри страницы

navigation:
  - title: Название ссылки
    key: Адрес к файлу html или md
    id: Идентификатор
    navigation:
     - title: Название ссылки
       id: Идентификатор


Заполнение страниц

Все наши страницы реализуются в папке content, c необходимыми переменными, например:

---
layout: post
title: Верхняя панель
description: Описание верхней панели сервиса ООО «Держава»
view-title: Верхняя панель сервиса
view-description: Верхняя панель сервиса - это панель помогающая пользователю использующему сервис иметь доступ к системным функциям сервиса

image: top-panel.jpg
crumbtitle: Верхняя панель
menus:
  global:
    title: Верхняя панель
    weight: 1

testtext: entry.html

navigation:
- title: Введение
  key: entry.html
  id: headline-1

- title: Панель
  key: panel.html
  id: headline-2

- title: Логотип
  key: logotype.html
  id: headline-3

- title: Подача заявки
  key: application.html
  id: headline-4

- title: Доп. инфо
  key: info.html
  id: headline-5
  navigation:
    - title: Справка
      key: info/help.html
      id: subheadline-1

    - title: Уведомления
      key: info/notification.html
      id: subheadline-2

- title: Управление аккаунтом
  key: entry.html
  id: headline-6
---

{% include content.html list=page.navigation %} // Использование не обязательно

// Вывод страничек по шаблону 
/*
  <section>
    // файл html указанный в key
  </section>  
*/

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

Затем в файле мы должны принять данные этого блока, например:

{% assign item = include.element %}

<h2 class="article__headline-2" id="{{ item.id }}">{{ item.title }}</h2>