Improve this page

Markdown 渲染器配置选项

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

Kramdown

Kramdown 是 Jekyll 的默认 Markdown 渲染器，通常在没有额外配置的情况下也能很好地工作。不过，它确实支持许多配置选项。

Kramdown 处理器

默认情况下，Jekyll 使用 GitHub Flavored Markdown (GFM) 处理器 处理 Kramdown。（指定 input: GFM 是可以的，但冗余。）GFM 支持一些额外的 Kramdown 选项，详见 kramdown-parser-gfm 文档。这些选项可以直接在你的 Kramdown Jekyll 配置中使用，例如：

kramdown:
  gfm_quirks: [paragraph_end]

你也可以更改 Kramdown 使用的处理器（如在 Kramdown RDoc 中为 input 键指定的）。例如，要在 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_offset 和 smart_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 中实现的所有语法元素，例如 Block Inline Attribute Lists。

CommonMark 提供了两种版本：基础 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 文件夹中）或作为 gem 后，在你的 _config.yml 中指定它：

markdown: MyCustomProcessor