@readme/markdown 13.7.2 → 13.7.4

package/components/CodeTabs/index.tsx

@@ -1,7 +1,7 @@
 import type { Mermaid } from 'mermaid';
 
 import syntaxHighlighterUtils from '@readme/syntax-highlighter/utils';
-import React, { useContext, useEffect } from 'react';
+import React, { useContext, useEffect, useRef } from 'react';
 
 import ThemeContext from '../../contexts/Theme';
 import useHydrated from '../../hooks/useHydrated';
@@ -10,6 +10,47 @@ let mermaid: Mermaid;
 
 const { uppercase } = syntaxHighlighterUtils;
 
+// Module-level queue that batches mermaid nodes across all CodeTabs instances into a
+// single mermaid.run() call. This is necessary because mermaid generates SVG element IDs
+// using Date.now(), which collides when multiple diagrams render in the same millisecond.
+// Colliding IDs cause diagrams to overlap or break layout.
+//
+// Why not use `deterministicIDSeed` with a unique ID per diagram? Mermaid's implementation
+// only uses seed.length (not the seed value) to compute the starting ID, so every UUID
+// (36 chars) produces the same `mermaid-36` prefix — the collision remains.
+// See: https://github.com/mermaid-js/mermaid/blob/mermaid%4011.12.0/packages/mermaid/src/utils.ts#L755-L761
+//
+// These vars must be module-scoped (not per-instance refs) because the batching requires
+// cross-instance coordination. They are short-lived: the queue drains on the next macrotask
+// and cleanup clears everything on unmount.
+let mermaidQueue: HTMLPreElement[] = [];
+let mermaidFlushTimer: ReturnType<typeof setTimeout> | null = null;
+let currentTheme: string | undefined;
+
+function queueMermaidNode(node: HTMLPreElement, theme: string) {
+  mermaidQueue.push(node);
+  currentTheme = theme;
+
+  if (!mermaidFlushTimer) {
+    // setTimeout(0) defers to a macrotask, after all useEffects have queued their nodes
+    mermaidFlushTimer = setTimeout(async () => {
+      const nodes = [...mermaidQueue];
+      mermaidQueue = [];
+      mermaidFlushTimer = null;
+
+      const module = await import('mermaid');
+      mermaid = module.default;
+      mermaid.initialize({
+        startOnLoad: false,
+        theme: currentTheme === 'dark' ? 'dark' : 'default',
+        deterministicIds: true,
+      });
+
+      await mermaid.run({ nodes });
+    }, 0);
+  }
+}
+
 interface Props {
   children: JSX.Element | JSX.Element[];
 }
@@ -18,6 +59,7 @@ const CodeTabs = (props: Props) => {
   const { children } = props;
   const theme = useContext(ThemeContext);
   const isHydrated = useHydrated();
+  const mermaidRef = useRef<HTMLPreElement>(null);
 
   // Handle both array (from rehype-react in rendering mdxish) and single element (MDX/JSX runtime) cases
   // The children here is the individual code block objects
@@ -32,22 +74,21 @@ const CodeTabs = (props: Props) => {
 
   const containAtLeastOneMermaid = childrenArray.some(pre => getCodeComponent(pre)?.props?.lang === 'mermaid');
 
-  // Render Mermaid diagram
   useEffect(() => {
-    // Ensure we only render mermaids when frontend is hydrated to avoid hydration errors
-    // because mermaid mutates the DOM before react hydrates
-    if (typeof window !== 'undefined' && containAtLeastOneMermaid && isHydrated) {
-      import('mermaid').then(module => {
-        mermaid = module.default;
-        mermaid.initialize({
-          startOnLoad: false,
-          theme: theme === 'dark' ? 'dark' : 'default',
-        });
-        mermaid.run({
-          nodes: document.querySelectorAll('.mermaid-render'),
-        });
-      });
+    // Wait for hydration so mermaid's DOM mutations don't cause mismatches
+    if (typeof window !== 'undefined' && containAtLeastOneMermaid && isHydrated && mermaidRef.current) {
+      queueMermaidNode(mermaidRef.current, theme);
     }
+
+    return () => {
+      // Clear the batch timer on unmount to prevent mermaid from running
+      // after the DOM is torn down
+      if (mermaidFlushTimer) {
+        clearTimeout(mermaidFlushTimer);
+        mermaidFlushTimer = null;
+        mermaidQueue = [];
+      }
+    };
   }, [containAtLeastOneMermaid, theme, isHydrated]);
 
   function handleClick({ target }, index: number) {
@@ -67,7 +108,11 @@ const CodeTabs = (props: Props) => {
     const codeComponent = getCodeComponent(childrenArray[0]);
     if (codeComponent?.props?.lang === 'mermaid') {
       const value = codeComponent?.props?.value;
-      return <pre className="mermaid-render mermaid_single">{value}</pre>;
+      return (
+        <pre ref={mermaidRef} className="mermaid-render mermaid_single">
+          {value}
+        </pre>
+      );
     }
   }
 
@@ -76,9 +121,7 @@ const CodeTabs = (props: Props) => {
       <div className="CodeTabs-toolbar">
         {childrenArray.map((pre, i) => {
           // the first or only child should be our Code component
-          const tabCodeComponent = Array.isArray(pre.props?.children)
-            ? pre.props.children[0]
-            : pre.props?.children;
+          const tabCodeComponent = Array.isArray(pre.props?.children) ? pre.props.children[0] : pre.props?.children;
           const lang = tabCodeComponent?.props?.lang;
           const meta = tabCodeComponent?.props?.meta;
 

package/components/Glossary/index.tsx

@@ -12,6 +12,9 @@ interface Props extends React.PropsWithChildren {
 
 const Glossary = ({ children, term: termProp, terms }: Props) => {
   const term = (Array.isArray(children) ? children[0] : children) || termProp;
+
+  if (!term) return null;
+
   const foundTerm = terms.find(i => term.toLowerCase() === i?.term?.toLowerCase());
 
   if (!foundTerm) return <span>{term}</span>;

package/components/TailwindStyle/index.tsx

@@ -75,20 +75,10 @@ const TailwindStyle = ({ children, darkModeDataAttribute }: Props) => {
       records.forEach(record => {
         if (record.type === 'childList') {
           record.addedNodes.forEach(node => {
-            if (!(node instanceof HTMLElement)) return;
-
-            // Check the added node itself
-            if (node.classList.contains(tailwindPrefix)) {
-              traverse(node, addClasses);
-              shouldUpdate = true;
-            }
-
-            // Also check descendants — React may insert a parent node
-            // whose children contain TailwindRoot elements
-            node.querySelectorAll(`.${tailwindPrefix}`).forEach(child => {
-              traverse(child, addClasses);
-              shouldUpdate = true;
-            });
+            if (!(node instanceof HTMLElement) || !node.classList.contains(tailwindPrefix)) return;
+
+            traverse(node, addClasses);
+            shouldUpdate = true;
           });
         } else if (record.type === 'attributes') {
           if (record.attributeName !== 'class' || !(record.target instanceof HTMLElement)) return;
@@ -97,10 +87,11 @@ const TailwindStyle = ({ children, darkModeDataAttribute }: Props) => {
           shouldUpdate = true;
         }
 
-        if (shouldUpdate) {
-          setClasses(Array.from(classesSet.current));
-        }
       });
+
+      if (shouldUpdate) {
+        setClasses(Array.from(classesSet.current));
+      }
     });
 
     observer.observe(ref.current.parentElement, {

package/dist/lib/mdast-util/gemoji/index.d.ts

@@ -0,0 +1,2 @@
+import type { Extension as FromMarkdownExtension } from 'mdast-util-from-markdown';
+export declare function gemojiFromMarkdown(): FromMarkdownExtension;

package/dist/lib/micromark/gemoji/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Micromark extension for :emoji: inline syntax.
+ */
+export { gemoji } from './syntax';

package/dist/lib/micromark/gemoji/syntax.d.ts

@@ -0,0 +1,9 @@
+import type { Extension } from 'micromark-util-types';
+declare module 'micromark-util-types' {
+    interface TokenTypeMap {
+        gemoji: 'gemoji';
+        gemojiMarker: 'gemojiMarker';
+        gemojiName: 'gemojiName';
+    }
+}
+export declare function gemoji(): Extension;