From af365ff027e2150235e05770e7d9e266be67706e Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Thu, 2 Apr 2026 11:13:44 -0500 Subject: [PATCH 1/6] Shortcode examples Signed-off-by: Lee Calcote --- .github/build/Makefile.core.mk | 5 +- .gitignore | 1 + assets/icons/exoscale-demo.svg | 1 + content/content-formatting-examples/_index.md | 43 ++ .../academy-theme/_index.md | 9 + .../academy-theme/alerts.md | 32 + .../academy-theme/chapterstyle.md | 27 + .../academy-theme/csvtable-roles.md | 19 + .../academy-theme/csvtable.md | 19 + .../academy-theme/embedded-design.md | 25 + .../academy-theme/image.md | 9 + .../academy-theme/lab-intro.md | 23 + .../academy-theme/local-video.md | 26 + ...ded-design-deploy-meshery-using-meshery.js | 150 ++++ .../meshery-design-embed/index.md | 12 + .../academy-theme/svg.md | 25 + .../academy-theme/theme-details.md | 37 + .../academy-theme/theme-pageinfo.md | 19 + .../academy-theme/usestatic.md | 15 + .../academy-theme/version.md | 17 + .../docsy/_index.md | 9 + .../blocks-cover-link-down/background.png | Bin 0 -> 19512 bytes .../docsy/blocks-cover-link-down/index.md | 13 + .../docsy/blocks-cover-link-down/logo.png | Bin 0 -> 5049 bytes .../docsy/blocks-lead.md | 11 + .../docsy/blocks-section-feature.md | 13 + .../content-formatting-examples/docsy/card.md | 11 + .../docsy/cardpane.md | 19 + .../docsy/comment.md | 19 + .../docsy/conditional-text.md | 29 + .../docsy/docsy-alert.md | 24 + .../docsy/docsy-pageinfo.md | 23 + .../docsy/iframe.md | 9 + .../docsy/imgproc/index.md | 9 + .../docsy/imgproc/logo.png | Bin 0 -> 5049 bytes .../docsy/readfile.md | 15 + .../docsy/redoc.md | 9 + .../docsy/swaggerui.md | 9 + .../docsy/tabpane-tab.md | 19 + .../docsy/tabpanel.md | 37 + .../hextra/_index.md | 9 + .../{ => hextra/asciinema}/demo.cast | 0 .../hextra/asciinema/index.md | 29 + .../hextra/badge.md | 31 + .../hextra/callout.md | 48 ++ .../hextra/cards.md | 49 ++ .../hextra/details.md | 37 + .../hextra/filetree.md | 46 ++ .../hextra/icon.md | 17 + .../hextra/include.md | 23 + .../jupyter}/example-notebook.ipynb | 0 .../hextra/jupyter/index.md | 24 + .../hextra/pdf/index.md | 23 + .../{ => hextra/pdf}/sample.pdf | Bin .../hextra/steps.md | 45 ++ .../hextra/tabs.md | 69 ++ .../hextra/term.md | 31 + .../hugo-builtins/_index.md | 9 + .../hugo-builtins/figure.md | 9 + .../hugo-builtins/highlight.md | 17 + .../hugo-builtins/hugo-details.md | 11 + .../hugo-builtins/instagram.md | 9 + .../hugo-builtins/param.md | 9 + .../hugo-builtins/qr.md | 9 + .../hugo-builtins/ref.md | 9 + .../hugo-builtins/relref.md | 9 + .../hugo-builtins/vimeo.md | 9 + .../hugo-builtins/x.md | 9 + .../hugo-builtins/youtube.md | 9 + content/content-formatting-examples/index.md | 696 ------------------ .../markdown/_index.md | 9 + .../markdown/code.md | 13 + .../markdown/footnotes.md | 11 + .../markdown/image-styling.md | 26 + .../markdown/lists.md | 25 + .../markdown/markdown-basics.md | 11 + .../markdown/responsive-images.md | 17 + .../markdown/tables.md | 20 + content/include-snippet/index.md | 2 +- static/data/csv/keys-backup.csv | 10 + static/examples/frame-example.html | 28 + static/examples/images/deploy.png | Bin 0 -> 19512 bytes static/examples/images/exoscale-icon.png | Bin 0 -> 5049 bytes static/examples/images/exoscale-icon.svg | 1 + static/examples/images/kubernetes-icon.svg | 1 + static/examples/openapi/example.json | 69 ++ 86 files changed, 1630 insertions(+), 700 deletions(-) create mode 100644 assets/icons/exoscale-demo.svg create mode 100644 content/content-formatting-examples/_index.md create mode 100644 content/content-formatting-examples/academy-theme/_index.md create mode 100644 content/content-formatting-examples/academy-theme/alerts.md create mode 100644 content/content-formatting-examples/academy-theme/chapterstyle.md create mode 100644 content/content-formatting-examples/academy-theme/csvtable-roles.md create mode 100644 content/content-formatting-examples/academy-theme/csvtable.md create mode 100644 content/content-formatting-examples/academy-theme/embedded-design.md create mode 100644 content/content-formatting-examples/academy-theme/image.md create mode 100644 content/content-formatting-examples/academy-theme/lab-intro.md create mode 100644 content/content-formatting-examples/academy-theme/local-video.md create mode 100644 content/content-formatting-examples/academy-theme/meshery-design-embed/embedded-design-deploy-meshery-using-meshery.js create mode 100644 content/content-formatting-examples/academy-theme/meshery-design-embed/index.md create mode 100644 content/content-formatting-examples/academy-theme/svg.md create mode 100644 content/content-formatting-examples/academy-theme/theme-details.md create mode 100644 content/content-formatting-examples/academy-theme/theme-pageinfo.md create mode 100644 content/content-formatting-examples/academy-theme/usestatic.md create mode 100644 content/content-formatting-examples/academy-theme/version.md create mode 100644 content/content-formatting-examples/docsy/_index.md create mode 100644 content/content-formatting-examples/docsy/blocks-cover-link-down/background.png create mode 100644 content/content-formatting-examples/docsy/blocks-cover-link-down/index.md create mode 100644 content/content-formatting-examples/docsy/blocks-cover-link-down/logo.png create mode 100644 content/content-formatting-examples/docsy/blocks-lead.md create mode 100644 content/content-formatting-examples/docsy/blocks-section-feature.md create mode 100644 content/content-formatting-examples/docsy/card.md create mode 100644 content/content-formatting-examples/docsy/cardpane.md create mode 100644 content/content-formatting-examples/docsy/comment.md create mode 100644 content/content-formatting-examples/docsy/conditional-text.md create mode 100644 content/content-formatting-examples/docsy/docsy-alert.md create mode 100644 content/content-formatting-examples/docsy/docsy-pageinfo.md create mode 100644 content/content-formatting-examples/docsy/iframe.md create mode 100644 content/content-formatting-examples/docsy/imgproc/index.md create mode 100644 content/content-formatting-examples/docsy/imgproc/logo.png create mode 100644 content/content-formatting-examples/docsy/readfile.md create mode 100644 content/content-formatting-examples/docsy/redoc.md create mode 100644 content/content-formatting-examples/docsy/swaggerui.md create mode 100644 content/content-formatting-examples/docsy/tabpane-tab.md create mode 100644 content/content-formatting-examples/docsy/tabpanel.md create mode 100644 content/content-formatting-examples/hextra/_index.md rename content/content-formatting-examples/{ => hextra/asciinema}/demo.cast (100%) create mode 100644 content/content-formatting-examples/hextra/asciinema/index.md create mode 100644 content/content-formatting-examples/hextra/badge.md create mode 100644 content/content-formatting-examples/hextra/callout.md create mode 100644 content/content-formatting-examples/hextra/cards.md create mode 100644 content/content-formatting-examples/hextra/details.md create mode 100644 content/content-formatting-examples/hextra/filetree.md create mode 100644 content/content-formatting-examples/hextra/icon.md create mode 100644 content/content-formatting-examples/hextra/include.md rename content/content-formatting-examples/{ => hextra/jupyter}/example-notebook.ipynb (100%) create mode 100644 content/content-formatting-examples/hextra/jupyter/index.md create mode 100644 content/content-formatting-examples/hextra/pdf/index.md rename content/content-formatting-examples/{ => hextra/pdf}/sample.pdf (100%) create mode 100644 content/content-formatting-examples/hextra/steps.md create mode 100644 content/content-formatting-examples/hextra/tabs.md create mode 100644 content/content-formatting-examples/hextra/term.md create mode 100644 content/content-formatting-examples/hugo-builtins/_index.md create mode 100644 content/content-formatting-examples/hugo-builtins/figure.md create mode 100644 content/content-formatting-examples/hugo-builtins/highlight.md create mode 100644 content/content-formatting-examples/hugo-builtins/hugo-details.md create mode 100644 content/content-formatting-examples/hugo-builtins/instagram.md create mode 100644 content/content-formatting-examples/hugo-builtins/param.md create mode 100644 content/content-formatting-examples/hugo-builtins/qr.md create mode 100644 content/content-formatting-examples/hugo-builtins/ref.md create mode 100644 content/content-formatting-examples/hugo-builtins/relref.md create mode 100644 content/content-formatting-examples/hugo-builtins/vimeo.md create mode 100644 content/content-formatting-examples/hugo-builtins/x.md create mode 100644 content/content-formatting-examples/hugo-builtins/youtube.md delete mode 100644 content/content-formatting-examples/index.md create mode 100644 content/content-formatting-examples/markdown/_index.md create mode 100644 content/content-formatting-examples/markdown/code.md create mode 100644 content/content-formatting-examples/markdown/footnotes.md create mode 100644 content/content-formatting-examples/markdown/image-styling.md create mode 100644 content/content-formatting-examples/markdown/lists.md create mode 100644 content/content-formatting-examples/markdown/markdown-basics.md create mode 100644 content/content-formatting-examples/markdown/responsive-images.md create mode 100644 content/content-formatting-examples/markdown/tables.md create mode 100644 static/data/csv/keys-backup.csv create mode 100644 static/examples/frame-example.html create mode 100644 static/examples/images/deploy.png create mode 100644 static/examples/images/exoscale-icon.png create mode 100644 static/examples/images/exoscale-icon.svg create mode 100644 static/examples/images/kubernetes-icon.svg create mode 100644 static/examples/openapi/example.json diff --git a/.github/build/Makefile.core.mk b/.github/build/Makefile.core.mk index e44cd0d7..6b440b0e 100644 --- a/.github/build/Makefile.core.mk +++ b/.github/build/Makefile.core.mk @@ -23,10 +23,9 @@ GIT_STRIPPED_VERSION=$(shell git describe --tags `git rev-list --tags --max-coun REMOTE_PROVIDER="Layer5" LOCAL_PROVIDER="None" -GOVERSION = 1.23 +GOVERSION = 1.25.5 GOPATH = $(shell go env GOPATH) GOBIN = $(GOPATH)/bin -KEYS_PATH="../../server/permissions/keys.csv" SHELL := /usr/bin/env bash -o pipefail @@ -36,7 +35,7 @@ SHELL := /usr/bin/env bash -o pipefail # All Adapters # ADAPTER_URLS := "localhost:10000 localhost:10001 localhost:10002 localhost:10004 localhost:10005 localhost:10006 localhost:10007 localhost:10009 localhost:10010 localhost:10012" # No Adapters -ADAPTER_URLS := "localhost:10000 localhost:10001 localhost:10012 localhost:10013" +# ADAPTER_URLS := "localhost:10000 localhost:10001 localhost:10012 localhost:10013" #----------------------------------------------------------------------------- # Providers (Add your provider here. See https://docs.meshery.io/extensibility/providers) diff --git a/.gitignore b/.gitignore index edd9ef8b..14bc7348 100644 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,4 @@ public/ resources/ node_modules/ .hugo_build.lock +.DS_Store \ No newline at end of file diff --git a/assets/icons/exoscale-demo.svg b/assets/icons/exoscale-demo.svg new file mode 100644 index 00000000..ffff086e --- /dev/null +++ b/assets/icons/exoscale-demo.svg @@ -0,0 +1 @@ + diff --git a/content/content-formatting-examples/_index.md b/content/content-formatting-examples/_index.md new file mode 100644 index 00000000..2bf4deaf --- /dev/null +++ b/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. diff --git a/content/content-formatting-examples/academy-theme/_index.md b/content/content-formatting-examples/academy-theme/_index.md new file mode 100644 index 00000000..b8428d97 --- /dev/null +++ b/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. diff --git a/content/content-formatting-examples/academy-theme/alerts.md b/content/content-formatting-examples/academy-theme/alerts.md new file mode 100644 index 00000000..15b330c0 --- /dev/null +++ b/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 content with **Markdown** support.{{}} +``` + +**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 >}} diff --git a/content/content-formatting-examples/academy-theme/chapterstyle.md b/content/content-formatting-examples/academy-theme/chapterstyle.md new file mode 100644 index 00000000..a5ca009e --- /dev/null +++ b/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 `
` 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 `
` | _(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 %}} diff --git a/content/content-formatting-examples/academy-theme/csvtable-roles.md b/content/content-formatting-examples/academy-theme/csvtable-roles.md new file mode 100644 index 00000000..d6642f51 --- /dev/null +++ b/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 +{{}} +``` + +The CSV file must be located at `static/data/csv/keys-backup.csv` with the same format used by `csvtable`. + +**Example:** + +{{< csvtable-roles >}} diff --git a/content/content-formatting-examples/academy-theme/csvtable.md b/content/content-formatting-examples/academy-theme/csvtable.md new file mode 100644 index 00000000..255c1dfe --- /dev/null +++ b/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 +{{}} +``` + +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 >}} diff --git a/content/content-formatting-examples/academy-theme/embedded-design.md b/content/content-formatting-examples/academy-theme/embedded-design.md new file mode 100644 index 00000000..652720f5 --- /dev/null +++ b/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 +{{}} +``` + +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. diff --git a/content/content-formatting-examples/academy-theme/image.md b/content/content-formatting-examples/academy-theme/image.md new file mode 100644 index 00000000..10d2ae11 --- /dev/null +++ b/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%" >}} diff --git a/content/content-formatting-examples/academy-theme/lab-intro.md b/content/content-formatting-examples/academy-theme/lab-intro.md new file mode 100644 index 00000000..446f4289 --- /dev/null +++ b/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. diff --git a/content/content-formatting-examples/academy-theme/local-video.md b/content/content-formatting-examples/academy-theme/local-video.md new file mode 100644 index 00000000..91e6c2a1 --- /dev/null +++ b/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 `