---
title: "How Rails builds a page with content_for and yield"
date: 2026-08-20T16:00:00
tags: [rails, ruby, erb, templates, frontend, backend, tech]
description: "How Rails assembles templates: why the layout renders last, where content_for content lives, what happens to a section nobody yields, and how the Rails model differs from Jinja2, Twig, Go html/template, and Handlebars."
embedding:
version: 1
model: "text-embedding-3-small"
dimensions: 512
hash: "sha256:39fddee9975c128585b3e588d347d9a0d185905d5bc90f99557cae6d103e3dd3"
vector: "/h8H7SjR68/5+y339v8k+Ajh/hk6vxgyFvoMEPr2Dt73viL+JAI5EhLw5Oo8Hhr3BE4LE9L/yvCn/RLoMs/0DuYAr+MZGDgCGfkQ3z0rFe0+7sq6Bdfl+ej4zCXRJiIn2zz6JWbOzuJD2dcs+t2Y9vgj5dgNJu3xwgj49v3NG+Dr5jsFDM/iE/wX/kDq8BMV0V/b99jjK//a//OX+vcE3+IE7//E3Nj1sO0D/tsDCdzy0Psi+TDwIN8L/AXlIuwJDCDz+znsIDYSQjnoEx/n6svmCPsQHv7u8RsQLwc8Eh0BIyTp/AZBHuzSIN3K8/7CA/z49hUSz8o2LVL4yPPpwBg5/eXUJeEE1joJ+CzlOEEg/NTJGfnrEuT6Dh/l/u5AMyHqChwDFxox8Q8CFNQZEmLz8BgSDr4nwNnM/EP9HtUHyt4EHAwg8M/y7tDz7vmr4CULLsXT3PYB7uEHFSr79CYk8f0V170W1uruMBFd4R4JKR5T/93L6hASFBIEKhjZAQIF58MLDf3kBiEvMB4zDTQt0tb59TPi7fU/+hQC9dcj2h04A7HR7NIqPsr9vOQvKhQKAuYNDQIt+eoIgQQH3xDA7RXqB/H1QRob7gxk1gL+FCoGMd748e3CzELYCdnRDNf+9vZj9wQV4Ob9MOrz9M/SJ7rjIQkZ8dsiBvkD8P8="
scale: 0.0012291635
---
This article is about one small pair of tools: `yield` and `content_for`. They look trivial until you have to answer "in what order does this actually run" - and especially "what happens if I declare a section that nobody outputs".
Everything below was verified on ActionView 6.1; the experiment code is included.
## The problem
A layout is a frame around the page. The problem is that the frame needs data only the concrete page knows: the tab title, social `` tags, its own CSS, breadcrumbs, buttons in the header.
The naive solution is instance variables:
```erb
<%# app/controllers/products_controller.rb %>
@page_title = "Nike sneakers"
<%# app/views/layouts/application.html.erb %>
<%= @page_title %>
```
It works for strings and falls apart on markup: if the title needs a `` or a link, you start assembling HTML in the controller. `content_for` solves exactly that - it lets a template send a piece of **markup** upward into the layout.
## Three words of vocabulary
```erb
<%# layouts/application.html.erb %>
<%= yield :title %>
<%= yield :head %>
<%= yield %>
<%= yield :sidebar %>
```
```erb
<%# products/show.html.erb %>
<% content_for :title, "Nike sneakers" %>
<% content_for :head do %>
<% end %>
<%= @product.name %>
```
- `yield` with no argument - the main page body;
- `yield :name` - a named slot;
- `content_for :name` - filling a slot (with a block or a string);
- `content_for?(:name)` - checking that the slot is non-empty, without outputting it.
The difference between reading via `yield :name` and `content_for :name` is one practical thing: `yield` works only inside templates, `content_for` also works inside helpers.
## Assembly order: bottom-up
The main non-obvious part: **the layout renders last**. Not first, the way intuition suggests ("frame first, then content").
Here is the Rails code that does it - `actionview/lib/action_view/renderer/template_renderer.rb`:
```ruby
def render_with_layout(view, template, path, locals)
layout = path && find_layout(path, locals.keys, [formats.first])
body = if layout
# yield(layout) here renders the main template.
# Its result is stored in the buffer under the key :layout ...
view.view_flow.set(:layout, yield(layout))
# ... and only then is the layout itself rendered
layout.render(view, locals) { |*name| view._layout_for(*name) }
else
yield
end
build_rendered_template(body, template)
end
```
And bare `yield` inside a layout is simply reading that same buffer (`action_view/context.rb`):
```ruby
def _layout_for(name = nil)
name ||= :layout
view_flow.get(name).html_safe
end
```
So `<%= yield %>` in a layout does not "run" the template. The template has already finished; `yield` pulls a ready string out of a hash under the key `:layout`.
### Experiment
We will build a mini stand on bare ActionView and record the real call order:
```ruby
require "action_view"
require "action_view/testing/resolvers"
TEMPLATES = {
"layouts/app.html.erb" => <<~ERB,
<% $log << "layout: start" %>
HEAD[<%= yield :head %>]
BODY[<%= yield %>]
<% $log << "layout: end" %>
ERB
"page.html.erb" => <<~ERB,
<% $log << "page: start" %>
<% content_for :head do %><% $log << "page: content_for(:head) block" %>meta<% end %>
<% content_for :nowhere do %><% $log << "page: content_for(:nowhere) block" %>wasted<% end %>
<%= render "widget" %>
<% $log << "page: end" %>
ERB
"_widget.html.erb" => <<~ERB,
<% $log << "partial: runs" %>
<% content_for :head do %><% $log << "partial: content_for(:head) block" %>+css<% end %>
ERB
}
$log = []
lookup = ActionView::LookupContext.new([ActionView::FixtureResolver.new(TEMPLATES)])
view = ActionView::Base.with_empty_template_cache.new(lookup, {}, nil)
puts view.render(template: "page", layout: "layouts/app")
puts $log
```
Output:
```
1. page: start
2. page: content_for(:head) block
3. page: content_for(:nowhere) block
4. partial: runs
5. partial: content_for(:head) block
6. page: end
7. layout: start
8. layout: end
HEAD[meta+css]
BODY[
]
```
Notice: `HEAD` stands **above** `BODY` in the finished HTML, even though it ran **later**. Source order and execution order are different things.
You also see that `content_for` from a partial quietly reached the layout and was **appended** to what the page put there: `meta+css`. By default `content_for` concatenates rather than replaces.
```mermaid
sequenceDiagram
participant C as Controller
participant TR as TemplateRenderer
participant V as page.html.erb
participant P as _widget.html.erb
participant F as view_flow (Hash)
participant L as layouts/app.html.erb
C->>TR: render :show
TR->>V: render (template first!)
V->>F: content_for :head -> "meta"
V->>F: content_for :nowhere -> "wasted"
V->>P: render "widget"
P->>F: content_for :head -> += "+css"
P-->>V: widget HTML
V-->>TR: page body
TR->>F: set(:layout, page body)
TR->>L: render (layout last)
L->>F: yield :head -> get(:head)
L->>F: yield -> get(:layout)
L-->>C: finished HTML
```
## Where the content lives
All of this is one `ActionView::OutputFlow` object that lives for exactly one request (`action_view/flows.rb`):
```ruby
class OutputFlow
def initialize
@content = Hash.new { |h, k| h[k] = ActiveSupport::SafeBuffer.new }
end
def get(key)
@content[key]
end
def set(key, value)
@content[key] = ActiveSupport::SafeBuffer.new(value)
end
def append(key, value)
@content[key] << value
end
end
```
A hash of strings, and nothing more. The page body is stored there too, under the reserved key `:layout`, next to your `:head` and `:sidebar`.
`content_for` itself is also simple:
```ruby
def content_for(name, content = nil, options = {}, &block)
if content || block_given?
if block_given?
options = content if content
content = capture(&block) # <-- the block runs HERE, immediately
end
if content
options[:flush] ? @view_flow.set(name, content) : @view_flow.append(name, content)
end
nil
else
@view_flow.get(name).presence
end
end
```
The key line is `capture(&block)`. `capture` swaps the output buffer, runs the block fully, and returns the accumulated string. There is no laziness: the block executes when it is encountered, whether anyone will need it or not.
## What if there is `content_for` but no `yield`?
That was the original question. The answer: **the block runs, HTML is built, the string lands in the hash and sits there until the end of the request, then GC collects it**.
In the experiment above, the `:nowhere` section was never output. Check the buffer state after render:
```ruby
p view.view_flow.content.keys
# => [:head, :nowhere, :layout]
p view.view_flow.content[:nowhere].to_s
# => "wasted"
```
The log line `3. page: content_for(:nowhere) block` is the proof: the work was done. Rails does not analyze the layout ahead of time and does not know which slots anyone is waiting for.
### How much does it cost
Let's measure. 200 "garbage" `content_for` calls inside a loop on one page, 300 renders:
```ruby
Benchmark.bm(22) do |x|
x.report("without content_for") { N.times { run(a) } }
x.report("content_for to nowhere") { N.times { run(b) } }
end
```
```
user system total real
without content_for 0.079012 0.004745 0.083757 ( 0.083810)
content_for to nowhere 0.179607 0.007918 0.187525 ( 0.187599)
allocated objects: without=1852 with garbage content_for=3499
```
The render became 2.2x slower, and almost twice as many objects were allocated. But recalculated per call: **about 1.7 microseconds and ~8 objects**.
Practical takeaway from these numbers:
- **One or two "dead" `content_for` calls on a page are noise.** Against a database query they are invisible. There is nothing to optimize here.
- **`content_for` inside a loop or inside a collection partial is real money.** A thousand table rows, each with its own `content_for`, means milliseconds and GC garbage for no good reason.
- **If the block hits the database or a helper with logic, the cost is no longer in microseconds.** `capture` will run everything honestly, including `@product.reviews.count`.
### The real problem is not performance
It is silence. Rails **gives no warning** if a name does not match:
```erb
<%# layout %>
<%= yield :sidebar %>
<%# view %>
<% content_for :side_bar do %>...<% end %>
```
Tests stay green, the page renders, the sidebar is empty. Debugging this means eyeballing two names in different files.
A couple of practices that help:
```erb
<%# 1. Explicitly show that the slot is optional - and change the layout at the same time %>
<%# 2. A default value %>
<%= content_for?(:title) ? yield(:title) : "Store" %>
```
And if you want guarantees - put slot names into constants or helpers (`page_title(...)` instead of `content_for :title`) so a typo is caught at the Ruby level, not by eye.
### Side effect: accumulation
Because `content_for` appends by default, a partial in a collection will write as many times as there are items:
```ruby
T = {
"layouts/app.html.erb" => "SIDEBAR[<%= yield :sidebar %>]\nBODY[<%= yield %>]",
"page.html.erb" => "<%= render partial: 'item', collection: [1,2,3] %>",
"_item.html.erb" => "<% content_for :sidebar do %>(<%= item %>)<% end %>[<%= item %>]"
}
```
```
SIDEBAR[(1)(2)(3)]
BODY[[1][2][3]]
```
Sometimes that is exactly what you want (collect every modal on the page). Sometimes it is a triple `