Render diagrams at build time with Pele and improve integration icons

src/frontend/config/remark-mermaid.mjs

@@ -1,4 +1,7 @@
-/** Turn opted-in fences into plain pre elements before code highlighting. */
+import { fromHtml } from 'hast-util-from-html';
+import { renderMermaid } from '../src/utils/mermaid.mjs';
+
+/** Render opted-in fences before code highlighting, including nested MDX content. */
 export function remarkMermaid() {
   return (tree) => {
     function visit(parent) {
@@ -9,8 +12,8 @@ export function remarkMermaid() {
             children: [],
             data: {
               hName: 'pre',
-              hProperties: { className: ['mermaid'] },
-              hChildren: [{ type: 'text', value: node.value }],
+              hProperties: { className: ['mermaid'], 'data-processed': 'true' },
+              hChildren: fromHtml(renderMermaid(node.value), { fragment: true }).children,
             },
             position: node.position,
           };

src/frontend/package.json

@@ -78,15 +78,21 @@
     "@fontsource-variable/fira-code": "^5.3.0",
     "@fontsource-variable/rubik": "^5.3.0",
     "@fontsource/poppins": "^5.3.0",
+    "@iconify-json/iconoir": "^1.2.12",
+    "@iconify-json/logos": "^1.2.18",
+    "@iconify/utils": "3.1.4",
     "@lunariajs/core": "^0.1.1",
     "@lunariajs/starlight": "^0.1.1",
     "@mdx-js/mdx": "^3.1.1",
     "asciinema-player": "^3.17.0",
     "astro": "^7.4.1",
     "astro-expressive-code": "^0.44.1",
+    "fontkitten": "1.0.3",
     "hast-util-to-html": "^9.0.5",
+    "hast-util-from-html": "^2.0.3",
     "mdast-util-to-hast": "^13.2.1",
     "mermaid": "^11.16.1",
+    "pele": "1.12.0",
     "remark-directive": "^4.0.0",
     "satori": "^0.28.1",
     "satteri": "^0.9.5",

src/frontend/src/components/SampleReadmeBlocks.astro

@@ -21,6 +21,7 @@ import {
   toSentenceCase,
 } from '@utils/sample-readme-headings';
 import { isStandaloneSampleImageBlock } from '@utils/sample-readme-images';
+import { renderMermaid } from '@utils/mermaid.mjs';
 
 interface Props {
   blocks: RootContent[];
@@ -224,7 +225,7 @@ function matchGitHubAlert(block: Blockquote): GitHubAlert | null {
     if (block.type === 'code') {
       const code = getCodeProps(block);
       if (code.lang.toLowerCase() === 'mermaid') {
-        return <pre class="mermaid">{code.code}</pre>;
+        return <pre class="mermaid" data-processed="true" set:html={renderMermaid(code.code)} />;
       }
 
       return <Code code={code.code} lang={code.lang} meta={code.meta} />;

src/frontend/src/components/api-reference/InheritanceDiagram.astro

@@ -9,6 +9,7 @@ interface Props {
 }
 
 import { shortTypeName } from '@utils/packages';
+import { renderMermaid } from '@utils/mermaid.mjs';
 
 const { type, allTypes = [] } = Astro.props;
 
@@ -71,7 +72,7 @@ if (shouldRender) {
 
 {shouldRender && (
   <div class="inheritance-diagram">
-    <pre class="mermaid" set:text={diagram} />
+    <pre class="mermaid" data-processed="true" set:html={renderMermaid(diagram)} />
   </div>
 )}
 

src/frontend/src/components/starlight/Head.astro

@@ -57,7 +57,6 @@ function computeSourceUrl() {
 }
 <script>
   import '@scripts/deployment-guard';
-  import '@scripts/mermaid';
 
   document.addEventListener('astro:before-swap', (event) => {
     const theme = document.documentElement.dataset.theme;

src/frontend/src/content/docs/community/contributor-guide.mdx

@@ -546,7 +546,11 @@ The `aspire.dev` site supports several Markdown extensions to enhance your docum
 
 ### Mermaid diagrams
 
-You can write mermaid diagrams as code blocks:
+You can write Mermaid diagrams as code blocks. Pele renders these diagrams to SVG during page generation, and their colors follow the selected site theme without browser-side re-rendering. Architecture diagrams support the `logos`, `iconoir`, and custom `aspire` icon packs.
+
+Use technology-specific icons for named resources, such as `logos:redis`, `logos:postgresql`, or `logos:rabbitmq-icon`. Use role icons for language-neutral concepts: `iconoir:network` for AppHost, `iconoir:puzzle` for hosting integrations, `iconoir:server-connection` for client integrations, and `iconoir:code` for applications. Keep built-in icons such as `server` and `database` for unspecified infrastructure or technologies without a suitable bundled logo.
+
+Reuse existing product artwork from `src/assets/icons/` through the local `aspire` pack when the `logos` pack has no suitable logo, such as `aspire:microsoft-foundry` or `aspire:azure-key-vault`. The renderer embeds these assets and preserves their aspect ratios, including light and dark variants where available. Choose conceptual icons by meaning: `iconoir:sparks` for AI models and deployments, `iconoir:key` for secrets, and `iconoir:folder` for workspaces. Use current product names in labels without changing API or package identifiers.
 
 ````md title="src/content/docs/example.md"
 ```mermaid

src/frontend/src/content/docs/integrations/ai/ollama/ollama-get-started.mdx

@@ -41,14 +41,14 @@ The Ollama integration has two sides: a **hosting integration** that you use in
 ```mermaid
 architecture-beta
 
-  group apphost(server)[AppHost]
-  group consumer(server)[Consuming app]
+  group apphost(iconoir:network)[AppHost]
+  group consumer(iconoir:app-window)[Consuming app]
 
-  service hosting(server)[Hosting integration] in apphost
-  service ollama(server)[Ollama server] in apphost
-  service model(database)[Model resource] in apphost
+  service hosting(iconoir:puzzle)[Hosting integration] in apphost
+  service ollama(logos:ollama)[Ollama server] in apphost
+  service model(iconoir:sparks)[Model resource] in apphost
 
-  service app(server)[App] in consumer
+  service app(iconoir:code)[App] in consumer
 
   hosting:R --> L:ollama
   ollama:R --> L:model

src/frontend/src/content/docs/integrations/ai/openai/openai-get-started.mdx

@@ -37,15 +37,15 @@ The OpenAI integration has two sides: a **hosting integration** that you use in
 ```mermaid
 architecture-beta
 
-  group apphost(server)[AppHost]
-  group consumer(server)[Consuming app]
+  group apphost(iconoir:network)[AppHost]
+  group consumer(iconoir:app-window)[Consuming app]
 
-  service hosting(server)[Hosting integration] in apphost
-  service openai(internet)[OpenAI API] in apphost
-  service model(database)[chat model] in apphost
+  service hosting(iconoir:puzzle)[Hosting integration] in apphost
+  service openai(logos:openai-icon)[OpenAI API] in apphost
+  service model(iconoir:sparks)[chat model] in apphost
 
   service client(iconoir:server-connection)[Client integration] in consumer
-  service app(server)[App] in consumer
+  service app(iconoir:code)[App] in consumer
 
   hosting:R --> L:openai
   openai:R --> L:model

src/frontend/src/content/docs/integrations/ai/squad/squad-get-started.mdx

@@ -21,12 +21,12 @@ The integration does not start an agent process or service. Add the separate `Sq
 
 ```mermaid
 architecture-beta
-  group apphost(server)[AppHost]
-  group consumer(server)[Consuming app]
+  group apphost(iconoir:network)[AppHost]
+  group consumer(iconoir:app-window)[Consuming app]
 
-  service hosting(server)[Squad resource] in apphost
-  service team(database)[Squad workspace] in apphost
-  service app(server)[Service] in consumer
+  service hosting(iconoir:puzzle)[Squad resource] in apphost
+  service team(iconoir:folder)[Squad workspace] in apphost
+  service app(iconoir:code)[Service] in consumer
 
   hosting:R --> L:team
   hosting:R --> L:app

src/frontend/src/content/docs/integrations/ai/stable-diffusion-cpp/stable-diffusion-cpp-get-started.mdx

@@ -23,13 +23,13 @@ The hosting package runs the stable-diffusion.cpp container, downloads one Huggi
 ```mermaid
 architecture-beta
 
-  group apphost(server)[AppHost]
-  group consumer(server)[Consuming app]
+  group apphost(iconoir:network)[AppHost]
+  group consumer(iconoir:app-window)[Consuming app]
 
-  service hosting(server)[Hosting integration] in apphost
-  service server(server)[stable-diffusion.cpp server] in apphost
-  service model(database)[Hugging Face model] in apphost
-  service app(server)[Application] in consumer
+  service hosting(iconoir:puzzle)[Hosting integration] in apphost
+  service server(iconoir:sparks)[stable-diffusion.cpp server] in apphost
+  service model(logos:hugging-face-icon)[Hugging Face model] in apphost
+  service app(iconoir:code)[Application] in consumer
 
   hosting:R --> L:server
   server:R --> L:model

src/frontend/src/content/docs/integrations/caching/garnet/garnet-get-started.mdx

@@ -36,14 +36,14 @@ The Garnet integration has two sides: a **hosting integration** that you use in
 ```mermaid
 architecture-beta
 
-  group apphost(server)[AppHost]
-  group consumer(server)[Consuming app]
+  group apphost(iconoir:network)[AppHost]
+  group consumer(iconoir:app-window)[Consuming app]
 
-  service hosting(server)[Hosting integration] in apphost
-  service garnet(server)[Garnet server] in apphost
+  service hosting(iconoir:puzzle)[Hosting integration] in apphost
+  service garnet(aspire:garnet)[Garnet server] in apphost
 
   service client(iconoir:server-connection)[Client integration] in consumer
-  service app(server)[App] in consumer
+  service app(iconoir:code)[App] in consumer
 
   hosting:R --> L:garnet
   garnet:R --> L:client

src/frontend/src/content/docs/integrations/caching/redis-distributed/redis-distributed-get-started.mdx

@@ -36,14 +36,14 @@ The Redis distributed caching integration has two sides: the **hosting integrati
 ```mermaid
 architecture-beta
 
-  group apphost(server)[AppHost]
-  group consumer(server)[Consuming app]
+  group apphost(iconoir:network)[AppHost]
+  group consumer(iconoir:app-window)[Consuming app]
 
-  service hosting(server)[Hosting integration] in apphost
-  service redis(server)[Redis server] in apphost
+  service hosting(iconoir:puzzle)[Hosting integration] in apphost
+  service redis(logos:redis)[Redis server] in apphost
 
   service client(iconoir:server-connection)[StackExchange Redis distributed cache client] in consumer
-  service app(server)[App] in consumer
+  service app(iconoir:code)[App] in consumer
 
   hosting:R --> L:redis
   redis:R --> L:client

src/frontend/src/content/docs/integrations/caching/redis-output/redis-output-get-started.mdx

@@ -35,14 +35,14 @@ The Redis output caching integration has two sides: a **hosting integration** th
 ```mermaid
 architecture-beta
 
-  group apphost(server)[AppHost]
-  group consumer(server)[ASP NET Core app]
+  group apphost(iconoir:network)[AppHost]
+  group consumer(iconoir:app-window)[ASP NET Core app]
 
-  service hosting(server)[Hosting integration] in apphost
-  service redis(server)[Redis server] in apphost
+  service hosting(iconoir:puzzle)[Hosting integration] in apphost
+  service redis(logos:redis)[Redis server] in apphost
 
   service client(iconoir:server-connection)[StackExchange Redis output cache client] in consumer
-  service app(server)[App] in consumer
+  service app(iconoir:code)[App] in consumer
 
   hosting:R --> L:redis
   redis:R --> L:client

src/frontend/src/content/docs/integrations/caching/redis/redis-get-started.mdx

@@ -37,14 +37,14 @@ The Redis integration has two sides: a **hosting integration** that you use in y
 ```mermaid
 architecture-beta
 
-  group apphost(server)[AppHost]
-  group consumer(server)[Consuming app]
+  group apphost(iconoir:network)[AppHost]
+  group consumer(iconoir:app-window)[Consuming app]
 
-  service hosting(server)[Hosting integration] in apphost
-  service redis(server)[Redis server] in apphost
+  service hosting(iconoir:puzzle)[Hosting integration] in apphost
+  service redis(logos:redis)[Redis server] in apphost
 
   service client(iconoir:server-connection)[Client integration] in consumer
-  service app(server)[App] in consumer
+  service app(iconoir:code)[App] in consumer
 
   hosting:R --> L:redis
   redis:R --> L:client

src/frontend/src/content/docs/integrations/caching/valkey/valkey-get-started.mdx

@@ -36,14 +36,14 @@ The Valkey integration has two sides: a **hosting integration** that you use in
 ```mermaid
 architecture-beta
 
-  group apphost(server)[AppHost]
-  group consumer(server)[Consuming app]
+  group apphost(iconoir:network)[AppHost]
+  group consumer(iconoir:app-window)[Consuming app]
 
-  service hosting(server)[Hosting integration] in apphost
-  service valkey(server)[Valkey server] in apphost
+  service hosting(iconoir:puzzle)[Hosting integration] in apphost
+  service valkey(logos:valkey-icon)[Valkey server] in apphost
 
   service client(iconoir:server-connection)[Client integration] in consumer
-  service app(server)[App] in consumer
+  service app(iconoir:code)[App] in consumer
 
   hosting:R --> L:valkey
   valkey:R --> L:client