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

Jekyll позволяет вам свободно создавать сайты в соответствии с вашими идеями и все это благодаря конфигурационным опциям. Эти опции можно задать в файле _config.yml, расположенном в корне сайта или путем установки нужных флагов при выполнении команд jekyll в терминале.

Настройки конфигурации

Глобальная конфигурация

В таблице ниже перечислены доступные настройки для Jekyll, в виде опций конфигурационного файла и флагов в командной строке:

Каталог-назначение очищается после сборки

Содержимое каталога, в котором собирается сайт по умолчанию автоматически очищается в процессе сборки. Все файлы и каталоги, не созданные Jekyll удаляются. Некоторые файлы можно оставить, используя директиву <keep_files>. Не используйте важный каталог в качестве каталога-назначения; взамен этого копируйте из него нужные файлы.

Опции при сборке в командной строке (build)

Опции команд для сервера

В дополнение к указанным опциям, подкоманда serve может принимать опции подкоманды build.

Не используйте табуляцию в конфигурационных файлах

Это влечет ошибки парсинга или сброс всех настроек на дефолтные значения. Используйте пробелы.

Кастомные заголовки WEBRick

Вы можете добавить их в _config.yml:

# File: _config.yml
webrick:
  headers:
    My-Header: My-Value
    My-Other-Header: My-Other-Value

По умолчанию добавлен лишь один заголовок, отключающий кэширование при разработке, чтобы вы не мучались с агрессивным кэшированием в Chrome на этой стадии.

Задание окружения Jekyll на момент сборки

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

Например, следующее условие в вашем коде обеспечит подключение комментариев Disqus только при сборке в окружении production:

{% if jekyll.environment == "production" %}
   {% include disqus.html %}
{% endif %}

Содержимое блока с таким условием будет выводиться только, если при сборке вы укажите в командной строке переменную production, вот так:

JEKYLL_ENV=production jekyll build

Указывая значения окружения вы можете делать отдельные виды контента доступными только в определенном окружении.

По умолчанию значением JEKYLL_ENV является development, соответственно, если иное значение не задано при сборке, содержимое внутри тегов {% if jekyll.environment == "development" %} будет выводится в готовом сайте.

Вы можете задавать свои значения для окружения, не только development или production. С помощью условий для этих значений вы можете подключать на production такие вещи как комментарии Disqus или Google Analytics. Или, наоборот, выводить кнопку “Edit me in GitHub” только при разработке.

Значения вводных по умолчанию

Использование вводной YAML это один из способов настройки страниц и постов на вашем сайте. Настройка таких вещей как макет по умолчанию, кастомизация заголовка или определение более точных даты и времени поста — все это делается через вводную.

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

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

Ключ defaults содержит массив из пар scope/values, определяющих какие умолчания должны использоваться к определенным файлам/каталогам или типам файлов в каталогах.

Предположим, вы хотите добавить макет ко всем страницам и постам на сайте. Вы добавите следующие строки в файл _config.yml:

defaults:
  -
    scope:
      path: "" # an empty string here means all files in the project
    values:
      layout: "default"

Не забудьте остановить и перезапустить jekyll serve

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

В этом примере мы применяем заданные значения (values) к любому файлу, расположенному по указанному пути. Так как путь указан пустой, эти значения применяются ко всем файлам в проекте. Возможно, вы не хотите назначать макет всем файлам (например, файлам CSS) — вы можете задать тип файла type в ключе scope:

defaults:
  -
    scope:
      path: "" # an empty string here means all files in the project
      type: "posts" # previously `post` in Jekyll 2.2.
    values:
      layout: "default"

Теперь мы задаем макет только для файлов типа posts. К числу доступных типов относятся pages, posts, drafts, а также любые коллекции на сайте. Указание type является опциональным, а path обязательным.

Как упоминалось раннее, вы можете задать множественные пары scope/values для defaults.

defaults:
  -
    scope:
      path: ""
      type: "posts"
    values:
      layout: "my-site"
  -
    scope:
      path: "projects"
      type: "pages" # previously `page` in Jekyll 2.2.
    values:
      layout: "project" # overrides previous default layout
      author: "Mr. Hyde"

С такими настройками все посты будут по умолчанию использовать макет my-site . А любые страницы в каталоге projects/ будут использовать макет project. также в этих страницах переменной liquid page.author будет задано значение Mr. Hyde.

collections:
  - my_collection:
    output: true

defaults:
  -
    scope:
      path: ""
      type: "my_collection" # a collection in your site, in plural form
    values:
      layout: "default"

В этом примере коллекции с названием my_collection задан макет default.

Приоритеты

Jekyll применит все настройки заданные вами в секции defaults файла _config.yml. Однако вы можете переписать эти настройки, указав более специфичный путь.

Вы можете увидеть это в последнем примере. Сначала мы задаем в качестве дефолтного макет my-site. Затем, используя более специфичный путь, мы задаем макет project для файлов в каталоге projects/. Так можно переписать любое значение во вводной поста или страницы.

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

# In _config.yml
...
defaults:
  -
    scope:
      path: "projects"
      type: "pages"
    values:
      layout: "project"
      author: "Mr. Hyde"
      category: "project"
...

# In projects/foo_project.md
---
author: "John Smith"
layout: "foobar"
---
The post text goes here...

В результате после сборки файлу projects/foo_project.md будет задан макет foobar вместо project и автор John Smith вместо Mr. Hyde.

Конфигурация по умолчанию

Jekyll по умолчанию запускается со следующими настройками. Альтернативные настройки этих опций могут быть заданы в файле конфигурации или в командной строке.

Две опции kramdown не поддерживаются

На данный момент опции remove_block_html_tags и remove_span_html_tags не поддерживаются, так как не включены в конвертер kramdown ->HTML

# Расположение
source:      .
destination: ./_site
plugins:     ./_plugins
layouts:     ./_layouts
data_source: ./_data
collections: null

# Обработка текста
safe:         false
include:      [".htaccess"]
exclude:      []
keep_files:   [".git", ".svn"]
encoding:     "utf-8"
markdown_ext: "markdown,mkdown,mkdn,mkd,md"

# Фильтрация контента
show_drafts: null
limit_posts: 0
future:      true
unpublished: false

# Плагины
whitelist: []
gems:      []

# Преобразования
markdown:    kramdown
highlighter: rouge
lsi:         false
excerpt_separator: "\n\n"

# Сервер
detach:  false
port:    4000
host:    127.0.0.1
baseurl: "" # does not include hostname

# Вывод
permalink:     date
paginate_path: /page:num
timezone:      null

quiet:    false
defaults: []

# Процессоры Markdown

rdiscount:
  extensions: []

redcarpet:
  extensions: []

kramdown:
  auto_ids:       true
  footnote_nr:    1
  entity_output:  as_char
  toc_levels:     1..6
  smart_quotes:   lsquo,rsquo,ldquo,rdquo
  enable_coderay: false

  coderay:
    coderay_wrap:              div
    coderay_line_numbers:      inline
    coderay_line_number_start: 1
    coderay_tab_width:         4
    coderay_bold_every:        10
    coderay_css:               style

Опции Markdown

Jekyll поддерживает различные движки рендеринга Markdown, некоторые опции в них можно изменить.

Redcarpet

Redcarpet можно конфигурировать с помощью настройки extensions, указав значением массив со строками. Каждая строка должна быть одним из расширений класса Redcarpet::Markdown, ее наличие в массиве автоматически присваивает этому расширению значение true.

Некоторые особенности есть в обработке Jekyll следующих двух расширений Redcarpet:

• no_fenced_code_blocks — по умолчанию Jekyll подключает расширение fenced_code_blocks (для выделения блоков кода тройными или тройными обратными кавычками), вероятно, потому что использование их на GitHub сделало эти блоки стандартом де-факто. Так как расширение fenced_code_blocks изначально активировано, его передача в массив опций ни на что не влияет, а для его отключения надо передать именно no_fenced_code_blocks — так вы сможете отключить выделение блоков кода этим способом и вернуть обычное выделение четырьмя пробелами. Вы также можете определить используемый язык, указав его после первого ограничителя:

  ```ruby
    # ...ruby code
    ```

При активации подсветки код будет подсвечиваться, при отсутствии подсветчика к элементу <code> будет добавляться атрибут class="LANGUAGE", который может быть использован библиотеками JavaScript для подсветки кода.

• smart — это псевдорасширение активирует SmartyPants, конвертирующее обычные кавычки в фигурные и дефисы в тире.

Все остальные расширения Redcarpet сохраняют свои обычные расширения и никаких других опций для них в Jekyll нет, полный список расширений здесь. Убедитесь, что вы используете нужную версию Redcarpet — в Jekyll на данный момент используется версия 2.2, а такие расширения как footnotes и highlight работают начиная с версии 3.0. Наиболее популярные следующие расширения:

• tables
• no_intra_emphasis
• autolink

Kramdown

Вы можете включить распознавание Github Flavored Markdown, передав опции input значение GFM.

Например, так это делается в _config.yml:

kramdown:
  input: GFM

Собственные процессоры Markdown

Если вы заинтересованы в создании собственного процессора markdown вы можете создать новый класс в пространстве имен Jekyll::Converters::Markdown:

class Jekyll::Converters::Markdown::MyCustomProcessor
  def initialize(config)
    require 'funky_markdown'
    @config = config
  rescue LoadError
    STDERR.puts 'You are missing a library required for Markdown. Please run:'
    STDERR.puts '  $ [sudo] gem install funky_markdown'
    raise FatalException.new("Missing dependency: funky_markdown")
  end

  def convert(content)
    ::FunkyMarkdown.new(content).convert
  end
end

После создания собственного класса и его правильной настройки в каталоге _plugins или как gem, укажите его в _config.yml:

markdown: MyCustomProcessor

Инкрементальная регенерация

Инкрементальная регенерация остается экспериментальной возможностью

Хотя в большинстве случаев инкрементальная сборка будет работать, ее корректная работа во всех случаях не гарантирована. Будьте предельно осторожны при ее использовании и сообщайте о всех не перечисленных ниже проблемах путем открытия задачи (issue) на Github.

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

В текущей имплементации инкрементальная регенерация будет происходить только после изменения страницы или ее зависимостей. На данный момент отслеживаемыми зависимостями являются файлы макетов (layout, заданных во вводной) и подключаемых фрагментов (с помощью тега {% include %}). Простые ссылки на другие документы (типа содержимого переменной site.posts) не рассматриваются как зависимости.

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

Инкрементальная регенерация может быть активирована флагом командной строки --incremental (сокращенно -I) или опцией incremental: true в файле конфигурации.