@redocly/theme 0.69.0-next.9 → 0.70.0-next.0

package/src/core/hooks/use-active-heading.ts

@@ -286,18 +286,22 @@ export function useActiveHeading(
       return;
     }
     const headers = findHeaders(contentElement);
+    // oxlint-disable-next-line react-you-might-not-need-an-effect/no-chain-state-updates -- headings and the initial active heading come from DOM queries and scroll measurement, available only after layout
     setHeadingElements(headers);
 
     if (headers.length > 0 && !heading) {
       if (isTopOfPage()) {
+        // oxlint-disable-next-line react-you-might-not-need-an-effect/no-chain-state-updates -- see above
         setHeading(headers[0].id);
       } else {
         const totalHeight = scrollY + window.innerHeight;
         if (totalHeight >= document.body.scrollHeight - 10) {
+          // oxlint-disable-next-line react-you-might-not-need-an-effect/no-chain-state-updates -- see above
           setHeading(headers[headers.length - 1]?.id || undefined);
         } else {
           const triggerOffset = getTriggerOffset();
           const activeHeader = findActiveHeaderByVirtualPosition(headers, scrollY, triggerOffset);
+          // oxlint-disable-next-line react-you-might-not-need-an-effect/no-chain-state-updates -- see above
           setHeading(activeHeader.id);
         }
       }

package/src/core/hooks/use-active-section-id.ts

@@ -43,6 +43,7 @@ export function useActiveSectionId(
           const section = sections[i];
           const rect = section.getBoundingClientRect();
           if (rect.y < heightOffset && rect.bottom > heightOffset) {
+            if (isSkippedContent(section)) continue;
             setItemId(section.getAttribute('data-section-id') || '');
             return;
           }
@@ -73,3 +74,10 @@ export function useActiveSectionId(
 
   return itemId;
 }
+
+function isSkippedContent(element: Element): boolean {
+  return (
+    typeof element.checkVisibility === 'function' &&
+    !element.checkVisibility({ contentVisibilityAuto: true })
+  );
+}

package/src/core/hooks/use-connect-mcp-button.ts

@@ -8,6 +8,7 @@ import { useMCPConfig } from './use-mcp-config';
 import { ClipboardService } from '../utils/clipboard-service';
 import { DEFAULT_MCP_OPTIONS } from '../constants/mcp';
 import { generateClaudeCodeCommand, generateCodexCommand } from '../utils/mcp';
+import { getBaseDataAttributes } from '../utils/telemetry/get-base-data-attributes';
 
 export type McpButtonOptions = {
   options?: MCPOption[];
@@ -27,8 +28,9 @@ const COPIED_RESET_TIMEOUT = 1000;
 export function useConnectMCPButton({
   options = DEFAULT_MCP_OPTIONS,
 }: McpButtonOptions = {}): McpButtonSettings {
-  const { useTranslate } = useThemeHooks();
+  const { useTranslate, useTelemetry } = useThemeHooks();
   const { translate } = useTranslate();
+  const telemetry = useTelemetry();
   const { serverName, serverUrl, cursorUrl, vscodeUrl } = useMCPConfig();
   const [copiedOption, setCopiedOption] = useState<MCPOption | null>(null);
 
@@ -40,6 +42,10 @@ export function useConnectMCPButton({
 
   const handleAction = useCallback(
     (action: MCPOption) => {
+      telemetry.sendConnectMcpClickedMessage([
+        { ...getBaseDataAttributes('connectMcp', 'button'), option: action },
+      ]);
+
       const connection = { serverName, url: serverUrl };
       const copyTextMap: Partial<Record<MCPOption, string>> = {
         copy: JSON.stringify(
@@ -66,7 +72,7 @@ export function useConnectMCPButton({
 
       window.open(urlMap[action], '_blank');
     },
-    [cursorUrl, vscodeUrl, serverUrl, serverName, resetCopied],
+    [cursorUrl, vscodeUrl, serverUrl, serverName, resetCopied, telemetry],
   );
 
   const triggerButtonText = useMemo(

package/src/core/hooks/use-element-size.ts

@@ -1,4 +1,5 @@
-import { useState, useCallback, RefObject, useLayoutEffect, useRef } from 'react';
+import type { RefObject } from 'react';
+import { useState, useCallback, useLayoutEffect, useRef } from 'react';
 
 type Size = {
   width: number;

package/src/core/hooks/use-product-picker.ts

@@ -4,7 +4,7 @@ import { useNavigate } from 'react-router';
 import { getProductClassName } from '@redocly/theme/components/Product/utils';
 
 import { useThemeHooks } from './use-theme-hooks';
-import { withPathPrefix, generateBeforeAfterContext } from '../utils';
+import { withPathPrefix, generateBeforeAfterContext, getSafeClassName } from '../utils';
 
 export function useProductPicker() {
   const { useCurrentProduct, useProducts, useTelemetry, useLoadAndNavigate } = useThemeHooks();
@@ -36,7 +36,7 @@ export function useProductPicker() {
       Array.from(root.classList)
         .filter((c) => c.startsWith('product-'))
         .forEach((c) => root.classList.remove(c));
-      root.classList.add(getProductClassName(freshProduct.name));
+      root.classList.add(getSafeClassName(getProductClassName(freshProduct.name)));
     }
 
     loadAndNavigate({ navigate, to: withPathPrefix(freshProduct.link) });

package/src/core/hooks/use-tabs.ts

@@ -289,14 +289,16 @@ export const useActiveTab = ({ initialTab, tabsId }: UseActiveTabProps) => {
   const [activeTab, setActiveTab] = useState<string | undefined>(undefined);
   const resolvedActiveTab = activeTab ?? initialTab;
   const prevActiveTabRef = useRef(resolvedActiveTab);
+  const isTabResolvedFromHashRef = useRef(false);
 
   useEffect(() => {
-    if (activeTab !== undefined) {
+    if (isTabResolvedFromHashRef.current) {
       return;
     }
+    isTabResolvedFromHashRef.current = true;
 
     setActiveTab(getInitialTab({ initialTab, hash: location.hash, tabsId }));
-  }, [activeTab, initialTab, location.hash, tabsId]);
+  }, [initialTab, location.hash, tabsId]);
 
   useEffect(() => {
     const hasActiveTabChanged = prevActiveTabRef.current !== resolvedActiveTab;

package/src/core/hooks/use-telemetry-fallback.ts

@@ -36,6 +36,8 @@ export const useTelemetryFallback = () => ({
   sendProductPickerChangedMessage: () => {},
   sendLogoClickedMessage: () => {},
   sendCodeSnippetReportedMessage: () => {},
+  sendConnectMcpClickedMessage: () => {},
+  sendMcpConnectionSnippetCopiedMessage: () => {},
   sendMobileMenuClosedMessage: () => {},
   sendMobileMenuOpenedMessage: () => {},
   sendPageViewedMessage: () => {},

package/src/core/styles/global.ts

@@ -599,6 +599,7 @@ const links = css`
 `;
 
 
+// oxlint-disable-next-line theme/css-variable-pattern -- `--schema-labels--text-color` is a documented public variable
 const apiReferenceDocs = css`
   /* === ref docs and graphql docs specific === */
 

package/src/core/types/catalog.ts

@@ -1,7 +1,11 @@
-import { InfiniteData, UseInfiniteQueryResult } from '@tanstack/react-query';
-import { ENTITY_RELATION_TYPES } from '@redocly/config';
+import type { InfiniteData, UseInfiniteQueryResult } from '@tanstack/react-query';
+import type {
+  ENTITY_RELATION_TYPES,
+  CatalogEntityConfig,
+  EntitiesCatalogConfig,
+  LayoutVariant,
+} from '@redocly/config';
 
-import type { CatalogEntityConfig, EntitiesCatalogConfig, LayoutVariant } from '@redocly/config';
 import type { CatalogFilterConfig } from '@redocly/theme/config';
 
 export type FilterResult = {

package/src/core/types/common.ts

@@ -1,5 +1,5 @@
 import type React from 'react';
-import { DEFAULT_COLOR_MODES } from '../constants';
+import type { DEFAULT_COLOR_MODES } from '../constants';
 
 export type Plural<T extends string> = `${T}s`;
 

package/src/core/types/hooks.ts

@@ -1,6 +1,11 @@
-import type { ResolvedBannerConfig } from '@redocly/config';
+import type {
+  ResolvedBannerConfig,
+  PageData,
+  PageProps,
+  ResolvedNavItemWithLink,
+  Version,
+} from '@redocly/config';
 import type { AsyncApiRealmUI } from '@redocly/realm-asyncapi-sdk';
-import type { PageData, PageProps, ResolvedNavItemWithLink, Version } from '@redocly/config';
 import type { ShikiTransformer } from '@shikijs/types';
 import type { Callback, TFunction as TFunc } from 'i18next';
 import type { To, Location, NavigateFunction } from 'react-router';
@@ -14,9 +19,15 @@ import type {
   UseCatalogProps,
   CatalogApiParams,
   CatalogApiResults,
+  BffCatalogEntity,
+  BffCatalogEntityList,
+  BffCatalogRelatedEntity,
+  BffCatalogRelatedEntityList,
+  BffCatalogEntityRevision,
+  BffCatalogEntityRevisionList,
 } from './catalog';
 import type { UserMenuData } from './user-menu';
-import type { ItemState } from './sidebar';
+import type { ItemState, DrilldownMenuItemDetails } from './sidebar';
 import type {
   SearchItemData,
   SearchFacet,
@@ -29,17 +40,8 @@ import type {
 import type { SubmitFeedbackParams } from './feedback';
 import type { TFunction } from './l10n';
 import type { BreadcrumbItem } from './breadcrumb';
-import type { DrilldownMenuItemDetails } from './sidebar';
 
-import {
-  BffCatalogEntity,
-  BffCatalogEntityList,
-  BffCatalogRelatedEntity,
-  BffCatalogRelatedEntityList,
-  BffCatalogEntityRevision,
-  BffCatalogEntityRevisionList,
-} from './catalog';
-import { AiSearchError } from '../constants/search';
+import type { AiSearchError } from '../constants/search';
 
 export type ThemeHooks = {
   useAnchorPositioning: () => { isSupported: boolean };

package/src/core/utils/class-names.ts

@@ -1,5 +1,13 @@
 const SPACE_DELIMITER = ' ';
 
+// EasyList/AdGuard ship generic cosmetic rules that hide these exact class tokens on every
+// site; the trailing underscore keeps the class usable without matching the filter lists.
+const ADBLOCK_HIDDEN_CLASS_NAMES = new Set(['product-ad', 'product-ads', 'product-inlist-ad']);
+
+export function getSafeClassName(className: string): string {
+  return ADBLOCK_HIDDEN_CLASS_NAMES.has(className) ? `${className}_` : className;
+}
+
 export function concatClassNames(...args: Array<string | undefined>): string {
   return args
     .map((className) => (className ? className.trim() : className))

package/src/core/utils/mcp.ts

@@ -42,23 +42,6 @@ export function slugifyMcpServerName(name: string): string {
     .replace(/^-+|-+$/g, '');
 }
 
-// Claude Desktop's config file only launches stdio commands, so remote servers
-// connect through the mcp-remote bridge.
-export function generateClaudeDesktopConfig(config: McpConnectionParams): string {
-  return JSON.stringify(
-    {
-      mcpServers: {
-        [slugifyMcpServerName(config.serverName)]: {
-          command: 'npx',
-          args: ['-y', 'mcp-remote', config.url],
-        },
-      },
-    },
-    null,
-    2,
-  );
-}
-
 export function generateClaudeCodeCommand(config: McpConnectionParams): string {
   return `claude mcp add --transport http ${slugifyMcpServerName(config.serverName)} ${config.url}`;
 }

package/src/core/utils/menu.ts

@@ -1,8 +1,8 @@
 import type { ResolvedNavItem, Version } from '@redocly/config';
 import type { Location } from 'react-router';
 
-import { type Locale, type TFunction } from '../types/l10n';
-import { type ItemState } from '../types/sidebar';
+import type { Locale, TFunction } from '../types/l10n';
+import type { ItemState } from '../types/sidebar';
 import { MenuItemType } from '../constants/common';
 import { getPathnameForLocale, withoutPathPrefix, withPathPrefix } from './urls';
 

package/src/core/utils/urls.ts

@@ -5,9 +5,7 @@ import { DEFAULT_LOCALE_PLACEHOLDER } from '../constants/common';
 export function combineUrls(baseURL: string, ...relativeURLs: (string | undefined)[]) {
   let res = baseURL;
   for (let relativeURL of relativeURLs) {
-    res = relativeURL
-      ? res.replace(/[\/\\]+$/, '') + '/' + relativeURL.replace(/^[\/\\]+/, '')
-      : res;
+    res = relativeURL ? res.replace(/[/\\]+$/, '') + '/' + relativeURL.replace(/^[/\\]+/, '') : res;
   }
 
   return res;

package/src/ext/use-configure-replay.ts

@@ -1,8 +1,8 @@
 import { useEffect, useState, useCallback, useRef } from 'react';
 
-import {
-  type ConfigureRequestValues,
-  type ConfigureServerRequestValues,
+import type {
+  ConfigureRequestValues,
+  ConfigureServerRequestValues,
 } from '@redocly/theme/ext/configure';
 import type { UserClaims, OpenAPIServer, OpenAPIInfo } from '@redocly/theme/core/types';
 

package/src/layouts/OIDCForbidden.tsx

@@ -14,7 +14,7 @@ export function OIDCForbidden(): JSX.Element {
 
   // use whatever you want here
   const URL_REGEX =
-    /https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_\+.~#?&//=]*)/;
+    /https?:\/\/(www\.)?[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_+.~#?&//=]*)/;
 
   const renderText = (text: string) =>
     text.split(' ').map((part: string) =>

package/src/markdoc/components/Accordion/Accordion.tsx

@@ -1,10 +1,11 @@
-import React from 'react';
+import React, { useContext } from 'react';
 import styled, { keyframes } from 'styled-components';
 
 import type { JSX, PropsWithChildren } from 'react';
 
 import { ChevronRightIcon } from '@redocly/theme/icons/ChevronRightIcon/ChevronRightIcon';
 import { ACCORDION_COMPONENT_NAME } from '@redocly/theme/core/constants';
+import { AccordionGroupContext } from '@redocly/theme/core/contexts';
 
 export type AccordionProps = {
   title: string;
@@ -22,10 +23,13 @@ export function Accordion({
   'data-source': dataSource,
   'data-hash': dataHash,
 }: PropsWithChildren<AccordionProps>): JSX.Element {
+  const groupName = useContext(AccordionGroupContext);
+
   return (
     <AccordionWrapper
       className={className}
       open={expanded}
+      name={groupName ?? undefined}
       data-component-name={ACCORDION_COMPONENT_NAME}
       data-source={dataSource}
       data-hash={dataHash}
@@ -37,7 +41,9 @@ export function Accordion({
         />
         {title}
       </AccordionSummary>
-      <AccordionBody>{children}</AccordionBody>
+      <AccordionBody>
+        <AccordionGroupContext.Provider value={null}>{children}</AccordionGroupContext.Provider>
+      </AccordionBody>
     </AccordionWrapper>
   );
 }

package/src/markdoc/components/Accordion/AccordionGroup.tsx

@@ -1,24 +1,31 @@
-import React from 'react';
+import React, { useId } from 'react';
 import styled from 'styled-components';
 
 import type { JSX, PropsWithChildren } from 'react';
 
 import { ACCORDION_GROUP_COMPONENT_NAME, ACCORDION_SELECTOR } from '@redocly/theme/core/constants';
+import { AccordionGroupContext } from '@redocly/theme/core/contexts';
 
 export type AccordionGroupProps = {
+  singleExpanded?: boolean;
   className?: string;
 };
 
 export function AccordionGroup({
+  singleExpanded = false,
   className,
   children,
 }: PropsWithChildren<AccordionGroupProps>): JSX.Element {
+  const groupName = useId();
+
   return (
     <AccordionGroupWrapper
       className={className}
       data-component-name={ACCORDION_GROUP_COMPONENT_NAME}
     >
-      {children}
+      <AccordionGroupContext.Provider value={singleExpanded ? groupName : null}>
+        {children}
+      </AccordionGroupContext.Provider>
     </AccordionGroupWrapper>
   );
 }

package/src/markdoc/components/CodeWalkthrough/CodePanelPreview.tsx

@@ -1,7 +1,7 @@
-import React, { PropsWithChildren, useState } from 'react';
+import React, { useState } from 'react';
 import styled from 'styled-components';
 
-import type { JSX } from 'react';
+import type { JSX, PropsWithChildren } from 'react';
 
 import { useThemeHooks } from '@redocly/theme/core/hooks';
 import { ChevronUpIcon } from '@redocly/theme/icons/ChevronUpIcon/ChevronUpIcon';

package/src/markdoc/components/CodeWalkthrough/CodeWalkthrough.tsx

@@ -9,10 +9,8 @@ import {
 } from '@redocly/theme/core/contexts';
 import { CodePanel } from '@redocly/theme/markdoc/components/CodeWalkthrough/CodePanel';
 import { useCodeWalkthrough } from '@redocly/theme/core/hooks';
-import {
-  CodeFilters,
-  GetFilterState,
-} from '@redocly/theme/markdoc/components/CodeWalkthrough/CodeFilters';
+import type { GetFilterState } from '@redocly/theme/markdoc/components/CodeWalkthrough/CodeFilters';
+import { CodeFilters } from '@redocly/theme/markdoc/components/CodeWalkthrough/CodeFilters';
 
 export type CodeWalkthroughProps = PropsWithChildren<CodeWalkthroughAttr>;
 

package/src/markdoc/components/Diagram/Diagram.tsx

@@ -1,11 +1,8 @@
-import React, { useState } from 'react';
+import React, { useState, type JSX } from 'react';
 import styled from 'styled-components';
 
-import type { JSX } from 'react';
-
 import { concatClassNames } from '@redocly/theme/core/utils';
-import { useColorSwitcher } from '@redocly/theme/core/hooks';
-import { useThemeHooks } from '@redocly/theme/core/hooks';
+import { useColorSwitcher, useThemeHooks } from '@redocly/theme/core/hooks';
 import { SvgViewer } from '@redocly/theme/components/SvgViewer/SvgViewer';
 
 type DiagramProps = {

package/src/markdoc/components/Heading/Heading.tsx

@@ -1,4 +1,4 @@
-import React, { createElement, isValidElement } from 'react';
+import React, { createElement, isValidElement, useContext } from 'react';
 import styled from 'styled-components';
 import { useLocation } from 'react-router';
 
@@ -9,6 +9,7 @@ import { concatClassNames } from '@redocly/theme/core/utils';
 import { LinkIcon } from '@redocly/theme/icons/LinkIcon/LinkIcon';
 import { PageActions } from '@redocly/theme/components/PageActions/PageActions';
 import { useThemeHooks } from '@redocly/theme/core/hooks';
+import { PageActionsContext } from '@redocly/theme/core/contexts';
 import {
   ANCHOR_CLASS,
   HEADING_ANCHOR_CLASS,
@@ -65,8 +66,10 @@ export function Heading({
   const { usePageProps } = useThemeHooks();
   const pageProps = usePageProps();
 
-  const isMarkdownPage =
-    pageProps?.metadata?.type === 'markdown' || pageProps?.metadata?.type === 'asciidoc';
+  // The page-type fallback is only for backward compatibility; templates set the scope.
+  const withPageActions =
+    useContext(PageActionsContext) ??
+    (pageProps?.metadata?.type === 'markdown' || pageProps?.metadata?.type === 'asciidoc');
   const headingTextId = `${id}-heading-text`;
 
   const linkEl = (
@@ -101,7 +104,7 @@ export function Heading({
       <HeadingContentWrapper>
         {linkEl}
         {headingText}
-        {isMarkdownPage && __idx === 0 ? <PageActions pageSlug={pathname} /> : null}
+        {withPageActions && __idx === 0 ? <PageActions pageSlug={pathname} /> : null}
       </HeadingContentWrapper>
     </div>
   );

package/src/markdoc/components/Tabs/Tab.tsx

@@ -3,7 +3,7 @@ import styled from 'styled-components';
 
 import type { JSX } from 'react';
 
-import { TabsSize } from '@redocly/theme/markdoc/components/Tabs/Tabs';
+import type { TabsSize } from '@redocly/theme/markdoc/components/Tabs/Tabs';
 import { TabButtonLink, TabItem } from '@redocly/theme/markdoc/components/Tabs/TabList';
 import { GenericIcon } from '@redocly/theme/icons/GenericIcon/GenericIcon';
 

package/src/markdoc/components/Tabs/TabList.tsx

@@ -5,7 +5,7 @@ import type { JSX } from 'react';
 import type { TabItemProps } from '@redocly/theme/markdoc/components/Tabs/TabItemFragment';
 
 import { Tab } from '@redocly/theme/markdoc/components/Tabs/Tab';
-import { TabsSize } from '@redocly/theme/markdoc/components/Tabs/Tabs';
+import type { TabsSize } from '@redocly/theme/markdoc/components/Tabs/Tabs';
 import { Dropdown } from '@redocly/theme/components/Dropdown/Dropdown';
 import { DropdownMenu } from '@redocly/theme/components/Dropdown/DropdownMenu';
 import { DropdownMenuItem } from '@redocly/theme/components/Dropdown/DropdownMenuItem';

package/src/markdoc/tags/accordion-group.ts

@@ -3,6 +3,9 @@ import type { MarkdocSchemaWrapper } from '@redocly/theme/markdoc/tags/types';
 export const accordionGroup: MarkdocSchemaWrapper = {
   schema: {
     render: 'AccordionGroup',
+    attributes: {
+      singleExpanded: { type: Boolean, default: false },
+    },
   },
   tagName: 'accordion-group',
 };

package/src/markdoc/tags/code-walkthrough.ts

@@ -1,4 +1,5 @@
-import markdoc, { Node, RenderableTreeNode, ValidationError } from '@markdoc/markdoc';
+import type { Node, RenderableTreeNode, ValidationError } from '@markdoc/markdoc';
+import markdoc from '@markdoc/markdoc';
 
 import type { MarkdocSchemaWrapper } from '@redocly/theme/markdoc/tags/types';
 import type {

package/src/markdoc/tags/markdoc-example.ts

@@ -3,27 +3,7 @@ import markdoc from '@markdoc/markdoc';
 import type { Config, Node, RenderableTreeNode } from '@markdoc/markdoc';
 import type { MarkdocSchemaWrapper } from '@redocly/theme/markdoc/tags/types';
 
-// Walk through AST and look for raw markdown to parse
-function parseInlineMarkdown(
-  ast: RenderableTreeNode | RenderableTreeNode[],
-  config: Config,
-): RenderableTreeNode | RenderableTreeNode[] {
-  if (Array.isArray(ast)) {
-    return ast.flatMap((child) => parseInlineMarkdown(child, config));
-  }
-
-  if (typeof ast === 'string') {
-    const parsed = markdoc.parse(ast);
-    return markdoc.transform(parsed, config);
-  }
-
-  if (ast && typeof ast === 'object' && ast.$$mdtype === 'Tag') {
-    const children = parseInlineMarkdown(ast.children, config);
-    return { ...ast, children } as RenderableTreeNode;
-  }
-
-  return ast;
-}
+import { EXAMPLE_CONTENT_ATTRIBUTE, MARKDOC_EXAMPLE_TAG } from '@redocly/theme/core/constants';
 
 // This custom tag prevents evaluating any children markdoc tags (no children) so we can
 // have markdoc examples in code fences
@@ -39,33 +19,70 @@ export const markdocExample: MarkdocSchemaWrapper = {
     children: ['fence'],
     transform(node: Node, config: Config) {
       const attributes = node.transformAttributes(config);
-      const { content } = node.children[0]?.attributes || {};
+      const fenceNode = node.children[0];
+      const { content } = fenceNode?.attributes || {};
       if (!content) return null;
 
       const language = 'markdoc';
 
-      const annotations = node.children[0].annotations;
+      const annotations = fenceNode.annotations;
       let title = null;
       if (annotations.length > 0) {
         const fenceWithTitle = annotations.find((annotation) => annotation.name === 'title');
         title = fenceWithTitle?.value;
       }
 
-      const demoContent = node.children[0].transformChildren(config);
-      const parsedDemoContent = parseInlineMarkdown(demoContent, config);
-
       return new markdoc.Tag(
         'MarkdocExample',
         {
           ...attributes,
           title,
           language,
-          demoContent: parsedDemoContent,
+          demoContent: transformDemoContent(fenceNode, content, config),
           rawContent: content,
         },
         [],
       );
     },
   },
-  tagName: 'markdoc-example',
+  tagName: MARKDOC_EXAMPLE_TAG,
 };
+
+// Walk through AST and look for raw markdown to parse
+function parseRawMarkdown(
+  ast: RenderableTreeNode | RenderableTreeNode[],
+  config: Config,
+): RenderableTreeNode | RenderableTreeNode[] {
+  if (Array.isArray(ast)) {
+    return ast.flatMap((child) => parseRawMarkdown(child, config));
+  }
+
+  if (typeof ast === 'string') {
+    const parsed = markdoc.parse(ast);
+    return markdoc.transform(parsed, config);
+  }
+
+  if (ast && typeof ast === 'object' && ast.$$mdtype === 'Tag') {
+    const children = parseRawMarkdown(ast.children, config);
+    return { ...ast, children } as RenderableTreeNode;
+  }
+
+  return ast;
+}
+
+function toRenderableArray(node: RenderableTreeNode | RenderableTreeNode[]): RenderableTreeNode[] {
+  return Array.isArray(node) ? node : [node];
+}
+
+function transformDemoContent(fenceNode: Node, content: string, config: Config) {
+  const parsedBody = fenceNode.attributes[EXAMPLE_CONTENT_ATTRIBUTE] as Node | undefined;
+  if (parsedBody) {
+    return toRenderableArray(markdoc.transform(parsedBody.children, config));
+  }
+
+  if (!fenceNode.children.length) {
+    return toRenderableArray(markdoc.transform(markdoc.parse(content).children, config));
+  }
+
+  return toRenderableArray(parseRawMarkdown(fenceNode.transformChildren(config), config));
+}