前端开发工具【免费下载链接】middlemanHand-crafted frontend development项目地址https://gitcode.com/gh_mirrors/mi/middleman点击查看免费下载在 Middleman 静态站点生成器中嵌套布局Nested Layout允许开发者把多个布局层层叠加例如主布局 → 外层布局 → 内层布局三级结构从而复用页面外壳、栏目骨架与局部装饰。本文以仓库中的nested-layout-app测试夹具为对象从一份真实的 Markdown 页面配置slim-test.html.markdown出发完整讲解嵌套布局的配置方法、三种模板引擎ERB / HAML / Slim下的写法差异、wrap_layout的底层实现原理以及布局查找与解析顺序帮助你在自己的 Middleman 项目中灵活组合 Markdown 内容与任意模板引擎的布局。一份 fixture 揭示的完整配置骨架仓库中的 slim-test.html.markdown 是一份体量很小但信息完整的页面文件全文如下--- title: New Article Title date: 2011-01-01 layout: inner_slim --- The Article Content它由两部分组成YAML 前置数据Front Mattertitle声明页面标题date声明发布日期layout: inner_slim显式指定页面使用的布局名称——注意这里指定的是一个Slim 引擎的布局而页面正文本身是 Markdown说明布局引擎与内容引擎可以完全解耦。Markdown 正文The Article Content会被 Markdown 渲染器转换成pThe Article Content/p再注入布局链。同一目录下的 haml-test.html.markdown 结构完全一致只是把布局换成了inner_haml而 another.html.markdown 则使用默认的 ERB 布局inner。这三个文件共同证明无论布局是 Slim、HAML 还是 ERBMarkdown 页面都只需要在 front matter 里改一行layout:即可切换正文无需任何改动。三层布局链master → outer → innerinner_slim指向的布局位于 source/layouts/inner_slim.slim但它并非终点而是通过wrap_layout继续向外嵌套--- inner_slim: true --- wrap_layout :outer_slim do h3 I am Inner yield这里出现了两个关键语法 wrap_layout :outer_slim do ... end把当前块捕获的内容h3 I am Inner加上yield注入的页面正文整体作为内容再渲染outer_slim布局 yield输出页面正文 内层布局自身标记的组合内容表示输出内容不转义Slim 中单会进行转义处理。继续追踪 outer_slim.slim--- outer_slim: true --- wrap_layout :master_slim do h2 I am Outer yield外层布局同样用wrap_layout把自身内容包裹进master_slim。最终到达最外层 master_slim.slim--- master_slim: true --- h1 Master Slim p current_page.data.title div yieldmaster_slim不再向外嵌套它是这条布局链的根。注意它通过current_page.data.title读取页面 front matter 中的title——这正是布局链能把数据从页面一路传递到最外层布局的关键。整条链的渲染顺序为页面正文 (Markdown) → inner_slimh3 I am Inner → outer_slimh2 I am Outer → master_slimh1 Master Slim title 全部内容features/nested_layouts.feature 中的验收用例给出了/slim-test.html的精确输出可直接验证上述链条h1Master Slim/h1pNew Article Title/pdivh2I am Outer/h2h3I am Inner/h3pThe Article Content/p三种引擎的嵌套布局写法对比nested-layout-app的layouts目录同时提供了 ERB、HAML、Slim 三套等价布局是学习嵌套布局语法的最佳对照表。以内层 → 外层 → 主布局为例三套写法如下。ERBinner.erb / outer.erb / master.erb% wrap_layout :outer do % I am Inner % yield % % end %% wrap_layout :master do % I am Outer % yield % % end %Master Erb h1% current_page.data.title %/h1 % yield %HAMLinner_haml.haml / outer_haml.haml / master_haml.haml wrap_layout :outer_haml do I am Inner yield wrap_layout :master_haml do I am Outer yieldMaster Haml %h1 current_page.data.title yieldSlim前文已列此处归纳wrap_layout前加yield前加HAML 用。三种引擎的嵌套语义完全一致内层布局把自身内容作为页面交给外层布局外层布局再交给主布局。主布局中的yield最终输出的是整个嵌套好的内容块而current_page.data.title在任何一层布局中都能访问页面级 front matter 数据。wrap_layout 源码原理缓冲区捕获与递归渲染wrap_layout并非模板引擎的内置语法而是 Middleman 在TemplateContext中提供的核心辅助方法实现在 template_context.rbdef wrap_layout(layout_name, block) # Save current buffer for later buf_was save_buffer # Find a layout for this file layout_file ::Middleman::TemplateRenderer.locate_layout(app, layout_name, current_engine) # Get the layout engine extension File.extname(layout_file[:relative_path]) engine extension[1..-1].to_sym # Store last engine for later (could be inside nested renders) self.current_engine engine engine_was current_engine # By default, no content is captured content # Attempt to capture HTML from block begin content capture_html(block) if block_given? ensure # Reset stored buffer, regardless of success restore_buffer(buf_was) end # Render the layout, with the contents of the block inside. concat_safe_content render_file(layout_file, locs, opts) { content } ensure # Reset engine back to templates value, regardless of success self.current_engine engine_was end其工作流程可拆解为五个步骤理解这五步就等于理解了嵌套布局的底层机制保存当前输出缓冲区save_buffer把模板当前已累积的输出暂存起来并清空内部缓冲该方法的定义就在本文件第 4447 行这样后续捕获的内容不会混入已有输出。定位目标布局文件调用TemplateRenderer.locate_layout(app, layout_name, current_engine)按名称在布局目录中查找布局文件查找细节见下一节。切换引擎并捕获块内容根据布局文件扩展名推导引擎如.slim→:slim临时把current_engine切到该引擎用于支持混合引擎渲染随后用capture_html(block)执行do ... end块并捕获其产生的 HTML 字符串作为注入给外层布局的内容。递归渲染外层布局render_file(layout_file, locs, opts) { content }渲染找到的布局文件并把捕获的内容作为块传入——布局内部的yield展开时输出的正是这段内容。由于外层布局内部还可能再调用wrap_layout这一机制天然支持任意深度的递归嵌套。恢复引擎与缓冲区无论渲染成功与否ensure分支都会把current_engine还原为调用前的值、恢复先前保存的缓冲区避免影响外层模板继续渲染。注释中特别提到 could be inside nested renders说明该实现显式考虑了嵌套渲染的深度场景current_engine的保存/恢复保证了外层是 ERB、内层是 Slim 这类混搭组合不会串引擎。布局的查找与解析顺序嵌套布局依赖一套明确的布局解析规则核心实现在 template_renderer.rb。第一步确定布局名称与引擎fetch_layout第 201232 行。布局名称的优先级是渲染选项opts[:layout]通常来自页面 front matter 的layout:字段front_matter.rb 会从 front matter 中抽取:layout等键全局配置app.config[:layout]其默认值为:_auto_layout自动模式见 application.rb。布局引擎的优先级则是渲染选项opts[:layout_engine] 引擎级配置 页面内容引擎。这也解释了为什么 Markdown 页面能使用 Slim 布局——页面指定layout: inner_slim后inner_slim的扩展名决定了引擎为 Slim。第二步在磁盘上定位布局文件locate_layout类方法位于第 3648 行。查找顺序为先在layouts目录下找source/layouts/名称布局目录可通过set :layouts_dir, ...修改默认值为layouts见 application.rb未命中则回到 source 根目录查找同名文件。resolve_template还会按preferred_engine优先匹配指定引擎的文件例如layout: inner在同时存在inner.erb、inner.haml时会优先选与内容引擎一致的找不到才回退到任意扩展名。对于自动模式:_auto_layout系统会尝试查找source/layouts/layout.*一旦显式指定了布局名而文件缺失则抛出TemplateNotFound异常即 Could not locate layout: ...。第三步默认布局兜底。夹具 config.rb 中的一行set :layout, :inner设置了全局默认布局这意味着即便页面 front matter 不写layout:也会自动套用inner布局——这正是data-two.html.erb不指定布局仍能进入布局链的原因。数据在布局链中的传递与 Front Matter 保护嵌套布局场景下页面的 front matter 数据可以在任意一层布局中被读取。夹具中有两个专门验证这一点的页面data-one.html.erbtitle: Page Number One、layout: inner正文为Page #1data-two.html.erbtitle: Page Number Two、layout: outer正文为Page #2。data-one走完整的三层链inner → outer → masterdata-two只走两层outer → master因为其布局是outer而非inner。nested_layouts.feature的最后一个场景 YAML Front Matter isnt clobbered with nested layouts 专门断言多层嵌套后Page Number One、Page #1、I am Inner、I am Outer、Master Erb全部正确输出且访问data-two时I am Inner不会出现——证明嵌套渲染不会破坏 front matter 数据布局链的选择也严格遵循各页面自己的layout:声明。这也带来一个实用技巧公共数据如title写进页面 front matter各层布局通过current_page.data.key读取可避免在布局中硬编码页面信息而像inner_slim: true这类布局自身的标记数据写在布局文件的 front matter 里用于标识布局身份或控制分支逻辑。小结嵌套布局的适用场景与配置清单嵌套布局适合以下典型场景全站统一外壳 栏目模板 局部修饰主布局负责html、head、全局导航与页脚外层布局负责栏目级的两栏/三栏骨架内层布局负责文章页的题头、元信息条等局部装饰。混合引擎团队协作设计师用 Slim/HAML 写布局内容编辑用 Markdown/ERB 写页面引擎互不干扰。差异化页面结构通过 front matter 的layout:字段按页选择不同的嵌套深度同一站点内既有完整三层布局的页面也有只套一层的轻量页面。落地一份嵌套布局项目你只需四步在source/layouts/下按由内到外编写各层布局内层布局用wrap_layout :外层布局名 do ... yield ... end向上嵌套最外层布局用yield承接全部内容在页面 front matter 中写layout: 最内层布局名或在config.rb用set :layout, :name设置全局默认如本夹具的set :layout, :inner任意一层布局内通过current_page.data.key读取页面数据用bundle exec middleman build或middleman server验证输出可对照 nested_layouts.feature 中的期望输出检查渲染结果。所有相关源码与测试均可在此仓库中直接查阅布局渲染入口 template_renderer.rb、wrap_layout实现 template_context.rb、完整三引擎示例目录 nested-layout-app/source/layouts 及验收测试 nested_layouts.feature。赞分享前端开发工具【免费下载链接】middlemanHand-crafted frontend development项目地址https://gitcode.com/gh_mirrors/mi/middleman点击查看免费下载相关推荐Astro Markdown 页面布局机制全解析frontmatter 驱动的 layout 与布局 Props 传递原理Astro Markdown 页面布局机制全解析frontmatter 驱动的 layout 与布局 Props 传递原理 本篇技术指南以 Astro 官方测前端Web框架SSR前端构建如何永久保存微信聊天记录WeChatMsg完整指南让数据真正属于你如何永久保存微信聊天记录WeChatMsg完整指南让数据真正属于你 你是否曾为丢失重要微信对话而懊恼那些与家人的温馨对话、朋友间的珍贵回忆、工作中的关键沟通tldr 别名页面机制解析以保加利亚语 docker-slim 页面为例tldr 别名页面机制解析以保加利亚语 docker slim 页面为例 本指南以 pages.bg/common/docker slim.md 为切入点深文档教程知识库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
