Merge pull request #739 from zihanKuang/update-embedded-docs

zihanKuang · web-flow · commit 2fbbc18cee02 · 2025-08-05T10:56:50.000+08:00
feat(docs): Refactor embed design shortcode and update documentation
diff --git a/content/en/kanvas/designer/embedding-designs/embed-designs.gif b/content/en/kanvas/designer/embedding-designs/embed-designs.gif
diff --git a/content/en/kanvas/designer/embedding-designs/index.md b/content/en/kanvas/designer/embedding-designs/index.md
@@ -15,7 +15,7 @@ Meshery Design Embedding enables you to export a design in a format that can be
 
 To embed your Kanvas design, follow these steps:
 
-1. **Access Embed Option**: Within the Kanvas Designer, select the design you wish to embed in the design drawer. Click on the export icon in the menu for the selected design. The export modal will appear, click on the "Embed" option.
+1. **Access Embed Option**: Within the [Kanvas Designer](https://kanvas.new/), select the design you wish to embed. Click on the export icon in the menu for the selected design. The export modal will appear, click on the "Embed" option.
 
    ![Embed Designs from Kanvas](./embed-designs.gif)
 
@@ -34,31 +34,39 @@ To embed your Kanvas design, follow these steps:
 
 ### 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:
+You can customize the styles for the embedded design in two ways: globally via CSS classes, or for a single instance via an inline style parameter.
 
-- `embed-design-container`: for the embedding container
-- `cy-container`: for the canvas
+#### Global Styling (via CSS Classes)
 
-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.
+For advanced global styling, you can override the default CSS rules in your site's stylesheet. This will affect all embedded designs on your site. The main classes are:
 
-Here is a customization example:
+- `.meshery-embed-container`: The main container for the embedded design. You can target its `.full` or `.half` variants for specific sizing adjustments.
+- `.cy-container`: The canvas element within the container where the design itself is rendered.
+
+Here is an example of how you could override these classes:
 
 ```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;
+  /* Make all embed containers have a different border and background */
+  .meshery-embed-container {
+    border: 2px solid #00B39F;
+    background-color: #f5f5f5;
   }
 </style>
 ```
 
+#### Instance-specific Styling (via `style` Parameter)
+
+For styling a single instance, the recommended method is to use the `style` parameter directly in the shortcode. This provides maximum control and will override any default styles or global CSS.
+
+```html
+{{</* meshery-design-embed
+    src="..."
+    id="..."
+    style="width: 60%; height: 28rem; border-radius: 1.5rem;"
+*/>}}
+```
+
 ## Embedding in React Projects
 
 1. **Install the Package**: To integrate the Meshery Design into your React project, start by installing the package via npm:
@@ -70,11 +78,9 @@ Here is a customization example:
 ```jsx
 import MesheryDesignEmbed from '@layer5/meshery-design-embed'
 
-
 function Design() {
   return (
     <>
-
       <div>
         <MesheryDesignEmbed
           embedScriptSrc="embedded-design-embed1.js"  // path to the embed script
@@ -89,60 +95,116 @@ 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
 
-
-### Embedding with Hugo
+## Embedding with Hugo
 
 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.
 
-__Shortcode Definition__
+### Shortcode Definition
 
-```html
+<details>
+<summary>Click to expand the full Shortcode Definition</summary>
 
+```html
 {{ $script := .Get "src" }}
 {{ $id := .Get "id" }}
+{{ $size := .Get "size" | default "full" }}
 {{ $style := .Get "style" }}
 
+<style>
+.meshery-embed-container {
+  border: 1px solid #eee;
+  border-radius: 4px;
+  margin: 0rem auto;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+}
+.meshery-embed-container.full {
+  width: 80%;
+  height: 30rem;
+}
+.meshery-embed-container.half {
+  width: 50%;
+  height: 25rem;
+}
+.meshery-embed-container .cy-container {
+  width: 100%;
+  height: 100%;
+}
+</style>
+
 <div
     id="{{ $id }}"
-    {{ if $style }}
-        style="{{ $style }}"
-    {{ else }}
-        style="height: 30rem; width: 100%; border: 1px solid #eee"
-    {{ end }}
+    {{- if $style -}}
+        style="{{ $style | safeCSS }}"
+    {{- else -}}
+        class="meshery-embed-container {{ $size }}"
+    {{- end -}}
 ></div>
 
 <script src="{{ $script }}" type="module"></script>
 ```
+</details>
+
+### Shortcode Explanation
+
+- **`src`** (Required): The path to the exported JavaScript file for your design.
+- **`id`** (Required): A unique ID for the embedded design container.
+- **`size`** (Optional): A preset for simple sizing.
+  - Accepts `"full"` (default) or `"half"`.
+  - This parameter is ignored if `style` is used.
+- **`style`** (Optional): For advanced customization.
+  - Allows you to provide any custom CSS inline styles.
+  - **This parameter has higher priority and will override the `size` parameter.**
 
-#### Shortcode Explaination
+Now that your site has shortcode support for embedding Kanvas designs, you can use the `meshery-design-embed` shortcode in any Hugo markdown file where you want to display embedded designs to your site visitors.
 
-`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.
+### Using the Shortcode
 
-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. 
+To embed a Meshery Design in your Hugo pages, use the `meshery-design-embed` shortcode. You will need the design's exported JavaScript file and its unique ID.
 
-#### Shortcode Usage
+### Usage Examples
 
-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". 
+Place the exported `.js` file in an appropriate folder (e.g., a nearby `images` folder) and reference it in the shortcode.
 
-Use the shortcode in your Hugo content files as shown:
+**Default (full-width) display:**
 
 ```html
 {{</* meshery-design-embed
-    src="../export-designs/embedded-design-dapr.js"
-    id="embedded-design-7d183e77-09e1-4b69-a5ee-3e3870e9c5f4"
+    src="../path/to/your-design.js"
+    id="your-unique-design-id-full"
 */>}}
 ```
 
-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. 
+**Half-width display:**
 
-#### Embedded Design Example
+```html
+{{</* meshery-design-embed
+    src="../path/to/your-design.js"
+    id="your-unique-design-id-half"
+    size="half"
+*/>}}
+```
 
-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.
+**Custom styling:**
 
-<!-- Design Embed Container  -->
+```html
+{{</* meshery-design-embed
+    src="../path/to/your-design.js"
+    id="your-unique-design-id-custom"
+    style="width: 60%; height: 28rem; border-radius: 1.5rem;"
+*/>}}
+```
 
-{{< meshery-design-embed  src="../export-designs/embedded-design-dapr.js"  id="embedded-design-7d183e77-09e1-4b69-a5ee-3e3870e9c5f4" >}}
+### Embedded Design Example
 
+When Hugo builds your website, it will process the shortcode and generate the necessary HTML and JavaScript to embed the interactive Kanvas design. 
 
+Here's an example of how an embedded design appears:
+
+<!-- Design Embed Container  -->
+```html
+{{</* meshery-design-embed  
+src="../export-designs/embedded-design-dapr.js"  
+id="embedded-design-7d183e77-09e1-4b69-a5ee-3e3870e9c5f4" */>}}
+```
+
+{{< meshery-design-embed  src="../export-designs/embedded-design-dapr.js"  id="embedded-design-7d183e77-09e1-4b69-a5ee-3e3870e9c5f4" >}}
diff --git a/layouts/shortcodes/meshery-design-embed.html b/layouts/shortcodes/meshery-design-embed.html
@@ -33,21 +33,22 @@
   If not provided, "full" is used as default.
 -->
 {{ $size := .Get "size" | default "full" }}
+{{ $style := .Get "style" }}
 
 <style>
 .meshery-embed-container {
   border: 1px solid #eee;
   border-radius: 4px;
-  margin: 1rem auto;
+  margin: 0rem auto;
   box-shadow: 0 1px 3px rgba(0,0,0,0.1);
 }
 .meshery-embed-container.full {
-  width: 100%;
+  width: 80%;
   height: 30rem;
 }
 .meshery-embed-container.half {
   width: 50%;
-  height: 30rem;
+  height: 25rem;
 }
 .meshery-embed-container .cy-container {
   width: 100%;
@@ -67,7 +68,11 @@
 -->
 <div
     id="{{ $id }}"
-    class="meshery-embed-container {{ $size }}"
+    {{- if $style -}}
+        style="{{ $style | safeCSS }}"
+    {{- else -}}
+        class="meshery-embed-container {{ $size }}"
+    {{- end -}}
 ></div>
 
 <!-- 
