content: Improve documentation for partial decorators

Closes gohugoio#3376

Author: jmooring

content/en/functions/templates/Inner.md

@@ -1,31 +1,71 @@
 ---
 title: templates.Inner
-description: Inner executes the inner content of a partial decorator.
+description: Executes the content block enclosed by a partial call.
 categories: []
-keywords: []
+keywords: [decorator]
 params:
   functions_and_methods:
     aliases: [inner]
     returnType: any
-    signatures: [templates.Inner]
+    signatures: ['templates.Inner [CONTEXT]']
 ---
 
 {{< new-in 0.154.0 />}}
 
-> [!note]
-> We will improve documentation on this ... next year! But take it for a spin.
+The `templates.Inner` function defines the injection point for code nested within a block style partial call. This is the core mechanism used to create a [partial decorator][].
 
-`templates.Inner` can be called zero or more times in a partial template, typically with different data (e.g. pages in a range), and its presence signals a reversal of the execution -- the callee becomes the caller. This only works for partials wrapped in a `with` block (see example). Decorators can be deeply nested, see [this PR](https://github.com/gohugoio/hugoDocs/pull/3330) for an example.
+## Overview
 
-A very simple (and not very useful) example of a [partial decorator](g):
+The `templates.Inner` function acts as a placeholder within a partial template. When a partial is called as a decorator, it captures a block of code from the calling template rather than rendering it immediately. The `templates.Inner` function tells Hugo exactly where to inject that captured content.
 
-```go-html-template
-{{ with partial "b.html" "World" }}Hello {{ . }}{{ end }}
-{{ define "_partials/b.html" }}<b>{{ inner . }}</b>{{ end }}
+This signals a reversal of execution where the callee becomes the caller. The partial manages the outer structure while the calling template remains in control of the inner content.
+
+## Usage
+
+To use this function, the calling template must use the block style syntax with a [`with`][] statement. This allows decorators to be deeply nested.
+
+```go-html-template {file="layouts/home.html"}
+{{ with partial "components/card.html" . }}
+  <p>This content is passed to the partial.</p>
+{{ end }}
 ```
 
-The above renders to:
+Inside the partial, call `templates.Inner` to render the captured block.
 
-```handlebars
-<b>Hello World</b>
+```go-html-template {file="layouts/_partials/components/card.html"}
+<div class="card-frame">
+  {{ templates.Inner . }}
+</div>
 ```
+
+## Arguments
+
+The function accepts one optional argument: the [context](g). This argument determines the value of the dot (`.`) inside the captured block when it is rendered.
+
+- If you provide an argument, such as `{{ templates.Inner .SomeData }}`, the dot inside the captured block is rebound to that specific data.
+- If you do not provide an argument, the captured block uses the context of the caller where the partial was first invoked.
+
+## Context and scope
+
+When using decorators, the `with` statement creates a new [scope](g). Variables defined outside the with block in the calling template are not automatically available inside the captured block.
+
+By passing a context to `templates.Inner`, you ensure that the injected content has access to the correct data even when nested inside multiple layers of wrappers. This is critical when the decorator is used inside a loop or a specific data overlay.
+
+## Repeated execution
+
+A decorator can execute the captured content zero or more times. This is useful when the wrapper needs to repeat the same decoration for a collection of items, such as a list or a grid.
+
+```go-html-template {file="layouts/_partials/list-decorator.html"}
+<ul class="styled-list">
+  {{ range .items }}
+    <li>
+      {{ templates.Inner . }}
+    </li>
+  {{ end }}
+</ul>
+```
+
+In this example, the code provided by the caller is rendered once for every item in the .items collection, with the dot . updated to the current item in each iteration.
+
+[`with`]: /functions/go-template/with/
+[partial decorator]: /templates/partial-decorators/

content/en/quick-reference/glossary/partial-decorator.md

@@ -1,7 +1,8 @@
 ---
 title: partial decorator
+reference: /templates/partial-decorators/
 ---
 
-A _partial decorator_ is a [_partial_](g) template called from any other template including [_shortcodes_](g), [render hooks](g), and other partials.
+A _partial decorator_ is specific type of [_partial_](g) that functions as a [_wrapper component_](g). While a standard partial simply renders data within a fixed template, a decorator uses composition to enclose an entire block of content. It utilizes the [`templates.Inner`][] function as a placeholder to define exactly where that external content should be injected within the wrapper's layout.
 
-  See [templates.Inner](/functions/templates/inner/) for more information.
+  [`templates.Inner`]: /functions/templates/inner/

content/en/quick-reference/glossary/wrapper-component.md

@@ -0,0 +1,6 @@
+---
+title: wrapper component
+reference: /templates/partial-decorators/
+---
+
+A _wrapper component_ is an interface pattern that encloses other content through composition rather than fixed parameters. It provides a reusable shell to handle layout, styling, or logic, allowing the calling template to inject arbitrary content into the component's interior.

content/en/templates/404.md

@@ -4,7 +4,7 @@ linkTitle: 404 templates
 description: Create a template to render a 404 error page.
 categories: []
 keywords: []
-weight: 190
+weight: 200
 ---
 
 To render a 404 error page in the root of your site, create a 404 template in the root of the `layouts` directory. For example:

content/en/templates/embedded.md

@@ -3,7 +3,7 @@ title: Embedded partial templates
 description: Hugo provides embedded partial templates for common use cases.
 categories: []
 keywords: []
-weight: 170
+weight: 180
 aliases: [/templates/internal]
 ---
 

content/en/templates/partial-decorators.md

@@ -0,0 +1,123 @@
+---
+title: Partial decorators
+description: Use partial decorators to create reusable wrapper components that enclose and compose template content.
+categories: []
+keywords: [decorator]
+weight: 170
+---
+
+## Overview
+
+{{% glossary-term "partial decorator" %}}
+
+This approach creates a connection between two files. The calling template provides a block of code and the partial decorator determines where that code appears. This allows the partial to wrap around content without needing to know the specific markup or internal logic of the enclosed block.
+
+## Implementation
+
+To use a partial decorator, use a block-style call in your templates. The [`with`][] statement is required to initiate the partial and create a container for the content. This block can include any valid template code including page methods and functions.
+
+```go-html-template {file="layouts/home.html" copy=true}
+{{ with partial "components/wrapper.html" . }}
+  <p>Everything in this block will be wrapped.</p>
+  <p>{{ .Content | transform.Plainify | strings.Truncate 200 }}</p>
+{{ end }}
+```
+
+Inside the partial template, place the `templates.Inner` function call where the wrapped content should appear.
+
+```go-html-template {file="layouts/_partials/components/wrapper.html" copy=true}
+<div class="wrapper-styling">
+  {{ templates.Inner . }}
+</div>
+```
+
+The `with` statement creates a new [scope](g). Variables defined outside of the `with` block are not available inside it. To use external data within the wrapped content, you must ensure it is part of the [context](g) passed in the partial call.
+
+A key feature of the `templates.Inner` function is its ability to accept a context argument. By passing a context to the function, you define what the dot (`.`) represents inside the wrapped block. This ensures that the injected content has access to the correct data even when nested inside multiple layers of wrappers.
+
+## Benefits of composition
+
+Using partial decorators to build wrapper components provides several advantages:
+
+- It eliminates the need to use separate partials for opening and closing tags when encapsulating a block of code.
+- It prevents parameter bloat because a standard partial no longer requires an extensive list of arguments to account for every possible variation of the content inside it.
+- It enables clean composition where the wrapped block can execute any template logic without the wrapper needing to receive or process that data.
+
+This approach separates container logic from content logic. The wrapper handles structural requirements like specific class hierarchies or CSS grid containers. The calling template retains control over the inner markup and how data is displayed.
+
+## Example
+
+The following templates illustrate how to nest three wrapper components including a section, a column, and a card while passing context through each layer.
+
+The home template initiates the structure by calling the section, column, and card partials as decorators:
+
+```go-html-template {file="layouts/home.html" copy=true}
+{{ $ctx := dict
+  "page" .
+  "label" "Recent Posts"
+  "pageCollection" ((site.GetPage "/posts").RegularPages)
+}}
+
+{{ with partial "components/section.html" $ctx }}
+  <div class="grid-wrapper">
+    {{ range .pageCollection }}
+      {{ with partial "components/column.html" (dict "page" . "class" "col-half") }}
+        {{ with partial "components/card.html" (dict "page" .page "url" .page.RelPermalink "title" .page.LinkTitle) }}
+          <p>
+            {{ .page.Content | plainify | strings.Truncate 240 }}
+          </p>
+        {{ end }}
+      {{ end }}
+    {{ end }}
+  </div>
+{{ end }}
+```
+
+The section component provides a semantic container and an optional heading:
+
+```go-html-template {file="layouts/_partials/components/section.html" copy=true}
+<section class="content-section">
+  {{ with .label }}
+    <h2 class="section-label">{{ . }}</h2>
+  {{ end }}
+  <div class="section-content">
+    {{ templates.Inner . }}
+  </div>
+</section>
+```
+
+The column component manages layout width by applying a CSS class:
+
+```go-html-template {file="layouts/_partials/components/column.html" copy=true}
+<div class="{{ .class | default `column-default` }}">
+  {{ templates.Inner . }}
+</div>
+```
+
+The card component defines the visual boundary for the content:
+
+```go-html-template {file="layouts/_partials/components/card.html" copy=true}
+<div class="card">
+  {{ with .title }}
+    <h2 class="card-title">
+      {{ if $.url }}
+        <a href="{{ $.url }}">{{ . }}</a>
+      {{ else }}
+        {{ . }}
+      {{ end }}
+    </h2>
+  {{ end }}
+
+  <div class="card-body">
+    {{ templates.Inner . }}
+  </div>
+
+  {{ with .url }}
+    <div class="card-footer">
+      <a href="{{ . }}">Read more</a>
+    </div>
+  {{ end }}
+</div>
+```
+
+[`with`]: /functions/go-template/with/

content/en/templates/robots.md

@@ -4,7 +4,7 @@ linkTitle: robots.txt templates
 description: Hugo can generate a customized robots.txt in the same way as any other template.
 categories: []
 keywords: []
-weight: 180
+weight: 190
 aliases: [/extras/robots-txt/]
 ---
 

data/keywords.yaml

@@ -7,10 +7,11 @@
 # will decrease over time, though the initial implementation will require some
 # effort.
 
+- decorator
+- filter
 - highlight
 - menu
-- random
-- resource
 - metadata
 - process
-- filter
+- random
+- resource