From 78dfffa1a7ac4c8d55a9103fab23f1fc0331417c Mon Sep 17 00:00:00 2001
From: NicolasNewman <nanewman01@gmail.com>
Date: Tue, 9 Jul 2024 15:51:03 -0500
Subject: [PATCH] docs(arch): icon documentation

---
 docs/config/icons.md                          | 61 +++++++++++++++++++
 .../mermaid/src/docs/.vitepress/config.ts     |  1 +
 packages/mermaid/src/docs/config/icons.md     | 55 +++++++++++++++++
 3 files changed, 117 insertions(+)
 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 000000000..58487acbb
--- /dev/null
+++ b/docs/config/icons.md
@@ -0,0 +1,61 @@
+> **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).
+
+# SVG Icons (v???+)
+
+SVG Icons can be used with supported diagrams. Alongside the icon packs included with Mermaid, 3rd party libraries can be included in the configuration to cover additional use-cases.
+
+## Supported Diagrams
+
+| Diagram      | Usage                             |
+| ------------ | --------------------------------- |
+| Architecture | Icon names are surrounded by `()` |
+
+## Included Icon Packs
+
+| Icon Pack     | Prefix |
+| ------------- | ------ |
+| default       | N/A    |
+| Amazon AWS    | `aws:` |
+| Digital Ocean | `do:`  |
+| GitHub        | `gh:`  |
+
+### Extended AWS Icons
+
+Due to the large number of icons available to represent AWS services, only the most important ones are enabled by default. For full access, add `'aws:full'` to the `iconLibraries` field when initializing mermaid.
+
+## Using Custom Icon Packs
+
+Custom icon packs can be used by including them in the `iconLibraries` array on mermaid initialization.
+
+```js
+import sampleIconPack from 'sample-icon-pack';
+
+mermaid.initialize({
+  iconLibraries: [sampleIconPack, 'aws:full'],
+});
+```
+
+## Creating Custom Icon Packs
+
+```js
+import { createIcon } from 'mermaid';
+import type { IconLibrary, IconResolver } from 'mermaid';
+
+// type IconLibrary = Record<string, IconResolver>;
+// createIcon: (icon: string, originalSize: number) => IconResolver
+const myIconLibrary: IconLibrary = {
+  defaultCloudExample: createIcon(
+        `<g>
+            <rect width="80" height="80" style="fill: #087ebf; stroke-width: 0px;"/>
+            <path d="..." style="fill: none; stroke: #fff; stroke-miterlimit: 10; stroke-width: 2px;"/>
+        </g>`,
+        80
+    )
+};
+
+export default myIconLibrary
+```
diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts
index 619de961d..ebbab35c7 100644
--- a/packages/mermaid/src/docs/.vitepress/config.ts
+++ b/packages/mermaid/src/docs/.vitepress/config.ts
@@ -177,6 +177,7 @@ function sidebarConfig() {
         { text: 'Directives', link: '/config/directives' },
         { text: 'Theming', link: '/config/theming' },
         { text: 'Math', link: '/config/math' },
+        { text: 'Icons', link: '/config/icons' },
         { text: 'Accessibility', link: '/config/accessibility' },
         { text: 'Mermaid CLI', link: '/config/mermaidCLI' },
         { text: 'FAQ', link: '/config/faq' },
diff --git a/packages/mermaid/src/docs/config/icons.md b/packages/mermaid/src/docs/config/icons.md
new file mode 100644
index 000000000..285037182
--- /dev/null
+++ b/packages/mermaid/src/docs/config/icons.md
@@ -0,0 +1,55 @@
+# SVG Icons (v???+)
+
+SVG Icons can be used with supported diagrams. Alongside the icon packs included with Mermaid, 3rd party libraries can be included in the configuration to cover additional use-cases.
+
+## Supported Diagrams
+
+| Diagram      | Usage                             |
+| ------------ | --------------------------------- |
+| Architecture | Icon names are surrounded by `()` |
+
+## Included Icon Packs
+
+| Icon Pack     | Prefix |
+| ------------- | ------ |
+| default       | N/A    |
+| Amazon AWS    | `aws:` |
+| Digital Ocean | `do:`  |
+| GitHub        | `gh:`  |
+
+### Extended AWS Icons
+
+Due to the large number of icons available to represent AWS services, only the most important ones are enabled by default. For full access, add `'aws:full'` to the `iconLibraries` field when initializing mermaid.
+
+## Using Custom Icon Packs
+
+Custom icon packs can be used by including them in the `iconLibraries` array on mermaid initialization.
+
+```js
+import sampleIconPack from 'sample-icon-pack';
+
+mermaid.initialize({
+  iconLibraries: [sampleIconPack, 'aws:full'],
+});
+```
+
+## Creating Custom Icon Packs
+
+```js
+import { createIcon } from 'mermaid';
+import type { IconLibrary, IconResolver } from 'mermaid';
+
+// type IconLibrary = Record<string, IconResolver>;
+// createIcon: (icon: string, originalSize: number) => IconResolver
+const myIconLibrary: IconLibrary = {
+  defaultCloudExample: createIcon(
+        `<g>
+            <rect width="80" height="80" style="fill: #087ebf; stroke-width: 0px;"/>
+            <path d="..." style="fill: none; stroke: #fff; stroke-miterlimit: 10; stroke-width: 2px;"/>
+        </g>`,
+        80
+    )
+};
+
+export default myIconLibrary
+```