diff --git a/Makefile b/Makefile index 4d61ee8eb..fdada2387 100644 --- a/Makefile +++ b/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 diff --git a/assets/icons/exoscale-demo.svg b/assets/icons/exoscale-demo.svg new file mode 100644 index 000000000..e68645e2e --- /dev/null +++ b/assets/icons/exoscale-demo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/assets/icons/layer5-academy-icon.svg b/assets/icons/layer5-academy-icon.svg new file mode 100644 index 000000000..7b1bdf547 --- /dev/null +++ b/assets/icons/layer5-academy-icon.svg @@ -0,0 +1,10 @@ + + + + + + \ No newline at end of file diff --git a/content/content-formatting-examples/_index.md b/content/content-formatting-examples/_index.md new file mode 100644 index 000000000..2bf4deaf3 --- /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 000000000..b8428d974 --- /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 000000000..15b330c05 --- /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 000000000..a5ca009e0 --- /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 000000000..d6642f512 --- /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 000000000..255c1dfeb --- /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 000000000..652720f57 --- /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 000000000..10d2ae116 --- /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 000000000..446f42895 --- /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 000000000..91e6c2a10 --- /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 `