• 前端
• 开发工具

Middleman 默认将 Markdown 渲染参数在config.rb中全局配置，但在多页面站点中，不同页面往往需要不同的渲染行为（例如正文页开启智能引号、数据表页面开启表格支持）。本指南以仓库中markdown-frontmatter-options-app测试夹具为蓝本，讲解如何在页面 frontmatter 中通过renderer_options对单个 Markdown 页面精确覆盖全局配置，并结合renderers/redcarpet.rb、core_extensions/front_matter.rb、file_renderer.rb等源码说明其底层合并机制，读完即可在实战中为任意页面定制 Markdown 渲染选项。

一、主题定位：从smarty_pants-default.html.markdown这个 fixture 说起

关联文档本身是 Middleman 测试夹具中的一个源文件，位于 smarty_pants-default.html.markdown，全文只有 5 行：

--- layout: false --- "Hello"

它的价值不在于内容，而在于位置与组合：它与smarty_pants-on.html.markdown、smarty_pants-off.html.markdown、tables-default.html.markdown、tables-on.html.markdown、tables-off.html.markdown同处一个目录，构成"全局默认 / 页面开启 / 页面关闭"三组对照实验。夹具应用的 config.rb 只有一行全局配置：

set :markdown, smartypants: true

也就是说：全局层面智能引号（SmartyPants）默认开启，而smarty_pants-default.html.markdown没有在 frontmatter 里声明任何renderer_options，因此它代表"继承全局配置"的基准行为。这一 fixture 组件的存在本身，就是 Middleman "frontmatter 级渲染选项"功能的验收样本。

二、核心机制：renderer_options如何被提取并合并

2.1 frontmatter 中被"特殊对待"的键

Middleman 的 frontmatter 解析并不把所有键都当作普通页面数据。在 front_matter.rb 中，manipulate_resource_list会从 frontmatter 数据里专门抽取一组特殊选项：

opts = fmdata.extract!(:layout, :layout_engine, :renderer_options, :directory_index, :content_type) opts[:renderer_options].symbolize_keys! if opts.key?(:renderer_options)

其中:renderer_options被单独抽出，并强制将键转为 Symbol（例如 YAML 中的smartypants: true会变成:smartypants => true），随后通过resource.add_metadata options: opts挂到该页面的渲染选项上。这就是"每页覆盖"的数据源头。

2.2 合并顺序：页面 frontmatter 覆盖全局set :markdown

真正发生合并的地方在 file_renderer.rb 的render方法中：

# Merge per-extension options from config extension = File.extname(path) options = {}.merge!(opts).merge!(options_for_ext(extension)) ... # Overwrite with frontmatter options options = options.deep_merge(options[:renderer_options]) if options[:renderer_options]

这里的顺序决定了优先级：

1. 先合并调用方传入的opts；
2. 再合并options_for_ext(extension)——该方法从config.rb读取针对该扩展名的配置（见 file_renderer.rb，它遍历 Tilt 中所有处理该扩展名的引擎，将@app.config[mapping_ext.to_sym]合并进来，因此set :markdown, smartypants: true最终会成为:smartypants => true）；
3. 最后，若 frontmatter 中存在renderer_options，用deep_merge覆盖前者。

由于deep_merge是"后者覆盖前者"的深层合并，页面 frontmatter 中的renderer_options拥有最高优先级——这正是smarty_pants-on.html.markdown与smarty_pants-off.html.markdown能独立于全局配置开关智能引号的根本原因。

三、三组对照 fixture 的逐页解读

3.1 智能引号（SmartyPants）：default / on / off

全局配置为set :markdown, smartypants: true，三个页面内容均为"Hello"，仅 frontmatter 不同：

显式开启示例（smarty_pants-on）：

--- layout: false renderer_options: smartypants: true --- "Hello"

显式关闭示例（smarty_pants-off）：

--- layout: false renderer_options: smartypants: false --- "Hello"

3.2 表格（tables）：default / on / off

三个页面正文均为同一段 Markdown 表格语法，仅renderer_options不同：

First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell

注意tables-default的行为与smarty_pants-default相反：由于全局只开启了smartypants而未开启tables，所以默认情况下表格语法不会被渲染为<table>。这组对照很好地说明了"默认继承全局、页面可单独加回或关掉"的语义。

3.3 三个页面共用的细节：layout: false

三个 fixture 都声明layout: false，这是为了隔离测试：不套用任何布局（如default_layout），直接渲染 Markdown 内容，从而让断言只关注渲染选项本身的效果。在实战中，如果你希望某页不套用站点的全局 layout，同样可以这样写。

四、源码级原理：Redcarpet 渲染器如何消费这些选项

4.1 智能引号是"渲染器级"选项

在 redcarpet.rb 的generate_renderer方法中，smartypants被特殊处理——它不是传给Redcarpet::Render::HTML的普通参数，而是通过混入模块动态生成一个子类渲染器：

if options.delete(:smartypants) # Support SmartyPants renderer = Class.new(renderer) do include ::Redcarpet::Render::SmartyPants end end

也就是说，开启智能引号后，"Hello"中的直引号会被 SmartyPants 规则转换为“Hello”（即 “Hello”）。frontmatter 里的smartypants: false会在合并后让该分支不执行，从而得到直引号输出。

4.2 表格是"解析器级"选项

同一个文件继续展示了渲染器其余可选参数的收集（redcarpet.rb）：

possible_render_opts = [:filter_html, :no_images, :no_links, :no_styles, :safe_links_only, :with_toc_data, :hard_wrap, :xhtml, :prettify, :link_attributes] render_options = possible_render_opts.each_with_object({}) do |opt, sum| sum[opt] = options.delete(opt) if options.key?(opt) end renderer.new(render_options)

tables并不在这个列表里，因为它属于Redcarpet::Markdown解析器层面的选项（控制语法解析阶段是否启用 GFM 风格表格），最终会经由_prepare_output中的Redcarpet::Markdown.new(generate_renderer, options).render(data)（redcarpet.rb）传给解析器。frontmatter 中的tables: true/false经过deep_merge进入options后，就能精确控制该页是否启用表格语法。

4.3 引擎前提：选项语义随引擎而异

renderer_options的键含义取决于你使用的 Markdown 引擎。Middleman 通过 markdown.rb 中的define_setting :markdown_engine, :kramdown将默认引擎设为 Kramdown，而after_configuration会根据config[:markdown_engine]分别require并注册 Redcarpet / Kramdown 的 Tilt 模板（markdown.rb）。本 fixture 明确使用了 Redcarpet（feature 场景中set :markdown_engine, :redcarpet），因此smartypants、tables均按 Redcarpet 语义生效。若改用 Kramdown，智能引号同样受支持（参见 markdown_kramdown.feature 中set :markdown, smartypants: true后输出 “Hello” 的断言），但表格等选项的行为可能不同，务必以所选引擎的文档为准。

五、可复现的验收用例：feature 测试如何锁定行为

该功能的全部行为都被 Cucumber 特性文件锁定在 markdown_redcarpet.feature 的 "Redcarpet per-page frontmatter options" 场景中：

Scenario: Redcarpet per-page frontmatter options Given a fixture app "markdown-frontmatter-options-app" And a file named "config.rb" with: """ set :markdown_engine, :redcarpet set :markdown, smartypants: true """ Given the Server is running at "markdown-frontmatter-options-app" When I go to "/smarty_pants-default.html" Then I should see "&ldquo;" When I go to "/smarty_pants-on.html" Then I should see "&ldquo;" When I go to "/smarty_pants-off.html" Then I should not see "&ldquo;" When I go to "/tables-default.html" Then I should not see "<table>" When I go to "/tables-on.html" Then I should see "<table>" When I go to "/tables-off.html" Then I should not see "<table>"

这段测试完整印证了上文所有结论：

• smarty_pants-default：无 frontmatter 覆盖 → 继承全局smartypants: true→ 输出“；
• smarty_pants-on：显式true→ 输出“；
• smarty_pants-off：显式false→不输出“（证明页面级覆盖生效）；
• tables-default：全局未开启 → 不输出<table>；
• tables-on/tables-off：页面级开关分别生效。

这套 fixture 位于 markdown-frontmatter-options-app（config.rb与source/下六个页面），与 feature 共同构成可重复执行的验收用例，是理解该功能最直接的入口。

六、实战要点与注意事项

1. 优先级牢记：页面 frontmatter 的renderer_options通过deep_merge覆盖config.rb中set :markdown的全局配置；未声明的键则继续沿用全局值。需要"多数页面开、个别页面关"时，只需在个别页面的 frontmatter 里写renderer_options: { smartypants: false }即可，无需改动全局。
2. 键需为合法 YAML 键：renderer_options内部使用符号键（源码会执行symbolize_keys!），YAML 中按smartypants: true、tables: true书写即可，Boolean 值务必用true/false而不是字符串。
3. 注意引擎匹配：本功能依赖所选 Markdown 引擎对具体选项的支持。Redcarpet 下smartypants、tables等选项的行为如本文所述；切换引擎后应先小范围验证再全站应用。
4. 可与其他 frontmatter 特殊键组合：renderer_options与layout、layout_engine、directory_index、content_type同属 frontmatter 特殊键（见 front_matter.rb），可在同一页面中组合使用，例如layout: false与renderer_options一起声明。
5. 调试建议：当某页 Markdown 渲染结果与预期不符时，先检查该页 frontmatter 是否意外声明了renderer_options，再对照全局set :markdown配置，按本文第二节的合并顺序逐层排查。

• 前端
• 开发工具