Introduce experimental OpenAPI shortcode

2026-05-22 14:06:48 +02:00
parent 118c5354bb
commit 1d38cd0183
8 changed files with 683 additions and 35 deletions
@@ -0,0 +1,3 @@
+---
+bookCollapseSection: true
+---
@@ -0,0 +1,43 @@
+# Badges
+
+Inline labels for annotating content with status, versions, or metadata.
+
+## Syntax
+
+```tpl
+{{</* badge style="info" title="Hugo" value="0.158" */>}}
+```
+
+## Styles
+
+| Shortcode | Output |
+| -- | -- |
+| `{{</* badge style="info" title="Hugo" value="0.158" */>}}` | {{< badge style="info" title="Hugo" value="0.158" >}} |
+| `{{</* badge style="success" title="Build" value="Passing" */>}}` | {{< badge style="success" title="Build" value="Passing" >}} |
+| `{{</* badge style="warning" title="Coverage" value="25%" */>}}` | {{< badge style="warning" title="Coverage" value="25%" >}} |
+| `{{</* badge style="danger" title="Issues" value="120" */>}}` | {{< badge style="danger" title="Issues" value="120" >}} |
+| | |
+| `{{</* badge style="info" title="Title" */>}}` | {{< badge style="info" title="Title" >}} |
+| `{{</* badge style="info" value="Value" */>}}` | {{< badge style="info" value="Value" >}} |
+| `{{</* badge value="Default" */>}}` | {{< badge value="Default" >}} |
+
+## Use in Links
+
+Wrap a badge in a markdown link
+
+```tpl
+[{{</* badge title="Hugo" value="0.158" */>}}](https://github.com/gohugoio/hugo/releases/tag/v0.158.0)
+```
+
+[{{< badge title="Hugo" value="0.158" >}}](https://github.com/gohugoio/hugo/releases/tag/v0.158.0)
+
+## Parameters
+
+`style`
+: Visual style. One of: `default`, `info`, `success`, `warning`, `danger`, `note`, `tip`, `important`, `caution`.
+
+`title`
+: Label text (left side).
+
+`value`
+: Value text (right side).
@@ -0,0 +1,47 @@
+# Cards
+
+Content blocks with optional images and links. Often used with [Columns](/docs/content/shortcodes/columns/) for grid layouts.
+
+## Syntax
+
+```tpl
+{{</* card [href="..."] [image="..."] [title="..."] */>}}
+Markdown content
+{{</* /card */>}}
+```
+
+## Example
+
+{{% columns %}}
+- {{< card image="placeholder.svg" >}}
+  ### With Image
+  Cards can display an image above the content.
+  {{< /card >}}
+
+- {{< card href="/docs/content/shortcodes/experimental/cards/" >}}
+  ### With Link {anchor=false}
+  When `href` is set, the entire card becomes clickable.
+  {{< /card >}}
+
+- {{< card title="Card" >}}
+  ### Plain Card
+  A basic card with no image or link, used for grouping related content.
+  {{< /card >}}
+{{% /columns %}}
+
+## Parameters
+
+`href`
+: Makes the card a link. The entire card area becomes clickable.
+
+`image`
+: Path to an image displayed above the card content. Supports page resources and URLs.
+
+`title`
+: Accessible title for the card.
+
+`alt`
+: Alt text for the card image.
+
+`class`
+: Additional CSS classes.
@@ -0,0 +1,30 @@
+# Images
+
+Enhanced image display with click-to-expand behavior.
+
+## Syntax
+
+```tpl
+{{</* image src="photo.jpg" alt="Description" title="Caption" loading="lazy" */>}}
+```
+
+## Example
+
+{{< image src="placeholder.svg" alt="Placeholder image" title="Click to expand" loading="lazy" >}}
+
+## Parameters
+
+`src`
+: Path to the image. Supports page resources, site resources, and URLs.
+
+`alt`
+: Alternate text for accessibility.
+
+`title`
+: Caption displayed below the image.
+
+`loading`
+: Loading strategy: `lazy`, `eager`, or `auto`.
+
+`class`
+: Additional CSS classes on the `<img>` element.
@@ -0,0 +1,19 @@
+---
+title: OpenAPI
+---
+
+# OpenAPI
+
+Renders an OpenAPI 3.x specification as a documentation page. Operations are grouped by their first tag.
+
+## Syntax
+
+```tpl
+{{%/* openapi src="spec.json" */%}}
+```
+
+The spec file is loaded via `resources.Get`, so the path is relative to the site's `assets/` directory. JSON and YAML are both supported.
+
+## Example
+
+{{% openapi src="tictactoe.json" %}}