Merge pull request rails#51733 from seanpdoyle/document-yield-head

rafaelfranca · web-flow · commit fca2a5e8a624 · 2024-06-26T17:03:40.000-04:00
Mention `yield :head` in Guides
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>
