Параметры Markdown

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

Kramdown

Kramdown — средство визуализации Markdown по умолчанию для Jekyll, которое часто хорошо работает без дополнительной настройки. Однако оно поддерживает множество параметров конфигурации.

Процессор Kramdown

По умолчанию Jekyll использует процессор GitHub Flavored Markdown (GFM) для Kramdown. (Указывать input: GFM можно, но это избыточно.) GFM поддерживает несколько дополнительных параметров Kramdown, описанных в документации kramdown-parser-gfm. Эти параметры можно непосредственно использовать в конфигурации Kramdown для Jekyll, например:

kramdown:
  gfm_quirks: [paragraph_end]

Также можно изменить процессор, используемый Kramdown (указанный для ключа input в RDoc Kramdown). Например, чтобы использовать в Jekyll процессор Kramdown без GFM, добавьте в конфигурацию следующее.

kramdown:
  input: Kramdown

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

Подсветка синтаксиса (CodeRay)

Чтобы использовать подсветку синтаксиса CodeRay с Kramdown, необходимо добавить зависимость от гема kramdown-syntax-coderay. Например, bundle add kramdown-syntax-coderay. После этого вы сможете указать CodeRay в конфигурации syntax_highlighter:

kramdown:
  syntax_highlighter: coderay

CodeRay поддерживает несколько собственных параметров конфигурации, описанных в документации kramdown-syntax-coderay; их можно передать как syntax_highlighter_opts, например:

kramdown:
  syntax_highlighter: coderay
  syntax_highlighter_opts:
    line_numbers: table
    bold_every: 5

Дополнительные параметры Kramdown

Kramdown поддерживает множество других относительно сложных параметров, таких как header_offset и smart_quotes. Они описаны в документации по настройке Kramdown, и их можно добавить в конфигурацию Kramdown следующим образом:

kramdown:
  header_offset: 2

Некоторые параметры kramdown не поддерживаются

Обратите внимание, что Jekyll использует конвертер HTML из Kramdown. Параметры Kramdown, используемые только другими конвертерами, например remove_block_html_tags (который используется конвертером RemoveHtmlTags), работать не будут.

CommonMark

CommonMark — рационализированная версия синтаксиса Markdown, реализованная на C, поэтому она быстрее, чем Kramdown по умолчанию, реализованный на Ruby. Она немного отличается от исходного Markdown и не поддерживает все элементы синтаксиса, реализованные в Kramdown, например блочные списки встроенных атрибутов.

Существуют два варианта: базовый CommonMark с плагином jekyll-commonmark и GitHub Flavored Markdown, поддерживаемый GitHub Pages.

Пользовательские процессоры 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 или как гем, укажите его в _config.yml:

markdown: MyCustomProcessor