Markdown 选项

Jekyll 支持的各种 Markdown 渲染器有时会提供额外的选项。

Kramdown

Kramdown 是 Jekyll 的默认 Markdown 渲染器,通常无需额外配置即可正常工作。但是,它确实支持许多配置选项。

Kramdown 处理器

默认情况下,Jekyll 为 Kramdown 使用 GitHub 风味 Markdown (GFM) 处理器。(指定 input: GFM 也可以,但多余。)GFM 支持一些额外的 Kramdown 选项,由 kramdown-parser-gfm 记录。这些选项可以直接在 Kramdown Jekyll 配置中使用,如下所示

kramdown:
  gfm_quirks: [paragraph_end]

您还可以更改 Kramdown 使用的处理器(如 Kramdown RDocinput 键所指定)。例如,要在 Jekyll 中使用非 GFM Kramdown 处理器,请将以下内容添加到您的配置中。

kramdown:
  input: Kramdown

Kramdown 解析器的文档可在 Kramdown 文档 中找到。如果您使用 Kramdown 或 GFM 以外的 Kramdown 解析器,则需要为其添加 gem。

语法高亮(CodeRay)

要将 CodeRay 语法高亮器与 Kramdown 一起使用,您需要添加对 kramdown-syntax-coderay gem 的依赖项。例如,bundle add kramdown-syntax-coderay。然后,您将能够在 syntax_highlighter 配置中指定 CodeRay

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_offsetsmart_quotes。这些选项在 Kramdown 配置文档 中进行了说明,并且可以像这样添加到你的 Kramdown 配置中

kramdown:
  header_offset: 2
有几个不受支持的 kramdown 选项

请注意,Jekyll 使用 Kramdown 的 HTML 转换器。仅由其他转换器使用的 Kramdown 选项,例如 remove_block_html_tags(由 RemoveHtmlTags 转换器使用),将不起作用。

CommonMark

CommonMark 是 Markdown 语法的合理化版本,用 C 语言实现,因此比用 Ruby 实现的默认 Kramdown 更快。它与原始 Markdown 略有不同,并且不支持在 Kramdown 中实现的所有语法元素,如 块内联属性列表

它有两种形式:带有 jekyll-commonmark 插件的基本 CommonMark 和 GitHub Pages 支持的 GitHub Flavored Markdown

自定义 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