From 09ecf76034de18edb83f25ff9fdb2c461296dab9 Mon Sep 17 00:00:00 2001
From: saurabhg772244 <saurabh@mermaidchart.com>
Date: Wed, 9 Oct 2024 15:34:12 +0530
Subject: [PATCH 1/4] Updated doc for image and icon shapes

---
 docs/syntax/flowchart.md                      | 60 +++++++++++++++++++
 packages/mermaid/src/docs/syntax/flowchart.md | 50 ++++++++++++++++
 2 files changed, 110 insertions(+)

diff --git a/docs/syntax/flowchart.md b/docs/syntax/flowchart.md
index 8f8b54e212..ea1db9c03d 100644
--- a/docs/syntax/flowchart.md
+++ b/docs/syntax/flowchart.md
@@ -926,6 +926,66 @@ flowchart TD
     A@{ shape: tag-rect, label: "Tagged process" }
 ```
 
+## Special shapes in Mermaid Flowcharts (v11.3.0+)
+
+Mermaid also introduces 2 special shapes to enhance your flowcharts: **icon** and **image**. These shapes allow you to include icons and images directly within your flowcharts, providing more visual context and clarity.
+
+### Icon Shape
+
+You can use the `icon` shape to include an icon in your flowchart. To use icons, you need to register the icon pack first. Follow the instructions provided [here](https://mermaid.js.org/syntax/architecture.html#icons). The syntax for defining an icon shape is as follows:
+
+```mermaid-example
+flowchart TD
+    A@{ icon: "fa:user", form: "square", label: "User Icon", pos: "t", h: 60 }
+```
+
+```mermaid
+flowchart TD
+    A@{ icon: "fa:user", form: "square", label: "User Icon", pos: "t", h: 60 }
+```
+
+### Parameters
+
+- **icon**: The name of the icon from the registered icon pack.
+- **form**: Specifies the background shape of the icon. If not defined there will be no background to icon. Options include:
+  - `square`
+  - `circle`
+  - `rounded`
+- **label**: The text label associated with the icon. This can be any string. If not defined, no label will be displayed.
+- **pos**: The position of the label. If not defined label will default to bottom of icon. Possible values are:
+  - `t`
+  - `b`
+- **h**: The height of the icon. If not defined this will default to 48 which is minimum.
+
+### Image Shape
+
+You can use the `image` shape to include an image in your flowchart. The syntax for defining an image shape is as follows:
+
+```mermaid-example
+flowchart TD
+    A@{ img: "https://example.com/image.png", label: "Image Label", pos: "t", w: 60, h: 60, constraint: "off" }
+```
+
+```mermaid
+flowchart TD
+    A@{ img: "https://example.com/image.png", label: "Image Label", pos: "t", w: 60, h: 60, constraint: "off" }
+```
+
+### Parameters
+
+- **img**: The URL of the image to be displayed.
+- **label**: The text label associated with the image. This can be any string. If not defined, no label will be displayed.
+- **pos**: The position of the label. If not defined, the label will default to the bottom of the image. Possible values are:
+  - `t`
+  - `b`
+- **w**: The width of the image. If not defined, this will default to the natural width of the image.
+- **h**: The height of the image. If not defined, this will default to the natural height of the image.
+- **constraint**: Determines if the image should constrain the node size. This setting also ensures the image maintains its original aspect ratio, adjusting the height (`h`) accordingly to the width (`w`). If not defined, this will default to `off` Possible values are:
+  - `on`
+  - `off`
+
+These new shapes provide additional flexibility and visual appeal to your flowcharts, making them more informative and engaging.
+
 ## Links between nodes
 
 Nodes can be connected with links/edges. It is possible to have different types of links or attach a text string to a link.
diff --git a/packages/mermaid/src/docs/syntax/flowchart.md b/packages/mermaid/src/docs/syntax/flowchart.md
index 86347bd808..1b8cfffc13 100644
--- a/packages/mermaid/src/docs/syntax/flowchart.md
+++ b/packages/mermaid/src/docs/syntax/flowchart.md
@@ -542,6 +542,56 @@ flowchart TD
     A@{ shape: tag-rect, label: "Tagged process" }
 ```
 
+## Special shapes in Mermaid Flowcharts (v11.3.0+)
+
+Mermaid also introduces 2 special shapes to enhance your flowcharts: **icon** and **image**. These shapes allow you to include icons and images directly within your flowcharts, providing more visual context and clarity.
+
+### Icon Shape
+
+You can use the `icon` shape to include an icon in your flowchart. To use icons, you need to register the icon pack first. Follow the instructions provided [here](https://mermaid.js.org/syntax/architecture.html#icons). The syntax for defining an icon shape is as follows:
+
+```mermaid-example
+flowchart TD
+    A@{ icon: "fa:user", form: "square", label: "User Icon", pos: "t", h: 60 }
+```
+
+### Parameters
+
+- **icon**: The name of the icon from the registered icon pack.
+- **form**: Specifies the background shape of the icon. If not defined there will be no background to icon. Options include:
+  - `square`
+  - `circle`
+  - `rounded`
+- **label**: The text label associated with the icon. This can be any string. If not defined, no label will be displayed.
+- **pos**: The position of the label. If not defined label will default to bottom of icon. Possible values are:
+  - `t`
+  - `b`
+- **h**: The height of the icon. If not defined this will default to 48 which is minimum.
+
+### Image Shape
+
+You can use the `image` shape to include an image in your flowchart. The syntax for defining an image shape is as follows:
+
+```mermaid-example
+flowchart TD
+    A@{ img: "https://example.com/image.png", label: "Image Label", pos: "t", w: 60, h: 60, constraint: "off" }
+```
+
+### Parameters
+
+- **img**: The URL of the image to be displayed.
+- **label**: The text label associated with the image. This can be any string. If not defined, no label will be displayed.
+- **pos**: The position of the label. If not defined, the label will default to the bottom of the image. Possible values are:
+  - `t`
+  - `b`
+- **w**: The width of the image. If not defined, this will default to the natural width of the image.
+- **h**: The height of the image. If not defined, this will default to the natural height of the image.
+- **constraint**: Determines if the image should constrain the node size. This setting also ensures the image maintains its original aspect ratio, adjusting the height (`h`) accordingly to the width (`w`). If not defined, this will default to `off` Possible values are:
+  - `on`
+  - `off`
+
+These new shapes provide additional flexibility and visual appeal to your flowcharts, making them more informative and engaging.
+
 ## Links between nodes
 
 Nodes can be connected with links/edges. It is possible to have different types of links or attach a text string to a link.

From 9f6f1e96e50b3589a73adfd37d5a1eb35579bba4 Mon Sep 17 00:00:00 2001
From: saurabhg772244 <saurabh@mermaidchart.com>
Date: Thu, 10 Oct 2024 13:11:54 +0530
Subject: [PATCH 2/4] Added new doc for registering icon pack in mermaid

---
 docs/config/icons.md                          | 55 +++++++++++++++++++
 docs/syntax/architecture.md                   | 50 +----------------
 docs/syntax/flowchart.md                      |  2 +-
 .../mermaid/src/docs/.vitepress/config.ts     |  1 +
 packages/mermaid/src/docs/config/icons.md     | 49 +++++++++++++++++
 .../mermaid/src/docs/syntax/architecture.md   | 50 +----------------
 packages/mermaid/src/docs/syntax/flowchart.md |  2 +-
 7 files changed, 109 insertions(+), 100 deletions(-)
 create mode 100644 docs/config/icons.md
 create mode 100644 packages/mermaid/src/docs/config/icons.md

diff --git a/docs/config/icons.md b/docs/config/icons.md
new file mode 100644
index 0000000000..ef0812b500
--- /dev/null
+++ b/docs/config/icons.md
@@ -0,0 +1,55 @@
+> **Warning**
+>
+> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
+>
+> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/icons.md](../../packages/mermaid/src/docs/config/icons.md).
+
+# Registering icon pack in mermaid
+
+The icon packs available can be found at [icones.js.org](https://icones.js.org/).
+We use the name defined when registering the icon pack, to override the prefix field of the iconify pack. This allows the user to use shorter names for the icons. It also allows us to load a particular pack only when it is used in a diagram.
+
+Using JSON file directly from CDN:
+
+```js
+import mermaid from 'CDN/mermaid.esm.mjs';
+mermaid.registerIconPacks([
+  {
+    name: 'logos',
+    loader: () =>
+      fetch('https://unpkg.com/@iconify-json/logos/icons.json').then((res) => res.json()),
+  },
+]);
+```
+
+Using packages and a bundler:
+
+```bash
+npm install @iconify-json/logos
+```
+
+With lazy loading
+
+```js
+import mermaid from 'mermaid';
+
+mermaid.registerIconPacks([
+  {
+    name: 'logos',
+    loader: () => import('@iconify-json/logos').then((module) => module.icons),
+  },
+]);
+```
+
+Without lazy loading
+
+```js
+import mermaid from 'mermaid';
+import { icons } from '@iconify-json/logos';
+mermaid.registerIconPacks([
+  {
+    name: icons.prefix, // To use the prefix defined in the icon pack
+    icons,
+  },
+]);
+```
diff --git a/docs/syntax/architecture.md b/docs/syntax/architecture.md
index 12a7cf4091..f24c5d607a 100644
--- a/docs/syntax/architecture.md
+++ b/docs/syntax/architecture.md
@@ -194,55 +194,7 @@ architecture-beta
 ## Icons
 
 By default, architecture diagram supports the following icons: `cloud`, `database`, `disk`, `internet`, `server`.
-Users can use any of the 200,000+ icons available in iconify.design, or add their own custom icons, by following the steps below.
-
-The icon packs available can be found at [icones.js.org](https://icones.js.org/).
-We use the name defined when registering the icon pack, to override the prefix field of the iconify pack. This allows the user to use shorter names for the icons. It also allows us to load a particular pack only when it is used in a diagram.
-
-Using JSON file directly from CDN:
-
-```js
-import mermaid from 'CDN/mermaid.esm.mjs';
-mermaid.registerIconPacks([
-  {
-    name: 'logos',
-    loader: () =>
-      fetch('https://unpkg.com/@iconify-json/logos/icons.json').then((res) => res.json()),
-  },
-]);
-```
-
-Using packages and a bundler:
-
-```bash
-npm install @iconify-json/logos
-```
-
-With lazy loading
-
-```js
-import mermaid from 'mermaid';
-
-mermaid.registerIconPacks([
-  {
-    name: 'logos',
-    loader: () => import('@iconify-json/logos').then((module) => module.icons),
-  },
-]);
-```
-
-Without lazy loading
-
-```js
-import mermaid from 'mermaid';
-import { icons } from '@iconify-json/logos';
-mermaid.registerIconPacks([
-  {
-    name: icons.prefix, // To use the prefix defined in the icon pack
-    icons,
-  },
-]);
-```
+Users can use any of the 200,000+ icons available in iconify.design, or add their own custom icons, by following the steps [here](https://mermaid.js.org/config/icons.html).
 
 After the icons are installed, they can be used in the architecture diagram by using the format "name:icon-name", where name is the value used when registering the icon pack.
 
diff --git a/docs/syntax/flowchart.md b/docs/syntax/flowchart.md
index ea1db9c03d..dd7be92074 100644
--- a/docs/syntax/flowchart.md
+++ b/docs/syntax/flowchart.md
@@ -932,7 +932,7 @@ Mermaid also introduces 2 special shapes to enhance your flowcharts: **icon** an
 
 ### Icon Shape
 
-You can use the `icon` shape to include an icon in your flowchart. To use icons, you need to register the icon pack first. Follow the instructions provided [here](https://mermaid.js.org/syntax/architecture.html#icons). The syntax for defining an icon shape is as follows:
+You can use the `icon` shape to include an icon in your flowchart. To use icons, you need to register the icon pack first. Follow the instructions provided [here](https://mermaid.js.org/config/icons.html). The syntax for defining an icon shape is as follows:
 
 ```mermaid-example
 flowchart TD
diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts
index 619de961dc..23d8a21bba 100644
--- a/packages/mermaid/src/docs/.vitepress/config.ts
+++ b/packages/mermaid/src/docs/.vitepress/config.ts
@@ -180,6 +180,7 @@ function sidebarConfig() {
         { text: 'Accessibility', link: '/config/accessibility' },
         { text: 'Mermaid CLI', link: '/config/mermaidCLI' },
         { text: 'FAQ', link: '/config/faq' },
+        { text: 'Registering icons', link: '/config/icons' },
       ],
     },
   ];
diff --git a/packages/mermaid/src/docs/config/icons.md b/packages/mermaid/src/docs/config/icons.md
new file mode 100644
index 0000000000..d5d296281c
--- /dev/null
+++ b/packages/mermaid/src/docs/config/icons.md
@@ -0,0 +1,49 @@
+# Registering icon pack in mermaid
+
+The icon packs available can be found at [icones.js.org](https://icones.js.org/).
+We use the name defined when registering the icon pack, to override the prefix field of the iconify pack. This allows the user to use shorter names for the icons. It also allows us to load a particular pack only when it is used in a diagram.
+
+Using JSON file directly from CDN:
+
+```js
+import mermaid from 'CDN/mermaid.esm.mjs';
+mermaid.registerIconPacks([
+  {
+    name: 'logos',
+    loader: () =>
+      fetch('https://unpkg.com/@iconify-json/logos/icons.json').then((res) => res.json()),
+  },
+]);
+```
+
+Using packages and a bundler:
+
+```bash
+npm install @iconify-json/logos
+```
+
+With lazy loading
+
+```js
+import mermaid from 'mermaid';
+
+mermaid.registerIconPacks([
+  {
+    name: 'logos',
+    loader: () => import('@iconify-json/logos').then((module) => module.icons),
+  },
+]);
+```
+
+Without lazy loading
+
+```js
+import mermaid from 'mermaid';
+import { icons } from '@iconify-json/logos';
+mermaid.registerIconPacks([
+  {
+    name: icons.prefix, // To use the prefix defined in the icon pack
+    icons,
+  },
+]);
+```
diff --git a/packages/mermaid/src/docs/syntax/architecture.md b/packages/mermaid/src/docs/syntax/architecture.md
index 476c60532f..53da754c94 100644
--- a/packages/mermaid/src/docs/syntax/architecture.md
+++ b/packages/mermaid/src/docs/syntax/architecture.md
@@ -156,55 +156,7 @@ architecture-beta
 ## Icons
 
 By default, architecture diagram supports the following icons: `cloud`, `database`, `disk`, `internet`, `server`.
-Users can use any of the 200,000+ icons available in iconify.design, or add their own custom icons, by following the steps below.
-
-The icon packs available can be found at [icones.js.org](https://icones.js.org/).
-We use the name defined when registering the icon pack, to override the prefix field of the iconify pack. This allows the user to use shorter names for the icons. It also allows us to load a particular pack only when it is used in a diagram.
-
-Using JSON file directly from CDN:
-
-```js
-import mermaid from 'CDN/mermaid.esm.mjs';
-mermaid.registerIconPacks([
-  {
-    name: 'logos',
-    loader: () =>
-      fetch('https://unpkg.com/@iconify-json/logos/icons.json').then((res) => res.json()),
-  },
-]);
-```
-
-Using packages and a bundler:
-
-```bash
-npm install @iconify-json/logos
-```
-
-With lazy loading
-
-```js
-import mermaid from 'mermaid';
-
-mermaid.registerIconPacks([
-  {
-    name: 'logos',
-    loader: () => import('@iconify-json/logos').then((module) => module.icons),
-  },
-]);
-```
-
-Without lazy loading
-
-```js
-import mermaid from 'mermaid';
-import { icons } from '@iconify-json/logos';
-mermaid.registerIconPacks([
-  {
-    name: icons.prefix, // To use the prefix defined in the icon pack
-    icons,
-  },
-]);
-```
+Users can use any of the 200,000+ icons available in iconify.design, or add their own custom icons, by following the steps [here](https://mermaid.js.org/config/icons.html).
 
 After the icons are installed, they can be used in the architecture diagram by using the format "name:icon-name", where name is the value used when registering the icon pack.
 
diff --git a/packages/mermaid/src/docs/syntax/flowchart.md b/packages/mermaid/src/docs/syntax/flowchart.md
index 1b8cfffc13..b48b8fb4c2 100644
--- a/packages/mermaid/src/docs/syntax/flowchart.md
+++ b/packages/mermaid/src/docs/syntax/flowchart.md
@@ -548,7 +548,7 @@ Mermaid also introduces 2 special shapes to enhance your flowcharts: **icon** an
 
 ### Icon Shape
 
-You can use the `icon` shape to include an icon in your flowchart. To use icons, you need to register the icon pack first. Follow the instructions provided [here](https://mermaid.js.org/syntax/architecture.html#icons). The syntax for defining an icon shape is as follows:
+You can use the `icon` shape to include an icon in your flowchart. To use icons, you need to register the icon pack first. Follow the instructions provided [here](https://mermaid.js.org/config/icons.html). The syntax for defining an icon shape is as follows:
 
 ```mermaid-example
 flowchart TD

From ca885027d4309f52af28d15402b662e3edfa2d83 Mon Sep 17 00:00:00 2001
From: saurabhg772244 <saurabh@mermaidchart.com>
Date: Thu, 10 Oct 2024 14:15:16 +0530
Subject: [PATCH 3/4] Moved position for icon config and added major version in
 icon docs

---
 docs/config/icons.md                           | 4 ++--
 packages/mermaid/src/docs/.vitepress/config.ts | 2 +-
 packages/mermaid/src/docs/config/icons.md      | 4 ++--
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/config/icons.md b/docs/config/icons.md
index ef0812b500..729afa1d54 100644
--- a/docs/config/icons.md
+++ b/docs/config/icons.md
@@ -17,7 +17,7 @@ mermaid.registerIconPacks([
   {
     name: 'logos',
     loader: () =>
-      fetch('https://unpkg.com/@iconify-json/logos/icons.json').then((res) => res.json()),
+      fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then((res) => res.json()),
   },
 ]);
 ```
@@ -25,7 +25,7 @@ mermaid.registerIconPacks([
 Using packages and a bundler:
 
 ```bash
-npm install @iconify-json/logos
+npm install @iconify-json/logos@1
 ```
 
 With lazy loading
diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts
index 23d8a21bba..4dec8231f7 100644
--- a/packages/mermaid/src/docs/.vitepress/config.ts
+++ b/packages/mermaid/src/docs/.vitepress/config.ts
@@ -174,13 +174,13 @@ function sidebarConfig() {
         { text: 'API-Usage', link: '/config/usage' },
         { text: 'Mermaid API Configuration', link: '/config/setup/README' },
         { text: 'Mermaid Configuration Options', link: '/config/schema-docs/config' },
+        { text: 'Registering icons', link: '/config/icons' },
         { text: 'Directives', link: '/config/directives' },
         { text: 'Theming', link: '/config/theming' },
         { text: 'Math', link: '/config/math' },
         { text: 'Accessibility', link: '/config/accessibility' },
         { text: 'Mermaid CLI', link: '/config/mermaidCLI' },
         { text: 'FAQ', link: '/config/faq' },
-        { text: 'Registering icons', link: '/config/icons' },
       ],
     },
   ];
diff --git a/packages/mermaid/src/docs/config/icons.md b/packages/mermaid/src/docs/config/icons.md
index d5d296281c..db079f841d 100644
--- a/packages/mermaid/src/docs/config/icons.md
+++ b/packages/mermaid/src/docs/config/icons.md
@@ -11,7 +11,7 @@ mermaid.registerIconPacks([
   {
     name: 'logos',
     loader: () =>
-      fetch('https://unpkg.com/@iconify-json/logos/icons.json').then((res) => res.json()),
+      fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then((res) => res.json()),
   },
 ]);
 ```
@@ -19,7 +19,7 @@ mermaid.registerIconPacks([
 Using packages and a bundler:
 
 ```bash
-npm install @iconify-json/logos
+npm install @iconify-json/logos@1
 ```
 
 With lazy loading

From a4fd42214b489b40769b9da1364e2513f6c774ea Mon Sep 17 00:00:00 2001
From: saurabhg772244 <saurabh@mermaidchart.com>
Date: Thu, 10 Oct 2024 15:17:26 +0530
Subject: [PATCH 4/4] Use relative URL in linking docs

---
 docs/syntax/architecture.md                      | 2 +-
 docs/syntax/flowchart.md                         | 2 +-
 packages/mermaid/src/docs/syntax/architecture.md | 2 +-
 packages/mermaid/src/docs/syntax/flowchart.md    | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/syntax/architecture.md b/docs/syntax/architecture.md
index f24c5d607a..2ac8a1ed1a 100644
--- a/docs/syntax/architecture.md
+++ b/docs/syntax/architecture.md
@@ -194,7 +194,7 @@ architecture-beta
 ## Icons
 
 By default, architecture diagram supports the following icons: `cloud`, `database`, `disk`, `internet`, `server`.
-Users can use any of the 200,000+ icons available in iconify.design, or add their own custom icons, by following the steps [here](https://mermaid.js.org/config/icons.html).
+Users can use any of the 200,000+ icons available in iconify.design, or add their own custom icons, by following the steps [here](../config/icons.md).
 
 After the icons are installed, they can be used in the architecture diagram by using the format "name:icon-name", where name is the value used when registering the icon pack.
 
diff --git a/docs/syntax/flowchart.md b/docs/syntax/flowchart.md
index dd7be92074..3837e77de6 100644
--- a/docs/syntax/flowchart.md
+++ b/docs/syntax/flowchart.md
@@ -932,7 +932,7 @@ Mermaid also introduces 2 special shapes to enhance your flowcharts: **icon** an
 
 ### Icon Shape
 
-You can use the `icon` shape to include an icon in your flowchart. To use icons, you need to register the icon pack first. Follow the instructions provided [here](https://mermaid.js.org/config/icons.html). The syntax for defining an icon shape is as follows:
+You can use the `icon` shape to include an icon in your flowchart. To use icons, you need to register the icon pack first. Follow the instructions provided [here](../config/icons.md). The syntax for defining an icon shape is as follows:
 
 ```mermaid-example
 flowchart TD
diff --git a/packages/mermaid/src/docs/syntax/architecture.md b/packages/mermaid/src/docs/syntax/architecture.md
index 53da754c94..2c4de5fd9e 100644
--- a/packages/mermaid/src/docs/syntax/architecture.md
+++ b/packages/mermaid/src/docs/syntax/architecture.md
@@ -156,7 +156,7 @@ architecture-beta
 ## Icons
 
 By default, architecture diagram supports the following icons: `cloud`, `database`, `disk`, `internet`, `server`.
-Users can use any of the 200,000+ icons available in iconify.design, or add their own custom icons, by following the steps [here](https://mermaid.js.org/config/icons.html).
+Users can use any of the 200,000+ icons available in iconify.design, or add their own custom icons, by following the steps [here](../config/icons.md).
 
 After the icons are installed, they can be used in the architecture diagram by using the format "name:icon-name", where name is the value used when registering the icon pack.
 
diff --git a/packages/mermaid/src/docs/syntax/flowchart.md b/packages/mermaid/src/docs/syntax/flowchart.md
index b48b8fb4c2..829b71c2dc 100644
--- a/packages/mermaid/src/docs/syntax/flowchart.md
+++ b/packages/mermaid/src/docs/syntax/flowchart.md
@@ -548,7 +548,7 @@ Mermaid also introduces 2 special shapes to enhance your flowcharts: **icon** an
 
 ### Icon Shape
 
-You can use the `icon` shape to include an icon in your flowchart. To use icons, you need to register the icon pack first. Follow the instructions provided [here](https://mermaid.js.org/config/icons.html). The syntax for defining an icon shape is as follows:
+You can use the `icon` shape to include an icon in your flowchart. To use icons, you need to register the icon pack first. Follow the instructions provided [here](../config/icons.md). The syntax for defining an icon shape is as follows:
 
 ```mermaid-example
 flowchart TD