Deprecate gist shortcode

content/en/shortcodes/comment.md

@@ -9,7 +9,7 @@ menu:
     parent: shortcodes
     weight:
 weight:
-expiryDate: 2025-01-22 # with v0.142.0 and later use HTML comments instead
+expiryDate: 2025-01-22 # Deprecated in v0.143.0. Use HTML comments instead
 ---
 
 {{% note %}}

content/en/shortcodes/gist.md

@@ -8,13 +8,19 @@ menu:
     parent: shortcodes
     weight:
 weight:
+expiryDate: 2027-01-31 # Deprecated in v0.143.0. Keep this around for a couple of years because it contains instructions for creating a replacement.
 ---
 
-{{% note %}}
+{{% deprecated-in 0.143.0 %}}
-To override Hugo's embedded `gist` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
+The `gist` shortcode was deprecated in version 0.143.0 and will be removed in a future release. To continue embedding GitHub Gists in your content, you'll need to create a custom shortcode:
 
-[source code]: {{% eturl gist %}}
+1. Create a new file: Create a file named `gist.html` within the `layouts/shortcodes` directory.
-{{% /note %}}
+2. Copy the source code: Paste the [original source code] of the gist shortcode into the newly created `gist.html` file.
+
+This will allow you to maintain the functionality of embedding GitHub Gists in your content after the deprecation of the original shortcode.
+
+[original source code]: {{% eturl gist %}}
+{{% /deprecated-in %}}
 
 To display a GitHub gist with this URL:
 
@@ -28,14 +34,8 @@ Include this in your Markdown:
 {{</* gist user 23932424365401ffa5e9d9810102a477 */>}}
 ```
 
-This will display all files in the gist alphabetically by file name.
-
-{{< gist jmooring 23932424365401ffa5e9d9810102a477 >}}
-
 To display a specific file within the gist:
 
 ```text
 {{</* gist user 23932424365401ffa5e9d9810102a477 list.html */>}}
 ```
-
-{{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}}