From d54185beffce4711ab93581170c566a0bd69845c Mon Sep 17 00:00:00 2001
From: Joe Mooring <joe.mooring@veriphor.com>
Date: Wed, 15 Mar 2023 11:17:21 -0700
Subject: [PATCH] Clarify markdownify behavior (#1999)

Closes #1992
---
 content/en/functions/markdownify.md | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/content/en/functions/markdownify.md b/content/en/functions/markdownify.md
index 8d8726cff..d222a8eb6 100644
--- a/content/en/functions/markdownify.md
+++ b/content/en/functions/markdownify.md
@@ -1,10 +1,7 @@
 ---
 title: markdownify
 linktitle: markdownify
-description: Runs the provided string through the Markdown processor.
-date: 2017-02-01
-publishdate: 2017-02-01
-lastmod: 2023-02-09
+description: Renders markdown to HTML.
 keywords: [markdown,content]
 categories: [functions]
 menu:
@@ -18,12 +15,21 @@ deprecated: false
 aliases: []
 ---
 
-
 ```
 {{ .Title | markdownify }}
 ```
 
-{{< new-in "0.93.0" >}} **Note**: `markdownify` now supports [Render Hooks] just like [`.Page.RenderString`]. However, if you use more complicated [Render Hooks] relying on page context, use [`.Page.RenderString`] instead. See [GitHub issue #9692](https://github.com/gohugoio/hugo/issues/9692) for more details.
+If the resulting HTML is a single paragraph, Hugo removes the wrapping `p` tags to produce inline HTML as required per the example above.
+
+To keep the wrapping `p` tags for a single paragraph, use the [`.Page.RenderString`] method, setting the `display` option to `block`.
+
+If the resulting HTML is two or more paragraphs, Hugo leaves the wrapping `p` tags in place.
 
-[Render Hooks]: /templates/render-hooks/
 [`.Page.RenderString`]: /functions/renderstring/
+
+{{% note %}}
+Although the `markdownify` function honors [markdown render hooks] when rendering markdown to HTML, use the `.Page.RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details.
+
+[markdown render hooks]: /templates/render-hooks/
+[#9692]: https://github.com/gohugoio/hugo/issues/9692
+{{% /note %}}