From 74d5082c72206120a6bf5f5e59bf8e82847fa407 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?=
 <bjorn.erik.pedersen@gmail.com>
Date: Mon, 7 Aug 2023 15:43:45 +0200
Subject: [PATCH] Add some .RenderShortcodes docs

---
 content/en/content-management/shortcodes.md |  7 +----
 content/en/variables/page.md                | 31 +++++++++++++++++++++
 2 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md
index 72ddc6a8c..670c5acc8 100644
--- a/content/en/content-management/shortcodes.md
+++ b/content/en/content-management/shortcodes.md
@@ -56,13 +56,8 @@ and a new line with a "quoted string".` */>}}
 
 ### Shortcodes with markdown
 
-In Hugo `0.55` we changed how the `%` delimiter works. Shortcodes using the `%` as the outer-most delimiter will now be fully rendered when sent to the content renderer. They can be part of the generated table of contents, footnotes, etc.
+Shortcodes using the `%` as the outer-most delimiter will be fully rendered when sent to the content renderer. This means that the rendered output from a shortcode can be part of the page's table of contents, footnotes, etc.
 
-If you want the old behavior, you can put the following line in the start of your shortcode template:
-
-```go-html-template
-{{ $_hugo_config := `{ "version": 1 }` }}
-```
 
 ### Shortcodes without markdown
 
diff --git a/content/en/variables/page.md b/content/en/variables/page.md
index 51b0b2fc1..5f6df4e15 100644
--- a/content/en/variables/page.md
+++ b/content/en/variables/page.md
@@ -118,6 +118,9 @@ The following is a list of page-level variables. Many of these will be defined i
 : Raw markdown content without the front matter. Useful with [remarkjs.com](
 https://remarkjs.com)
 
+.RenderShortcodes
+: See [Render Shortcodes](#rendershortcodes).
+
 .ReadingTime
 : The estimated time, in minutes, it takes to read the content.
 
@@ -243,6 +246,34 @@ For this reason, Hugo provides a global `page` function that you can use to acce
 
 There are one caveat with this, and this isn't new, but it's worth mentioning here: There are situations in Hugo where you may see a cached value, e.g. when using `partialCached` or in a shortcode.
 
+## The `.RenderShortcodes` method {#rendershortcodes}
+
+{{< new-in "0.117.0" >}} This renders all the shortcodes in the content, preserving the surrounding markup (e.g. Markdown) as is.
+
+The common use case this is to composing a page from multiple content files while preserving a global context for table of contents and foot notes.
+
+This method is most often used in shortcode templates. A simple example of shortcode template including content from another page would look like:
+
+```go-html-template
+{{ $p := site.GetPage (.Get 0) }}
+{{ $p.RenderShortcodes }}
+```
+
+In the above it's important to understand  and the difference between the two delimiters used when including a shortcode:
+
+* `{{</* myshortcode */>}}` tells Hugo that the rendered shortcode does not need further processing (e.g. it's HTML).
+* `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing (e.g. it's Markdown).
+
+The latter is what you want to use for the include shortcode outlined above:
+
+```md
+## Mypage
+{{%/* include "mypage" */%}}
+``````
+
+
+Also see [Use Shortcodes](/content-management/shortcodes/#use-shortcodes).
+
 ## Page-level params
 
 Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable.