diff --git a/src/components/codeBlock/index.tsx b/src/components/codeBlock/index.tsx
index 11ce2217f080a..310df8d13b5a9 100644
--- a/src/components/codeBlock/index.tsx
+++ b/src/components/codeBlock/index.tsx
@@ -85,6 +85,11 @@ export function CodeBlock({filename, language, children}: CodeBlockProps) {
 
   useCleanSnippetInClipboard(codeRef, {language});
 
+  // Mermaid blocks should not be processed by CodeBlock - they need special client-side rendering
+  if (language === 'mermaid') {
+    return <div className="language-mermaid">{children}</div>;
+  }
+
   async function copyCodeOnClick() {
     if (codeRef.current === null) {
       return;
diff --git a/src/rehype-onboarding-lines.js b/src/rehype-onboarding-lines.js
index 58c0e27296b83..b1b86a6f89167 100644
--- a/src/rehype-onboarding-lines.js
+++ b/src/rehype-onboarding-lines.js
@@ -29,6 +29,10 @@ function visitor(node) {
   if (!node.properties.className?.includes('code-highlight')) {
     return;
   }
+  // ignore mermaid code blocks - they have special client-side rendering
+  if (node.properties.className?.includes('language-mermaid')) {
+    return;
+  }
   handle_inline_options(node);
 }