docs: add remote markdown and mermaid rendering

components/CopyRawButton.js

@@ -1,18 +1,22 @@
 import { useState } from 'react';
 import { useRouter } from 'next/router';
 
-function getRawUrl(currentPath) {
+function getGeneratedRawUrl(currentPath) {
   if (currentPath === '/') return '/raw/index.md';
   return `/raw${currentPath}.md`;
 }
 
-export function CopyRawButton() {
+/**
+ * Render page-level actions for copying or viewing the Markdown source for the current docs page.
+ * Pages that render canonical Markdown from another repository can set `rawUrl` in frontmatter so these actions use that source instead of the generated local fallback.
+ */
+export function CopyRawButton({ frontmatter }) {
   const [copied, setCopied] = useState(false);
   const [copyError, setCopyError] = useState(false);
   const [isCopying, setIsCopying] = useState(false);
   const router = useRouter();
   const currentPath = router.asPath.split('#')[0].split('?')[0] || '/';
-  const rawUrl = getRawUrl(currentPath);
+  const rawUrl = frontmatter?.rawUrl || getGeneratedRawUrl(currentPath);
 
   const handleCopy = async () => {
     setIsCopying(true);

components/Layout.js

@@ -201,7 +201,7 @@ export default function Layout({ children, frontmatter }) {
 
         <main className="layout-content" id="main-content">
           <Breadcrumbs />
-          {frontmatter && <CopyRawButton />}
+          {frontmatter && <CopyRawButton frontmatter={frontmatter} />}
           <LastUpdated />
           <article>{children}</article>
 

components/MermaidDiagram.js

@@ -0,0 +1,116 @@
+import { useEffect, useMemo, useState } from 'react';
+import { CodeBlock } from './CodeBlock';
+
+let mermaidModulePromise;
+let diagramIdCounter = 0;
+
+function getMermaid() {
+  if (!mermaidModulePromise) {
+    mermaidModulePromise = import('mermaid').then((module) => {
+      const mermaid = module.default || module;
+      return mermaid;
+    });
+  }
+
+  return mermaidModulePromise;
+}
+
+function getDiagramId() {
+  diagramIdCounter += 1;
+  return `mermaid-diagram-${diagramIdCounter}`;
+}
+
+function getPreferredMermaidTheme() {
+  if (typeof document !== 'undefined' && document.documentElement.classList.contains('dark')) {
+    return 'dark';
+  }
+
+  return 'neutral';
+}
+
+/**
+ * Render a Mermaid fenced code block as an SVG diagram in the browser.
+ * Use this for Markdown fences with `mermaid` as the language; invalid diagrams fall back to copyable code with an actionable syntax error.
+ */
+export function MermaidDiagram({ chart, children }) {
+  const source = (chart || children || '').trim();
+  const diagramId = useMemo(getDiagramId, []);
+  const [svg, setSvg] = useState('');
+  const [error, setError] = useState(null);
+  const [loading, setLoading] = useState(Boolean(source));
+  const [theme, setTheme] = useState('neutral');
+
+  useEffect(() => {
+    const updateTheme = () => setTheme(getPreferredMermaidTheme());
+    updateTheme();
+
+    const observer = new MutationObserver(updateTheme);
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
+
+    return () => observer.disconnect();
+  }, []);
+
+  useEffect(() => {
+    if (!source) {
+      setLoading(false);
+      setError(new Error('No Mermaid source was provided. Add diagram text inside the mermaid code fence.'));
+      return undefined;
+    }
+
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    setSvg('');
+
+    async function renderDiagram() {
+      try {
+        const mermaid = await getMermaid();
+        mermaid.initialize({
+          startOnLoad: false,
+          securityLevel: 'strict',
+          theme,
+        });
+        const result = await mermaid.render(diagramId, source);
+        if (cancelled) return;
+        setSvg(result.svg);
+      } catch (err) {
+        if (cancelled) return;
+        setError(err);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    }
+
+    renderDiagram();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [diagramId, source, theme]);
+
+  if (error) {
+    return (
+      <div className="mermaid-diagram mermaid-diagram--error">
+        <p>
+          <strong>Could not render Mermaid diagram.</strong> Check the diagram syntax in the source Markdown and reload the page. Details: {error.message}
+        </p>
+        <CodeBlock content={source} language="mermaid" />
+      </div>
+    );
+  }
+
+  if (loading) {
+    return (
+      <div className="mermaid-diagram mermaid-diagram--loading" role="status">
+        Rendering Mermaid diagram…
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="mermaid-diagram"
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  );
+}