diff --git a/.gitignore b/.gitignore
index df34a5706..816160c9f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+.DS_Store
 node_modules
 /lib/
 /test/
diff --git a/README.md b/README.md
index a09214db1..bb35b5781 100644
--- a/README.md
+++ b/README.md
@@ -113,7 +113,9 @@ Displays the file size of the bundled library (dist/bundled.js) in bytes.
 
 ### icons
 
-Generates icon list for the documentation site
+Generates icon list for the documentation site. The output of this script should
+replace the `List of icons` section inside
+the `vscode-elements.github.io/src/content/docs/components/icon.mdx` so the docs stay in sync with the latest Codicon set.
 
 ### vscode-data
 
diff --git a/package-lock.json b/package-lock.json
index d12b36969..4d301f8eb 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -60,6 +60,9 @@
         "ts-lit-plugin": "^2.0.2",
         "typescript": "^5.8.2",
         "wireit": "^0.14.11"
+      },
+      "peerDependencies": {
+        "@vscode/codicons": ">=0.0.40"
       }
     },
     "node_modules/@awmottaz/prettier-plugin-void-html": {
diff --git a/package.json b/package.json
index a4000fabd..935daf05b 100644
--- a/package.json
+++ b/package.json
@@ -135,6 +135,9 @@
     "@lit/context": "^1.1.3",
     "lit": "^3.2.1"
   },
+  "peerDependencies": {
+    "@vscode/codicons": ">=0.0.40"
+  },
   "devDependencies": {
     "@awmottaz/prettier-plugin-void-html": "^2.0.0",
     "@bendera/wds-plugin-directory-index": "^0.5.0",
diff --git a/scripts/generateIconList.js b/scripts/generateIconList.js
index 690183b80..26ccd9155 100644
--- a/scripts/generateIconList.js
+++ b/scripts/generateIconList.js
@@ -1,19 +1,22 @@
 import fs from 'fs';
+import prettier from 'prettier';
 
 fs.readFile(
   './node_modules/@vscode/codicons/src/template/mapping.json',
   'utf-8',
-  (err, data) => {
+  async (err, data) => {
     if (err) {
       throw err;
     }
 
     const iconMap = JSON.parse(data);
     const keys = Object.keys(iconMap).sort();
+    const raw = keys
+      .map((k) => `<vscode-icon name="${k}" title="${k}"></vscode-icon>`)
+      .join('\n');
+    const formatted = await prettier.format(raw, {parser: 'html'});
 
-    keys.forEach((k) => {
-      // eslint-disable-next-line no-undef
-      console.log(`<vscode-icon name="${k}" title="${k}"></vscode-icon>`);
-    });
+    // eslint-disable-next-line no-undef
+    console.log(formatted);
   }
 );