Add example OpenAPI document, iframe example, video file, and keys backup CSV

Makefile

@@ -37,6 +37,7 @@ build-preview:
 ## Empty build cache and run on your local machine.
 clean: 
 	hugo --cleanDestinationDir
+	make setup
 	make site
 
 ## Fix Markdown linting issues

content/content-formatting-examples/_index.md

@@ -0,0 +1,43 @@
+---
+title: Content Formatting Examples
+weight: 5
+description: A collection of examples for formatting content, from basic Markdown text to advanced custom components and shortcodes.
+draft: true
+---
+
+The Layer5 Academy platform supports a wide range of shortcodes for enriching your learning content. Shortcodes are reusable template snippets you invoke in Markdown files to generate HTML output. They come from four sources:
+
+1. **Academy Theme** — custom shortcodes built specifically for the Academy platform.
+2. **Hextra** — shortcodes ported from the [Hextra](https://imfing.github.io/hextra/docs/guide/shortcodes/) Hugo theme, namespaced under `hextra/` to avoid conflicts.
+3. **Docsy Theme** — shortcodes inherited from the [Google Docsy](https://www.docsy.dev/) documentation theme.
+4. **Hugo Built-in** — shortcodes included with the [Hugo](https://gohugo.io/) static site generator.
+
+For guidance on creating your own shortcodes, see [Extending the Academy](/cloud/academy/creating-content/extending-the-academy/).
+
+{{< alert type="note" title="Example Page: Not for Production" >}}
+This page will not be published in the [production version](https://cloud.layer5.io/academy/) of the site. It is only visible for local preview and serves as a reference. You can safely delete this page from your repository at any time.
+{{< /alert >}}
+
+## Browse by category
+
+Each example lives in its own page so you can inspect and reuse it independently. Use the sidebar or the links below to navigate.
+
+### [Markdown](./markdown/)
+
+Standard Markdown formatting: text styles, code blocks, lists, tables, images, and footnotes.
+
+### [Hugo Built-in Shortcodes](./hugo-builtins/)
+
+Shortcodes included with Hugo: `figure`, `highlight`, `ref`, `relref`, `param`, `qr`, `details`, and embedded media (`youtube`, `vimeo`, `instagram`, `x`).
+
+### [Docsy Shortcodes](./docsy/)
+
+Shortcodes from the Google Docsy theme: alerts, page info, blocks (cover, lead, section, feature), cards, tabs, comments, conditional text, iframe, imgproc, readfile, and API docs (Redoc, SwaggerUI).
+
+### [Hextra Shortcodes](./hextra/)
+
+Shortcodes ported from the Hextra theme: callouts, cards, details, steps, tabs, file tree, badges, icons, PDF embed, page include, glossary terms, Jupyter notebooks, and asciinema recordings.
+
+### [Academy Theme Shortcodes](./academy-theme/)
+
+Custom shortcodes for the Academy platform: alerts, details, pageinfo, chapterstyle, image, SVG, local video, version labels, CSV tables, Meshery design embeds, and usestatic path resolution.

content/content-formatting-examples/academy-theme/_index.md

@@ -0,0 +1,9 @@
+---
+title: Academy Theme Shortcodes
+linkTitle: Academy Theme
+description: Custom shortcodes built specifically for the Layer5 Academy platform.
+weight: 5
+draft: true
+---
+
+These shortcodes are built specifically for the [Layer5 Academy](https://github.com/layer5io/academy-theme) platform.

content/content-formatting-examples/academy-theme/alerts.md

@@ -0,0 +1,32 @@
+---
+title: Alert
+linkTitle: Alert
+weight: 1
+description: Academy theme alert shortcode with multiple type variants.
+draft: true
+---
+
+The academy-theme `alert` shortcode renders a styled alert box. The `type` parameter controls the color and icon.
+
+```text
+{{</* alert type="note" title="Note" */>}}Alert content with **Markdown** support.{{</* /alert */>}}
+```
+
+**Parameters:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `type` | Alert style: `note`, `info`, `danger`, `warning` | _(none)_ |
+| `title` | Optional title above the alert body | _(none)_ |
+
+**Examples:**
+
+{{< alert title="Note" >}}A plain alert with a title.{{< /alert >}}
+
+{{< alert type="note" title="Note" >}}This alert supports a title and **Markdown**.{{< /alert >}}
+
+{{< alert type="info" title="Info" >}}This is an informational alert.{{< /alert >}}
+
+{{< alert type="danger" title="Danger" >}}This is a danger alert.{{< /alert >}}
+
+{{< alert type="warning" title="Warning" >}}This is a warning alert.{{< /alert >}}

content/content-formatting-examples/academy-theme/chapterstyle.md

@@ -0,0 +1,27 @@
+---
+title: Chapterstyle
+linkTitle: Chapterstyle
+weight: 5
+description: Academy theme chapterstyle shortcode for custom section styling.
+draft: true
+---
+
+The `chapterstyle` shortcode wraps content in a `<div>` with custom inline styles, useful for visually distinguishing chapter or section blocks.
+
+```text
+{{%/* chapterstyle style="padding: 1rem; border: 1px solid #d0d7de; border-radius: 0.75rem; background: #f8fafc;" */%}}
+Your styled content here.
+{{%/* /chapterstyle */%}}
+```
+
+**Parameters:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `style` | CSS style string applied to the wrapper `<div>` | _(none)_ |
+
+**Example:**
+
+{{% chapterstyle style="padding: 1rem; border: 1px solid #d0d7de; border-radius: 0.75rem; background: #f8fafc;" %}}
+This content is wrapped by the `chapterstyle` shortcode. The border, padding, and background color are applied via the `style` parameter. This shortcode is useful for visually grouping related content into a styled container.
+{{% /chapterstyle %}}

content/content-formatting-examples/academy-theme/csvtable-roles.md

@@ -0,0 +1,19 @@
+---
+title: CSV Table Roles
+linkTitle: CSV Table Roles
+weight: 10
+description: Academy theme csvtable-roles shortcode for role-specific permissions tables.
+draft: true
+---
+
+The `csvtable-roles` shortcode reads `static/data/csv/keys-backup.csv` and renders per-role permission tables showing which functions each role has access to.
+
+```text
+{{</* csvtable-roles */>}}
+```
+
+The CSV file must be located at `static/data/csv/keys-backup.csv` with the same format used by `csvtable`.
+
+**Example:**
+
+{{< csvtable-roles >}}

content/content-formatting-examples/academy-theme/csvtable.md

@@ -0,0 +1,19 @@
+---
+title: CSV Table
+linkTitle: CSV Table
+weight: 9
+description: Academy theme csvtable shortcode for rendering permissions tables from CSV data.
+draft: true
+---
+
+The `csvtable` shortcode reads `static/data/csv/keys-backup.csv` and renders a permissions table grouped by category. Each role column shows a check or cross indicator.
+
+```text
+{{</* csvtable */>}}
+```
+
+The CSV file must be located at `static/data/csv/keys-backup.csv` and contain columns for Category, Function, Feature, and various role names.
+
+**Example:**
+
+{{< csvtable >}}

content/content-formatting-examples/academy-theme/embedded-design.md

@@ -0,0 +1,25 @@
+---
+title: Embedded Design
+linkTitle: Embedded Design
+
+description: Example of the meshery-design-embed component shortcode.
+draft: true
+---
+
+The `meshery-design-embed` shortcode renders an interactive Meshery design diagram.
+
+```text
+{{</* meshery-design-embed
+  id="embedded-design-c811e9f4-2522-4eb6-b775-7475545356d8"
+  src="./embedded-design-deploy-meshery-using-meshery.js"
+*/>}}
+```
+
+The rendered output is shown below:
+
+{{< meshery-design-embed
+  id="embedded-design-c811e9f4-2522-4eb6-b775-7475545356d8"
+  src="../embedded-design-deploy-meshery-using-meshery.js"
+>}}
+
+> [Learn more](https://docs.layer5.io/kanvas/designer/embedding-designs/) about embedded designs.

content/content-formatting-examples/academy-theme/image.md

@@ -0,0 +1,9 @@
+---
+title: Image
+linkTitle: Image
+
+description: Render the academy-theme image shortcode.
+draft: true
+---
+
+{{< image src="/examples/images/exoscale-icon.png" alt="Exoscale icon displayed with the academy-theme image shortcode" title="Theme image shortcode" width="140px" radius="12%" >}}

content/content-formatting-examples/academy-theme/lab-intro.md

@@ -0,0 +1,23 @@
+---
+title: Lab Intro
+linkTitle: Lab Intro
+weight: 11
+description: Academy theme lab-intro shortcode for storing lab introduction content.
+draft: true
+---
+
+The `lab-intro` shortcode captures its inner content and stores it on the page scratch pad under the key `lab_intro`. This allows layout templates to retrieve and display lab introduction text in a dedicated section of the page.
+
+```text
+{{%/* lab-intro */%}}
+Welcome to this hands-on lab. In this exercise, you will learn how to deploy a cloud native application using Kubernetes. By the end of this lab, you will be able to create a cluster, deploy workloads, and expose services.
+{{%/* /lab-intro */%}}
+```
+
+**Example:**
+
+{{% lab-intro %}}
+Welcome to this hands-on lab. In this exercise, you will learn how to deploy a cloud native application using Kubernetes. By the end of this lab, you will be able to create a cluster, deploy workloads, and expose services.
+{{% /lab-intro %}}
+
+The content above is stored in the page's scratch pad. Layout templates can access it via `.Page.Scratch.Get "lab_intro"` to render it in a dedicated area.

content/content-formatting-examples/academy-theme/local-video.md

@@ -0,0 +1,26 @@
+---
+title: Local Video
+linkTitle: Local Video
+
+description: Render the academy-theme local-video shortcode.
+draft: true
+---
+
+The `local-video` shortcode embeds an HTML5 `<video>` player for a locally hosted video file.
+
+```text
+{{</* local-video src="/path/to/video.mp4" muted="true" autoplay="true" loop="true" */>}}
+```
+
+**Parameters:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `src` | Path to the video file | _(required)_ |
+| `muted` | Mute the video | `false` |
+| `autoplay` | Auto-play the video | `false` |
+| `loop` | Loop playback | `false` |
+
+{{< alert type="info" title="Sample video not included" >}}
+This shortcode requires a locally hosted `.mp4` video file. Add your video to `static/examples/` and update the `src` path.
+{{< /alert >}}

content/content-formatting-examples/academy-theme/meshery-design-embed/index.md

@@ -0,0 +1,12 @@
+---
+title: Meshery Design Embed
+linkTitle: Meshery Design Embed
+
+description: Render the academy-theme meshery-design-embed shortcode.
+draft: true
+---
+
+{{< meshery-design-embed
+  id="embedded-design-c811e9f4-2522-4eb6-b775-7475545356d8"
+  src="./embedded-design-deploy-meshery-using-meshery.js"
+>}}

content/content-formatting-examples/academy-theme/svg.md

@@ -0,0 +1,25 @@
+---
+title: SVG
+linkTitle: SVG
+weight: 7
+description: Academy theme svg shortcode for inline SVG icons from assets.
+draft: true
+---
+
+The `svg` shortcode renders an inline SVG icon from `assets/icons/{name}.svg`.
+
+```text
+{{</* svg name="layer5-academy-icon" */>}}
+```
+
+**Parameters:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `name` | SVG file name (without extension) from `assets/icons/` | _(required)_ |
+
+**Example:**
+
+The icon renders inline: {{< svg name="layer5-academy-icon" >}}
+
+To add your own SVG icons, place `.svg` files in the `assets/icons/` directory.

content/content-formatting-examples/academy-theme/theme-details.md

@@ -0,0 +1,37 @@
+---
+title: Details (Collapsible)
+linkTitle: Details
+weight: 3
+description: Academy theme details/collapsible shortcode.
+draft: true
+---
+
+The academy-theme `details` shortcode renders a collapsible content block.
+
+```text
+{{</* details summary="Click to expand" open="true" */>}}
+Collapsed content here. Supports **Markdown**.
+{{</* /details */>}}
+```
+
+**Parameters:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `summary` | Clickable summary text | _(empty)_ |
+| `open` | Set to `"true"` to start expanded | collapsed |
+
+**Expanded by default:**
+
+{{< details summary="Academy theme details (open)" open="true" >}}
+This is the academy-theme implementation of the `details` shortcode. It starts expanded because `open="true"` is set.
+
+- Supports **Markdown** formatting
+- Lists, `code`, and _emphasis_ all render correctly
+{{< /details >}}
+
+**Collapsed by default:**
+
+{{< details summary="Click to reveal hidden content" >}}
+This content was hidden until you clicked the summary. The `details` shortcode is useful for FAQs, optional information, or reducing page length.
+{{< /details >}}

content/content-formatting-examples/academy-theme/theme-pageinfo.md

@@ -0,0 +1,19 @@
+---
+title: Pageinfo
+linkTitle: Pageinfo
+weight: 4
+description: Academy theme pageinfo shortcode for page-level notices.
+draft: true
+---
+
+The academy-theme `pageinfo` shortcode renders a page-level notice box.
+
+```text
+{{</* pageinfo */>}}Notice content with **Markdown** support.{{</* /pageinfo */>}}
+```
+
+**Example:**
+
+{{< pageinfo >}}
+This block uses the academy-theme implementation of `pageinfo`. It is useful for rendering page-level status notices, such as deprecation warnings or draft indicators.
+{{< /pageinfo >}}

content/content-formatting-examples/academy-theme/usestatic.md

@@ -0,0 +1,15 @@
+---
+title: Usestatic
+linkTitle: Usestatic
+
+description: Render the academy-theme usestatic shortcode.
+draft: true
+---
+
+The `usestatic` shortcode resolves a tenant-scoped static file path, prefixing it with the organization UUID configured in `params.defined_org`.
+
+```text
+{{</* usestatic "images/exoscale-icon.png" */>}}
+```
+
+Resolved tenant-scoped static path: {{< usestatic "images/exoscale-icon.png" >}}

content/content-formatting-examples/academy-theme/version.md

@@ -0,0 +1,17 @@
+---
+title: Version
+linkTitle: Version
+weight: 8
+description: Academy theme version shortcode for version labels.
+draft: true
+---
+
+The `version` shortcode renders a styled version label.
+
+```text
+{{</* version color="Theme version label:" */>}} academy-theme sample output{{</* /version */>}}
+```
+
+**Example:**
+
+{{< version color="Theme version label:" >}} academy-theme sample output{{< /version >}}