Supercharge AWS Diagrams in VSCode with Mermaid and Custom Icons

#architecture #aws #documentation #vscode

Want to turn your architecture docs into visual gold? With the new Mermaid.js architecture diagram syntax and custom icon packs, you can create AWS diagrams—all from within VSCode using Markdown.

This guide walks you through how to:

✅ Use Mermaid’s new architecture syntax
✅ Set up custom AWS and icon libraries
✅ Preview it all in VSCode using the Markdown Preview Enhanced extension

Let’s dive in. 👇

🔧 Icon Packs You'll Use

Here are the icon libraries we’ll pull in:

These icons can be referenced in your Mermaid diagrams by name (e.g. logos:aws-lambda, aws:aurora, fa: ,).

✅ Step 1: Install Markdown Preview Enhanced

First, install the Markdown Preview Enhanced extension in VSCode.

It enables rich previews for .md files—supporting Mermaid, LaTeX, charts, diagrams, and more.

⚙️ Step 2: Inject Icon Packs into Mermaid

We’ll now customize the Markdown preview to load external icon packs into Mermaid.

How to set it up:

In VSCode, press Ctrl + P, then type:

   > Markdown Preview Enhanced: Customize Preview Html Head (WORKSPACE)

Select the command. It will create a file:

   .crossnote/head.html

Paste the following code into that file:

<!-- Load custom icon packs for Mermaid architecture diagrams -->
<script type="text/javascript">
  const configureMermaidIconPacks = () => {
    window["mermaid"].registerIconPacks([
      {
        name: "logos",
        loader: () =>
          fetch("https://unpkg.com/@iconify-json/logos/icons.json").then(res =>
            res.json()
          ),
      },
      {
        name: "lucide",
        loader: () =>
          fetch("https://unpkg.com/@iconify-json/lucide/icons.json").then(res =>
            res.json()
          ),
      },
      {
        name: "fa",
        loader: () =>
          fetch("https://unpkg.com/@iconify-json/fa/icons.json").then(res =>
            res.json()
          ),
      },
      {
        name: "aws",
        loader: () =>
          fetch(
            "https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/aa30729ab2e125f13526020fa98ed5eb0ed86cc1/dist/aws-icons-mermaid.json"
          ).then(res => res.json()),
      },
    ]);
  };

  if (document.readyState !== "loading") {
    configureMermaidIconPacks();
  } else {
    document.addEventListener("DOMContentLoaded", () => {
      configureMermaidIconPacks();
    });
  }
</script>

This ensures Mermaid can load and render your custom icons directly in preview.

🖼️ Step 3: Create a Diagram with AWS Icons

Now create a .md file (e.g. README.md) and embed a Mermaid diagram using the new architecture syntax and icons.

Here’s a full example using AWS services:

Click to expand the Mermaid diagram example

---
config:
  theme: base
  themeVariables:
    darkMode: false
    archEdgeColor: "#232F3E"
    archEdgeArrowColor: "#232F3E"
    archGroupBorderColor: "#ff862a"
---
architecture-beta


service user_service(lucide:user)[Users via Web Browser]

group cdk_infra(cloud)[AWS CDK Infrastructure]

service waf(logos:aws-waf)[AWS WAF] in cdk_infra
service cloudfront(logos:aws-cloudfront)[Amazon CloudFront] in cdk_infra
service cognito(logos:aws-cognito)[Amazon Cognito] in cdk_infra
service s3_front(logos:aws-s3)[Amazon S3 Frontend Hosting] in cdk_infra
service apigw(logos:aws-api-gateway)[Amazon API Gateway] in cdk_infra
service appsync(logos:aws-appsync)[AWS AppSync] in cdk_infra
service cdk_deploy(aws:cloudformation)[AWS CDK Deployment] in cdk_infra

group vpc_private_subnet(cloud)[VPC Private Subnet] in cdk_infra

service lambda(logos:aws-lambda)[AWS Lambda] in vpc_private_subnet
service dynamodb(logos:aws-dynamodb)[Amazon DynamoDB] in vpc_private_subnet
service aurora(logos:aws-aurora)[Amazon Aurora PostgreSQL] in vpc_private_subnet
service sagemaker(aws:sagemaker)[Amazon SageMaker] in vpc_private_subnet
service bedrock(aws:bedrock)[Amazon Bedrock] in vpc_private_subnet
service step_functions(logos:aws-step-functions)[AWS Step Functions] in vpc_private_subnet
service s3_ingest(logos:aws-s3)[Amazon S3 Ingestion] in vpc_private_subnet
service lambda_ingest(logos:aws-lambda)[AWS Lambda Ingestion] in vpc_private_subnet


user_service:R --&gt; L:waf
waf:R --&gt; L:cloudfront
cloudfront:R --&gt; L:cognito
cognito:R --&gt; L:s3_front
s3_front:R --&gt; L:apigw
s3_front:B --&gt; L:appsync
apigw:R --&gt; L:lambda
appsync:R --&gt; L:lambda
lambda:R --&gt; L:dynamodb
lambda:B --&gt; T:aurora
lambda:T --&gt; B:bedrock
sagemaker:R --&gt; B:s3_ingest
step_functions:R --&gt; L:s3_ingest
s3_ingest:R --&gt; L:lambda_ingest
lambda_ingest:R --&gt; L:dynamodb
lambda_ingest:R --&gt; L:aurora
cdk_deploy:R --&gt; L:step_functions

view in the Mermaid Live Editor