From b5f289165e64073b64f59e5a15c75817b263098f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?=
 <bjorn.erik.pedersen@gmail.com>
Date: Mon, 4 Nov 2024 09:30:10 +0100
Subject: [PATCH] Replace HTML comments in markdown with the new comment
 shortcode

See https://github.com/gohugoio/hugo/issues/12997
---
 content/en/content-management/front-matter.md | 4 ++++
 content/en/content-management/summaries.md    | 3 ++-
 content/en/functions/css/TailwindCSS.md       | 2 +-
 content/en/functions/transform/ToMath.md      | 2 +-
 content/en/methods/page/Summary.md            | 6 ++++--
 content/en/methods/site/Taxonomies.md         | 7 ++-----
 content/en/quick-reference/emojis.md          | 4 ++--
 layouts/shortcodes/comment.html               | 2 ++
 8 files changed, 18 insertions(+), 12 deletions(-)
 create mode 100644 layouts/shortcodes/comment.html

diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md
index e73696957..5cbf645a5 100644
--- a/content/en/content-management/front-matter.md
+++ b/content/en/content-management/front-matter.md
@@ -128,6 +128,7 @@ If `true`, the page will not be rendered unless you pass the `--buildDrafts` fla
 [`keywords`]: /methods/page/keywords/
 [taxonomy]: /getting-started/glossary/#taxonomy
 
+{{% comment %}}
 <!-- Added in v0.123.0 but purposefully omitted from documentation. -->
 <!--
 kind
@@ -139,6 +140,7 @@ kind
 lang
 : The language code for this page. This is usually derived from the module mount or filename.
 -->
+{{% /comment %}}
 
 ###### lastmod
 
@@ -182,11 +184,13 @@ Alias to [lastmod](#lastmod).
 
 [output formats]: /templates/output-formats/
 
+{{% comment %}}
 <!-- Added in v0.123.0 but purposefully omitted from documentation. -->
 <!--
 path
 : The canonical page path.
 -->
+{{% /comment %}}
 
 ###### params
 
diff --git a/content/en/content-management/summaries.md b/content/en/content-management/summaries.md
index 678666e1a..07c61d963 100644
--- a/content/en/content-management/summaries.md
+++ b/content/en/content-management/summaries.md
@@ -12,9 +12,10 @@ weight: 160
 toc: true
 aliases: [/content/summaries/,/content-management/content-summaries/]
 ---
-
+{{% comment %}}
 <!-- Do not remove the manual summary divider below. -->
 <!-- If you do, you will break its first literal usage on this page. -->
+{{% /comment %}}
 <!--more-->
 
 You can define a summary manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
diff --git a/content/en/functions/css/TailwindCSS.md b/content/en/functions/css/TailwindCSS.md
index a049d3aaf..828ac9051 100644
--- a/content/en/functions/css/TailwindCSS.md
+++ b/content/en/functions/css/TailwindCSS.md
@@ -16,7 +16,7 @@ toc: true
 
 {{< new-in 0.128.0 >}}
 
-<!-- TODO remove this admonition when feature is stable. -->
+{{% todo %}}remove this admonition when feature is stable.{{% /todo %}}
 
 {{% note %}}
 This is an experimental feature pending the release of TailwindCSS v4.0.
diff --git a/content/en/functions/transform/ToMath.md b/content/en/functions/transform/ToMath.md
index 593043941..bbdc7b289 100644
--- a/content/en/functions/transform/ToMath.md
+++ b/content/en/functions/transform/ToMath.md
@@ -36,7 +36,7 @@ These are a subset of the [KaTeX options].
 output
 : (`string`). Determines the markup language of the output. One of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
 
-    <!-- Indent to prevent splitting the description list. -->
+    {{% comment %}}Indent to prevent splitting the description list.{{% / comment %}}
 
     With `html` and `htmlAndMathml` you must include KaTeX CSS within the `head` element of your base template. For example:
 
diff --git a/content/en/methods/page/Summary.md b/content/en/methods/page/Summary.md
index 161262143..490b201d0 100644
--- a/content/en/methods/page/Summary.md
+++ b/content/en/methods/page/Summary.md
@@ -13,8 +13,10 @@ action:
   signatures: [PAGE.Summary]
 ---
 
-<!-- Do not remove the manual summary divider below. -->
-<!-- If you do, you will break its first literal usage on this page. -->
+{{% comment %}}
+Do not remove the manual summary divider below.
+If you do, you will break its first literal usage on this page.
+{{% /comment %}}
 <!--more-->
 
 You can define a [summary] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
diff --git a/content/en/methods/site/Taxonomies.md b/content/en/methods/site/Taxonomies.md
index d23a0908f..4690e6da5 100644
--- a/content/en/methods/site/Taxonomies.md
+++ b/content/en/methods/site/Taxonomies.md
@@ -9,12 +9,9 @@ action:
   signatures: [SITE.Taxonomies]
 ---
 
-<!-- TODO
+{{% comment %}}
 Show template example: GetTerms
-
-
-
--->
+{{% /comment %}}
 
 Conceptually, the `Taxonomies` method on a `Site` object returns a data structure such&nbsp;as:
 
diff --git a/content/en/quick-reference/emojis.md b/content/en/quick-reference/emojis.md
index 4c31c5d76..69531fd88 100644
--- a/content/en/quick-reference/emojis.md
+++ b/content/en/quick-reference/emojis.md
@@ -53,7 +53,7 @@ To process an emoji shortcode from within a template, use the [`emojify`] functi
 [`emojify`]: /functions/transform/emojify/
 [`RenderString`]: /methods/page/renderstring/
 
-<!-- 
+{{% comment %}}
 To generate the sections below:
 
     git clone https://github.com/ikatyang/emoji-cheat-sheet
@@ -66,7 +66,7 @@ Then...
     1. Copy and paste from README.md
     2. Search/replace (regex) "^###\s" with "## "
     3. Search/replace "^####\s " with "### "
--->
+{{% /comment %}}
 
 ## Table of Contents
 
diff --git a/layouts/shortcodes/comment.html b/layouts/shortcodes/comment.html
new file mode 100644
index 000000000..1952b6f03
--- /dev/null
+++ b/layouts/shortcodes/comment.html
@@ -0,0 +1,2 @@
+{{- $nop := .Inner -}}
+{{- /* "" */ -}}