Middleman 的 Markdown 渲染：用 with_toc_data 自动生成标题锚点 ID-平芜编程栈

前端
开发工具

【免费下载链接】middleman

Hand-crafted frontend development

项目地址：https://gitcode.com/gh_mirrors/mi/middleman

导读

本文以 Middleman 仓库中 with_toc_data.html.markdown 这一测试文档为起点，深入讲解 Middleman 静态站点生成器中 Markdown 渲染引擎的配置机制，重点剖析 Redcarpet 的with_toc_data渲染选项如何为 Markdown 标题自动生成可锚定的id属性，从而支撑页内目录（Table of Contents）、锚点跳转等经典场景。读完本文，你将掌握set :markdown配置的完整写法、渲染选项的底层传递链路，以及如何通过 frontmatter 做单页级别的选项覆盖。

一、一个只有两行标题的测试文档，测的是什么

在 middleman-core/fixtures/markdown-app/source/ 目录下，有一个看似"极简"的 Markdown 文档：

# First Header ## Second Header

它对应了with_toc_data这个 Redcarpet 渲染选项的验收测试。当 Middleman 以 Redcarpet 作为 Markdown 引擎、并开启with_toc_data: true时，这个文档会被渲染成带锚点id的标题节点：

<h1 id="first-header">First Header</h1> <h2 id="second-header">Second Header</h2>

这正是该选项的核心价值：Redcarpet 的 HTML 渲染器会依据标题的文本内容，自动生成小写、以连字符分隔的锚点 ID（First Header→first-header，Second Header→second-header），使页面内的每个标题都成为可被#first-header、#second-header直接定位的锚点目标。

二、开启方式：在 config.rb 中配置 Redcarpet 与渲染选项

Middleman 通过 config.rb 中的set指令完成引擎与渲染选项的声明。整个 markdown-app 夹具的默认配置只有一行：

set :markdown, smartypants: true

而开启with_toc_data的完整配置来自 markdown_redcarpet.feature 中的场景：

set :markdown_engine, :redcarpet set :markdown, filter_html: true, no_images: true, no_links: true, with_toc_data: true, hard_wrap: true, safe_links_only: true, prettify: true

两点关键信息值得注意：

set :markdown_engine, :redcarpet负责选定引擎。Middleman 默认的 Markdown 引擎其实是 Kramdown（见 renderers/markdown.rb 中的define_setting :markdown_engine, :kramdown），因此显式声明引擎是使用 Redcarpet 选项的前提。
set :markdown, ...中传入的键值对会原样进入 Tilt 模板的 options，其中渲染器级（renderer-level）选项会被 Redcarpet 渲染器消费，其余则作为 Markdown 解析选项。

在 markdown_redcarpet.feature 中，验收步骤明确断言了渲染结果：

When I go to "/with_toc_data.html" Then I should see 'id="first-header"' And I should see 'id="second-header"'

这组 Cucumber 断言与上面两行标题的文档一一对应，构成了with_toc_data功能最直接的证据链。

三、源码视角：渲染选项如何被提取并生效

在 renderers/redcarpet.rb 中，Middleman 对 Redcarpet 模板做了封装。核心逻辑位于_prepare_output与generate_renderer：

def _prepare_output Redcarpet::Markdown.new(generate_renderer, options).render(data) end # Renderer Options 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)

结合 redcarpet.rb#L43 可以看到：

渲染器级选项被限定在一个白名单内（possible_render_opts），with_toc_data就在其中；
白名单内的选项会被从统一的 options 中剥离出来，单独传给Redcarpet::Render::HTML的子类构造器（redcarpet.rb#L45-L49）；
剩余选项则作为Redcarpet::Markdown.new(renderer, options)的解析选项。

这也是为什么同一个set :markdown哈希里既能写tables: true（解析器选项）又能写with_toc_data: true（渲染器选项）——两者在源码层被分流到不同消费方。此外，redcarpet.rb#L93 通过::Tilt.register RedcarpetTemplate, 'markdown', 'mkd', 'md'把该模板注册到markdown、mkd、md三类扩展名上。

四、配置到模板的传递链路：config.rb → Tilt

你可能好奇set :markdown, ...的配置是如何到达模板的。链路在 file_renderer.rb 中完成闭环：

options_for_ext(ext)会读取@app.config[mapping_ext.to_sym]，即:markdown这个配置键对应的哈希（file_renderer.rb#L112-L128）；
渲染入口把该哈希合并进options，并注入:context（当前页面上下文，供link_to、image_tag等 Helper 使用）（file_renderer.rb#L52-L56）；
最终通过::Tilt.new(path, 1, options)创建模板实例并渲染（file_renderer.rb#L70-L73）。

换句话说：set :markdown, with_toc_data: true→config[:markdown]→ Tilt options →generate_renderer分流 →Redcarpet::Render::HTML渲染器。理解这条链路后，遇到"选项不生效"类问题，可以按此顺序排查配置键名、引擎选择和选项归属。

五、单页级覆盖：frontmatter 中的 renderer_options

如果不想全局开启，Middleman 支持通过每页 frontmatter 的renderer_options键做局部覆盖。机制在 core_extensions/front_matter.rb#L44-L55 中实现：

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

随后 file_renderer.rb#L60 在渲染时执行深度合并：

options = options.deep_merge(options[:renderer_options]) if options[:renderer_options]

夹具 markdown-frontmatter-options-app 给出了可复制的写法：

--- layout: false renderer_options: tables: true --- First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell

同理，smarty_pants-off.html.markdown 展示了用renderer_options: smartypants: false关闭默认选项的用法。对应场景在 markdown_redcarpet.feature#L127-L146 中有完整的开/关验收断言。这意味着你完全可以在全局开启with_toc_data，并对个别页面选择性关闭或追加其他渲染选项。

六、锚点 ID 的实际应用与注意事项

1. 页内目录（TOC）

拿到带id的标题后，就可以在布局（layout）或页面中生成目录链接。例如：

<ul> <li><a href="#first-header">First Header</a></li> <li><a href="#second-header">Second Header</a></li> </ul>

配合 Middleman 的 URL Helper（link_to、url_for）可进一步支持anchor/fragment参数（见 util/paths.rb#L230-L231 中的options[:anchor] || options[:fragment]），实现跨页带锚点的跳转链接。

2. ID 生成规则

从测试断言可以确定：# First Header→id="first-header"，# Second Header→id="second-header"，即文本小写化、空白转为连字符。这与 Redcarpet 内置的 slug 生成逻辑一致；如果你的标题含中文、特殊符号，生成的 ID 形态取决于引擎的具体实现，建议在构建后检查实际输出，或使用显式锚点（Kramdown 的{: id="..."}内联属性、HTML 手工<a name>等）来保证稳定性。

3. 引擎差异提醒

with_toc_data是Redcarpet 专用的渲染选项。若改用默认的 Kramdown 引擎（见 renderers/kramdown.rb 的KramdownTemplate封装），则需要使用 Kramdown 自身的auto_ids选项，且二者的 ID 生成规则不同。因此，涉及锚点 ID 的配置务必先明确当前:markdown_engine是什么。

七、小结

with_toc_data.html.markdown虽然只有两行标题，却完整覆盖了一条从"配置声明 → 引擎分流 → Tilt 模板 → 渲染器选项 → 验收测试"的 Middleman Markdown 渲染主链路。核心要点回顾：

要点	说明
配置入口	`set :markdown_engine, :redcarpet`+`set :markdown, with_toc_data: true`
选项归属	`with_toc_data`属渲染器级选项，与解析选项混写在同一个哈希中由源码自动分流
传递链路	`config.rb`→`options_for_ext`→ Tilt options →`generate_renderer`（见 file_renderer.rb）
单页覆盖	frontmatter 的`renderer_options`通过`deep_merge`覆盖全局配置
验收标准	标题生成`id="first-header"`、`id="second-header"`形式锚点（markdown_redcarpet.feature）
典型用途	页内目录、锚点跳转、长文导航

想深入验证，可以阅读 markdown_redcarpet.feature 的完整场景（含filter_html、hard_wrap、link_attributes、自定义 renderer 等十余个选项的断言），或直接修改 markdown-app 夹具配置运行构建，观察/with_toc_data.html的产物差异。