all: Change shortcode usage and design to prevent invalid HTML

content/en/methods/shortcode/Get.md

@@ -14,9 +14,9 @@ toc: true
 
 Specify the argument by position or by name. When calling a shortcode within Markdown, use either positional or named argument, but not both.
 
-{{% note %}}
+{{< note >}}
 Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details.
-{{% /note %}}
+{{< /note >}}
 
 ## Positional arguments
 
@@ -46,6 +46,6 @@ To retrieve arguments by name:
 {{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world.
 {{< /code >}}
 
-{{% note %}}
+{{< note >}}
 Argument names are case-sensitive.
-{{% /note %}}
+{{< /note >}}

content/en/methods/shortcode/Inner.md

@@ -46,15 +46,15 @@ Is rendered to:
 </div>
 ```
 
-{{% note %}}
-Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`strings.TrimSpace`] function as shown above to remove both carriage returns and newlines.
+{{< note >}}
+Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`strings.TrimSpace`] function as shown above to remove carriage returns and newlines.
 
 [`strings.TrimSpace`]: /functions/strings/trimspace/
-{{% /note %}}
+{{< /note >}}
 
-{{% note %}}
+{{< note >}}
 In the example above, the value returned by `Inner` is Markdown, but it was rendered as plain text. Use either of the following approaches to render Markdown to HTML.
-{{% /note %}}
+{{< /note >}}
 
 ## Use RenderString
 
@@ -143,9 +143,11 @@ The difference between this and the previous example is subtle but required. Not
  </div>
 ```
 
-{{% note %}}
-When using the `{{%/* */%}}` notation, do not pass the value returned by `Inner` through the `RenderString` method or  the `markdownify` function.
-{{% /note %}}
+{{< note >}}
+Don't process the `Inner` value with `RenderString` or `markdownify` when using [Markdown notation] to call the shortcode.
+
+[Markdown notation]: /content-management/shortcodes/#notation
+{{< /note >}}
 
 [commonmark]: https://commonmark.org/
 [indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks

content/en/methods/shortcode/Ordinal.md

@@ -11,9 +11,9 @@ action:
 
 The `Ordinal` method returns the zero-based ordinal of the shortcode in relation to its parent. If the parent is the page itself, the ordinal represents the position of this shortcode in the page content.
 
-{{% note %}}
+{{< note >}}
 Hugo  increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page.
-{{% /note %}}
+{{< /note >}}
 
 This method is useful for, among other things, assigning unique element IDs when a shortcode is called two or more times from the same page. For example:
 
@@ -47,8 +47,8 @@ Hugo renders the page to:
 <img id="img-001" src="/images/b.jpg" width="600" height="400" alt="">
 ```
 
-{{% note %}}
+{{< note >}}
 In the shortcode template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top level context passed into the template.
 
 [`with`]: /functions/go-template/with/
-{{% /note %}}
+{{< /note >}}

content/en/methods/shortcode/Position.md

@@ -28,6 +28,6 @@ In the absence of a "greeting" argument, Hugo will throw an error message and fa
 ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1"
 ```
 
-{{% note %}}
+{{< note >}}
 The position can be expensive to calculate. Limit its use to error reporting.
-{{% /note %}}
+{{< /note >}}

content/en/methods/shortcode/Scratch.md

@@ -10,7 +10,7 @@ action:
 expiryDate: 2026-11-18 # deprecated 2024-11-18 (soft)
 ---
 
-{{% deprecated-in 0.139.0 %}}
+{{< deprecated-in 0.139.0 >}}
 Use the [`SHORTCODE.Store`] method instead.
 
 This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `SHORTCODE.Store` as soon as possible.
@@ -18,4 +18,4 @@ This is a soft deprecation. This method will be removed in a future release, but
 Beginning with v0.139.0 the `SHORTCODE.Scratch` method is aliased to `SHORTCODE.Store`.
 
 [`SHORTCODE.Store`]: /methods/shortcode/store/
-{{% /deprecated-in %}}
+{{< /deprecated-in >}}

content/en/methods/shortcode/Store.md

@@ -18,12 +18,12 @@ toc: true
 
 Use the `Store` method to create a [scratch pad](g) to store and manipulate data, scoped to the current shortcode. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
 
-{{% note %}}
+{{< note >}}
 With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete.
 
 [assign values to template variables]: https://go.dev/doc/go1.11#text/template
 [`newScratch`]: /functions/collections/newScratch/
-{{% /note %}}
+{{< /note >}}
 
 {{% include "_common/store-methods.md" %}}