From 109efe3ebb13e47a212d813daf7f19b2db8a72dd Mon Sep 17 00:00:00 2001
From: Joe Mooring <joe.mooring@veriphor.com>
Date: Tue, 5 Nov 2024 05:23:03 -0800
Subject: [PATCH] Document the comment shortcode

---
 content/en/content-management/shortcodes.md | 20 ++++++++++++++++++++
 data/embedded_template_urls.toml            |  1 +
 2 files changed, 21 insertions(+)

diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md
index 847ba2bbb..8e345f2fb 100644
--- a/content/en/content-management/shortcodes.md
+++ b/content/en/content-management/shortcodes.md
@@ -74,6 +74,26 @@ You can call shortcodes within other shortcodes by creating your own templates t
 
 Use these embedded shortcodes as needed.
 
+### comment
+
+{{< new-in "0.137.1" >}}
+
+{{% note %}}
+To override Hugo's embedded `comment` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
+
+[source code]: {{% eturl comment %}}
+{{% /note %}}
+
+Use the `comment` shortcode to include comments in your Markdown. Hugo excludes the encapsulated text when rendering your site.
+
+Example usage:
+
+```text
+{{%/* comment */%}} TODO: rewrite the paragraph below. {{%/* /comment */%}}
+```
+
+Although you can call this shortcode using the `{{</* */>}}` notation, computationally it is more efficient to call it using the `{{%/* */%}}` notation as shown above.
+
 ### figure
 
 {{% note %}}
diff --git a/data/embedded_template_urls.toml b/data/embedded_template_urls.toml
index 7bb2e4eee..38b437fe1 100644
--- a/data/embedded_template_urls.toml
+++ b/data/embedded_template_urls.toml
@@ -24,6 +24,7 @@
 'render-codeblock-goat' = '_default/_markup/render-codeblock-goat.html'
 
 # Shortcodes
+'comment' = 'shortcodes/comment.html'
 'figure' = 'shortcodes/figure.html'
 'gist' = 'shortcodes/gist.html'
 'highlight' = 'shortcodes/highlight.html'