Merge pull request #419 from layer5io/embed-shortcode

Add Design Embed shortcode and docs

content/en/kanvas/designer/embedding-designs/index.md

@@ -33,6 +33,33 @@ To embed your Kanvas design, follow these steps:
 
    Make sure the `src` attribute in the script tag points to the location of the downloaded embedding script on your local filesystem or server.
 
+### Customization
+
+You can customize the styles for the embedded design by targeting CSS classes exposed or by adding inline styles. The following class can be overridden:
+
+- `embed-design-container`: for the embedding container
+- `cy-container`: for the canvas
+
+If you have multiple embeddings on a page, you can target them all using the classes or specific ones using the div's ID in the shortcode.
+
+Here is a customization example:
+
+```html
+<style>
+  .embed-design-container {
+    width: 100%;
+    border-radius: 1rem;
+    margin: 1rem;
+    overflow: hidden;
+    margin-inline: auto;
+    height: 35rem;
+  }
+  .embed-canvas-container {
+    background-color: gray;
+  }
+</style>
+```
+
 ## Embedding in React Projects
 
 1. **Install the Package**: To integrate the Meshery Design into your React project, start by installing the package via npm:
@@ -63,38 +90,60 @@ function Design() {
 Make sure the `embedScriptSrc` attribute in the component points to the location of the downloaded embedding script on your react filesystem.
 Usually the script is located "static" folder
 
-### Render
-After Finishing the steps , the embedded design will be rendered like :
 
-<!-- Design Embed Container  -->
-<div id="embedded-design-7d183e77-09e1-4b69-a5ee-3e3870e9c5f4" style="height:30rem;width:100%;border:1px solid #eee"></div>
-<script src="../export-designs/embedded-design-dapr.js" type="module" ></script>
+### Embedding with Hugo
 
-### Customization
+To prepare your Hugo site to support design embedding, perform the one-time task of adding the following shortcode definition to your site's set of supported shortcodes.
 
-You can customize the styles for the embedded design by targeting CSS classes exposed or by adding inline styles. The following class can be overridden:
+__Shortcode Definition__
 
-- `embed-design-container`: for the embedding container
-- `cy-container`: for the canvas
+```html
 
-If you have multiple embeddings on a page, you can target them all using the classes or specific ones using the div's ID in the shortcode.
+{{ $script := .Get "src" }}
+{{ $id := .Get "id" }}
+{{ $style := .Get "style" }}
 
-Here is a customization example:
+<div
+    id="{{ $id }}"
+    {{ if $style }}
+        style="{{ $style }}"
+    {{ else }}
+        style="height: 30rem; width: 100%; border: 1px solid #eee"
+    {{ end }}
+></div>
+
+<script src="{{ $script }}" type="module"></script>
+```
+
+#### Shortcode Explaination
+
+`src`: Specify the path to the exported JavaScript file.
+`id`: Provide a unique ID for the embedded design.
+`style`: (Optional) Customize the appearance of the embedded design with CSS styles. This allows you to control the height, width, border, and other visual aspects.
+
+Now that your site has shortcode support for embedding Kanvas designs, you're ready to use the shortcode in any Hugo markdown file where you want embedded the designs to be visible to your site visitors. 
+
+#### Shortcode Usage
+
+Following the steps to export a design will generate a JavaScript file, containing your design. Add the Javascript file to your site and embed the design by using your new shortcode. In the following example, we use an exported design, "embedded-design-dapr.js". 
+
+Use the shortcode in your Hugo content files as shown:
 
 ```html
-<style>
-  .embed-design-container {
-    width: 100%;
-    border-radius: 1rem;
-    margin: 1rem;
-    overflow: hidden;
-    margin-inline: auto;
-    height: 35rem;
-  }
-  .embed-canvas-container {
-    background-color: gray;
-  }
-</style>
+{{</* meshery-design-embed
+    src="../export-designs/embedded-design-dapr.js"
+    id="embedded-design-7d183e77-09e1-4b69-a5ee-3e3870e9c5f4"
+*/>}}
 ```
 
+This code snippet demonstrates how to embed a design named "embedded-design-dapr.js" with a specific ID. This will render an interactive diagram of a Dapr (Distributed Application Runtime) setup within your Hugo-based website. 
+
+#### Embedded Design Example
+
+Finally, render your designs in your pages. When Hugo builds your website, it will process this shortcode and generate the necessary HTML and JavaScript to embed the interactive Kanvas design. After finishing the steps, the embedded design will be rendered like in the example below.
+
+<!-- Design Embed Container  -->
+
+{{< meshery-design-embed  src="../export-designs/embedded-design-dapr.js"  id="embedded-design-7d183e77-09e1-4b69-a5ee-3e3870e9c5f4" >}}
+
 

layouts/shortcodes/meshery-design-embed.html

@@ -0,0 +1,60 @@
+<!-- 
+  This shortcode is used to embed a Meshery design into hugo sites 
+  Meshery Design Embedding allows exporting a design as an interactive component 
+  that integrates seamlessly into websites, blogs, or any platform supporting HTML, CSS, and JavaScript. 
+  This embedded design is interactive, making it easier for infrastructure stakeholders 
+  to visualize, explore, and collaborate on service mesh designs.
+  
+  -- Usage: 
+  {{/*< meshery-design-embed src="path/to/embed.js" id="unique-id" style="custom-styles" >*/}}
+
+  More Information: 
+  Learn more about embedding Meshery designs at:
+  https://docs.layer5.io/kanvas/designer/embedding-designs/
+-->
+
+<!-- 
+  Retrieve the path to the JavaScript file generated for embedding the Meshery design.
+  This script is generated when exporting a design from kanvas.new.
+  The `src` attribute specifies the script location, as provided by the user. 
+-->
+{{ $script := .Get "src" }}
+
+<!-- 
+  Retrieve the unique ID for the embedded Meshery design. 
+  This ID is typically generated when creating the embed code and is used to uniquely 
+  identify the container for the embedded design on the page.
+-->
+{{ $id := .Get "id" }}
+
+<!-- 
+  Retrieve optional custom styles for the embedding container.
+  If not provided, a default style will be applied to ensure proper rendering. 
+-->
+{{ $style := .Get "style" }}
+
+<!-- 
+  Embedding Container: 
+  A `div` element is dynamically created with the provided or default styles. 
+  - The `id` attribute links to the unique design embed.
+  - The `style` attribute can be customized or fall back to a default appearance, 
+    which includes:
+      - Height: 30rem
+      - Width: 100% (responsive to container width)
+      - Border: 1px solid #eee (light border for visibility)
+-->
+<div
+    id="{{ $id }}"
+    {{ if $style }}
+    style="{{ $style }}"
+    {{ else }}
+    style="height: 30rem; width: 100%; border: 1px solid #eee"
+    {{ end }}
+></div>
+
+<!-- 
+  Embed Script: 
+  The JavaScript file (retrieved from the `src` attribute) is included here.
+  - The `type="module"` ensures the script runs in a modern ES6 module context.
+-->
+<script src="{{ $script }}" type="module"></script>