diff --git a/scripts/docs-site/assets.mjs b/scripts/docs-site/assets.mjs
index 248e05cfb..fe38c5f0c 100644
--- a/scripts/docs-site/assets.mjs
+++ b/scripts/docs-site/assets.mjs
@@ -13,7 +13,7 @@ export function siteCss() {
 
 export function siteJs() {
   return `
-const root=document.documentElement;const saved=localStorage.getItem("theme");if(saved)root.dataset.theme=saved;document.querySelector("[data-theme]")?.addEventListener("click",()=>{const next=root.dataset.theme==="dark"?"light":"dark";root.dataset.theme=next;localStorage.setItem("theme",next)});
+const root=document.documentElement;const saved=localStorage.getItem("theme");if(saved)root.dataset.theme=saved;document.querySelector("[data-theme-toggle]")?.addEventListener("click",()=>{const next=root.dataset.theme==="dark"?"light":"dark";root.dataset.theme=next;localStorage.setItem("theme",next)});
 const sidebar=document.querySelector(".sidebar");document.querySelector("[data-nav-toggle]")?.addEventListener("click",()=>sidebar?.classList.toggle("open"));document.querySelectorAll(".sidebar a").forEach(a=>a.addEventListener("click",()=>sidebar?.classList.remove("open")));
 document.querySelector("[data-locale]")?.addEventListener("change",e=>{const url=e.target.selectedOptions[0]?.dataset.url;if(url)location.href=url});
 const modal=document.querySelector(".search-modal");const input=document.querySelector("[data-search-input]");const results=document.querySelector("[data-search-results]");let pagefindReady;
diff --git a/scripts/docs-site/build.mjs b/scripts/docs-site/build.mjs
index 08033b242..e6a6ca329 100644
--- a/scripts/docs-site/build.mjs
+++ b/scripts/docs-site/build.mjs
@@ -173,7 +173,7 @@ function sidebar(page, nav, activeTab) {
   const groups = (nav.find((tab) => tab.title === activeTab) ?? nav[0])?.groups ?? [];
   return `<aside class="sidebar">
 <a class="brand" href="${page.locale === "en" ? "/" : `/${page.locale}/`}"><img src="/assets/pixel-lobster.svg" alt=""><span><strong>${escapeHtml(config.name)}</strong><small>self-hosted agent gateway</small></span></a>
-<div class="tools"><select data-locale aria-label="Language">${options}</select><button type="button" data-theme>Theme</button></div>
+<div class="tools"><select data-locale aria-label="Language">${options}</select><button type="button" data-theme-toggle>Theme</button></div>
 <button class="search-button" type="button" data-search-open>Search docs <span>⌘K</span></button>
 <nav class="tabs">${tabs}</nav>
 <nav>${groups.map((group) => navGroupHtml(page, group)).join("")}</nav>
diff --git a/scripts/docs-site/mdx-ish.mjs b/scripts/docs-site/mdx-ish.mjs
index beb1d1cd2..811fc172c 100644
--- a/scripts/docs-site/mdx-ish.mjs
+++ b/scripts/docs-site/mdx-ish.mjs
@@ -69,7 +69,7 @@ function preprocess(input) {
 
   out = out.replace(/<([A-Z][A-Za-z0-9_.-]*)([^>]*)>/g, (_, name, attrs) => escapeHtml(`<${name}${attrs}>`));
   out = out.replace(/<\/([A-Z][A-Za-z0-9_.-]*)>/g, (_, name) => escapeHtml(`</${name}>`));
-  return out;
+  return dedentComponentChildren(out);
 }
 
 function postprocess(html) {
@@ -89,7 +89,7 @@ function expandMarker(payload) {
   if (kind === "calloutClose") return "</aside>";
   if (kind === "cardSelf") return cardHtml(value, true);
   if (kind === "cardOpen") return cardHtml(value, false);
-  if (kind === "cardClose") return "</span></a>";
+  if (kind === "cardClose") return "</div></a>";
   if (kind === "stepOpen") return `<li class="oc-step"><h3>${escapeHtml(parseAttrs(value).title ?? "Step")}</h3>`;
   if (kind === "stepClose") return "</li>";
   if (kind === "tabOpen") return `<section class="oc-tab"><h3>${escapeHtml(parseAttrs(value).title ?? "Tab")}</h3>`;
@@ -111,8 +111,30 @@ function cardHtml(rawAttrs, selfClosing) {
   const href = attrs.href ?? "#";
   const title = attrs.title ?? attrs.name ?? "Open";
   const icon = attrs.icon ? `<span class="oc-card-icon">${escapeHtml(attrs.icon)}</span>` : "";
-  const end = selfClosing ? "</span></a>" : "";
-  return `<a class="oc-card" href="${escapeAttr(href)}">${icon}<span><strong>${escapeHtml(title)}</strong>${end}`;
+  const end = selfClosing ? "</div></a>" : "";
+  return `<a class="oc-card" href="${escapeAttr(href)}">${icon}<div><strong>${escapeHtml(title)}</strong>${end}`;
+}
+
+function dedentComponentChildren(markdown) {
+  let depth = 0;
+  return markdown
+    .split("\n")
+    .map((line) => {
+      const markerMatch = line.match(new RegExp(`^${markerPrefix}:([^:]+):`));
+      if (markerMatch) {
+        if (markerMatch[1].endsWith("Close") || markerMatch[1] === "blockClose" || markerMatch[1] === "calloutClose") {
+          depth = Math.max(0, depth - 1);
+        }
+        const markerLine = line;
+        if (markerMatch[1].endsWith("Open") || markerMatch[1] === "blockOpen" || markerMatch[1] === "calloutOpen") {
+          depth += 1;
+        }
+        return markerLine;
+      }
+      if (depth <= 0 || !line.startsWith(" ")) return line;
+      return line.replace(new RegExp(`^ {1,${depth * 2}}`), "");
+    })
+    .join("\n");
 }
 
 function parseAttrs(raw) {