[docs] Place Quick Nav after the main demo in the DOM

docs/src/components/demo/index.css

@@ -3,6 +3,15 @@
     background-color: var(--color-content);
     border: 1px solid var(--color-gray-200);
     border-radius: var(--radius-md);
+
+    /* Coordinate the placement of Quick Nav that follows the main Demo */
+    &[data-before-quick-nav] {
+      float: left;
+      width: 100%;
+      & + * + * {
+        clear: left;
+      }
+    }
   }
 
   .DemoPlayground {

docs/src/components/quick-nav/rehypeQuickNav.mjs

@@ -6,6 +6,7 @@ const TITLE = 'QuickNav.Title';
 const LIST = 'QuickNav.List';
 const ITEM = 'QuickNav.Item';
 const LINK = 'QuickNav.Link';
+const DOC_DEMO = 'Demo';
 const DOC_SUBTITLE = 'Subtitle';
 
 /**
@@ -21,22 +22,57 @@ const DOC_SUBTITLE = 'Subtitle';
  */
 export function rehypeQuickNav() {
   return (tree, file) => {
-    const h1 = tree.children.find(
-      /** @param {{ tagName: string; }} node */
-      (node) => node.tagName === 'h1',
-    );
-
     /** @type {TocEntry[]} */
     const toc = file.data.toc;
     const root = createMdxElement({
       name: ROOT,
       children: toc.flatMap(getNodeFromEntry).filter(Boolean),
     });
 
-    // Place quick nav after the `<Subtitle>` that immediately follows the first `<h1>`,
-    // or after the first `<h1>` if a matching `<Subtitle>` wasn't found.
-    let index = tree.children.indexOf(h1) + 2; // Adding "2" because there's also a line break below h1
-    index = tree.children[index]?.name === DOC_SUBTITLE ? index + 1 : index;
+    // Determine the placement of Quick Nav up next
+
+    /** @type {{ tagName?: string; name?: string; attributes?: Record<string, string>[] }[]} */
+    const contentNodes = tree.children.filter(
+      /** @param {{ type?: string; value?: string;  }} child */
+      (child) => {
+        return (
+          // Filter out import statements
+          child.type !== 'mdxjsEsm' &&
+          // Filter out plain line breaks
+          child.value !== '\n'
+        );
+      },
+    );
+
+    const h1 = tree.children.find(
+      /** @param {{ tagName: string; }} node */
+      (node) => node.tagName === 'h1',
+    );
+
+    const subtitle = contentNodes.find((node, i) => {
+      const prev = contentNodes[i - 1];
+      return node.name === DOC_SUBTITLE && prev === h1;
+    });
+
+    let nodeBefore = contentNodes.find((node, i) => {
+      const prev = contentNodes[i - 1];
+      return node.name === DOC_DEMO && prev === subtitle;
+    });
+
+    // Add a styling hook if a `<Demo>` element was found
+    if (nodeBefore) {
+      nodeBefore.attributes ??= [];
+      nodeBefore.attributes.push({
+        type: 'mdxJsxAttribute',
+        name: 'data-before-quick-nav',
+        value: '',
+      });
+    } else {
+      // Otherwise, place the Quick Nav node after a fallback
+      nodeBefore = subtitle ?? h1;
+    }
+
+    const index = tree.children.indexOf(nodeBefore) + 1;
     tree.children.splice(index, 0, root);
   };
 }

docs/src/mdx-components.tsx

@@ -52,7 +52,9 @@ export const mdxComponents: MDXComponents = {
   td: Table.Cell,
 
   // Custom components
-  Demo: (props) => <DemoLoader className="mt-5 mb-8" {...props} />,
+  Demo: (props) => (
+    <DemoLoader className={'data-before-quick-nav' in props ? 'mb-10' : 'mt-5 mb-8'} {...props} />
+  ),
   QuickNav,
   AttributesTable: (props) => <AttributesTable className="mt-5 mb-6" {...props} />,
   CssVariablesTable: (props) => <CssVariablesTable className="mt-5 mb-6" {...props} />,