Mention yield :head in Guides

seanpdoyle · seanpdoyle · commit eb21e2ce23aa · 2024-05-06T17:03:42.000-04:00
Follow up to [#50527][] Highlight the presence of the `yield :head` pattern established by `turbo-rails` and adopted by Rails as part of [#50527][]. New applications will generate their application layout with `yield :head`, so mention that in the documentation. Also include the `yield :head` call in generated plugin layouts. [#50527]: #50527
diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md
@@ -1054,7 +1054,7 @@ Within the context of a layout, `yield` identifies a section where content from
   <head>
   </head>
   <body>
-  <%= yield %>
+    <%= yield %>
   </body>
 </html>
 ```
@@ -1064,15 +1064,17 @@ You can also create a layout with multiple yielding regions:
 ```html+erb
 <html>
   <head>
-  <%= yield :head %>
+    <%= yield :head %>
   </head>
   <body>
-  <%= yield %>
+    <%= yield %>
   </body>
 </html>
 ```
 
-The main body of the view will always render into the unnamed `yield`. To render content into a named `yield`, you use the `content_for` method.
+The main body of the view will always render into the unnamed `yield`. To render content into a named `yield`, call the `content_for` method with the same argument as the named `yield`.
+
+NOTE: Newly generated applications will include `<%= yield :head %>` within the `<head>` element of its `app/views/layouts/application.html.erb` template.
 
 ### Using the `content_for` Method
 
@@ -1091,15 +1093,15 @@ The result of rendering this page into the supplied layout would be this HTML:
 ```html+erb
 <html>
   <head>
-  <title>A simple page</title>
+    <title>A simple page</title>
   </head>
   <body>
-  <p>Hello, Rails!</p>
+    <p>Hello, Rails!</p>
   </body>
 </html>
 ```
 
-The `content_for` method is very helpful when your layout contains distinct regions such as sidebars and footers that should get their own blocks of content inserted. It's also useful for inserting tags that load page-specific JavaScript or CSS files into the header of an otherwise generic layout.
+The `content_for` method is very helpful when your layout contains distinct regions such as sidebars and footers that should get their own blocks of content inserted. It's also useful for inserting page-specific JavaScript `<script>` elements, CSS `<link>` elements, context-specific `<meta>` elements, or any other elements into the `<head>` of an otherwise generic layout.
 
 ### Using Partials
 
@@ -1398,7 +1400,7 @@ Suppose you have the following `ApplicationController` layout:
     <head>
       <title><%= @page_title or "Page Title" %></title>
       <%= stylesheet_link_tag "layout" %>
-      <style><%= yield :stylesheets %></style>
+      <%= yield :head %>
     </head>
     <body>
       <div id="top_menu">Top menu items here</div>
@@ -1413,9 +1415,11 @@ On pages generated by `NewsController`, you want to hide the top menu and add a
 * `app/views/layouts/news.html.erb`
 
     ```html+erb
-    <% content_for :stylesheets do %>
-      #top_menu {display: none}
-      #right_menu {float: right; background-color: yellow; color: black}
+    <% content_for :head do %>
+      <style>
+        #top_menu {display: none}
+        #right_menu {float: right; background-color: yellow; color: black}
+      </style>
     <% end %>
     <% content_for :content do %>
       <div id="right_menu">Right menu items here</div>
diff --git a/railties/lib/rails/generators/rails/plugin/templates/app/views/layouts/%namespaced_name%/application.html.erb.tt b/railties/lib/rails/generators/rails/plugin/templates/app/views/layouts/%namespaced_name%/application.html.erb.tt
@@ -5,6 +5,8 @@
   <%%= csrf_meta_tags %>
   <%%= csp_meta_tag %>
 
+  <%%= yield :head %>
+
   <%%= stylesheet_link_tag    "<%= namespaced_name %>/application", media: "all" %>
 </head>
 <body>
