@redocly/theme 0.69.0-next.9 → 0.69.0

package/lib/components/Catalog/CatalogEntities.js

@@ -70,6 +70,7 @@ function CatalogEntities(props) {
     const shouldShowLoadMore = query.hasNextPage ||
         (query.isPlaceholderData && entities && entities.length >= LOAD_MORE_THRESHOLD);
     (0, react_1.useEffect)(() => {
+        // oxlint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent -- the entities query lives in this ejectable component; the fetched total is mirrored up so the portal page header can show the count
         setEntitiesCounter(total || 0);
     }, [total, setEntitiesCounter]);
     if (!query.isPending && (!entities || entities.length === 0)) {

package/lib/components/MCP/McpConnectionTabs.js

@@ -62,11 +62,10 @@ const TAB_LABELS = {
     },
     json: { translationKey: 'page.mcpNotAllowed.tabs.json', defaultLabel: 'JSON' },
 };
-// The report control is docs feedback, not useful on the connection page.
-const CODE_BLOCK_HEADER = { controls: { copy: {}, report: { hidden: true } } };
 function McpConnectionTabs({ options = DEFAULT_TAB_OPTIONS, className, }) {
-    const { useTranslate } = (0, hooks_1.useThemeHooks)();
+    const { useTranslate, useTelemetry } = (0, hooks_1.useThemeHooks)();
     const { translate } = useTranslate();
+    const telemetry = useTelemetry();
     const { serverName, serverUrl, isMcpDisabled } = (0, hooks_1.useMCPConfig)();
     // The SSR markup of error pages is cached with the build-time origin, so the
     // tabs remount after hydration to pick up the real browser origin.
@@ -76,20 +75,31 @@ function McpConnectionTabs({ options = DEFAULT_TAB_OPTIONS, className, }) {
         return null;
     }
     const connection = { serverName, url: serverUrl };
+    const snippetHeader = (client, snippet) => ({
+        controls: {
+            copy: {
+                onClick: () => telemetry.sendMcpConnectionSnippetCopiedMessage([
+                    Object.assign(Object.assign({}, (0, utils_1.getBaseDataAttributes)('mcpConnectionSnippet', 'button')), { client, snippet }),
+                ]),
+            },
+            // The report control is docs feedback, not useful on the connection page.
+            report: { hidden: true },
+        },
+    });
     return (react_1.default.createElement(McpConnectionTabsWrapper, { key: hydrated ? 'client' : 'ssr', "data-component-name": "MCP/McpConnectionTabs", "data-testid": "mcp-connection-tabs", className: className },
         react_1.default.createElement(Tabs_1.Tabs, { size: Tabs_1.TabsSize.SMALL }, options.map((option) => {
             const { translationKey, defaultLabel, icon: TabIcon } = TAB_LABELS[option];
-            return (react_1.default.createElement(TabItemFragment_1.TabItemFragment, { key: option, label: translate(translationKey, defaultLabel), icon: TabIcon ? react_1.default.createElement(TabIcon, null) : undefined }, renderTabContent(option, connection, translate)));
+            return (react_1.default.createElement(TabItemFragment_1.TabItemFragment, { key: option, label: translate(translationKey, defaultLabel), icon: TabIcon ? react_1.default.createElement(TabIcon, null) : undefined }, renderTabContent(option, connection, translate, snippetHeader)));
         }))));
 }
-function renderTabContent(option, connection, translate) {
+function renderTabContent(option, connection, translate, snippetHeader) {
     const terminalHint = (react_1.default.createElement(TabHint, null, translate('page.mcpNotAllowed.snippets.terminal.hint', 'Run this command in your terminal:')));
-    const urlBlock = react_1.default.createElement(CodeBlock_1.CodeBlock, { lang: "text", source: connection.url, header: CODE_BLOCK_HEADER });
+    const urlBlock = (react_1.default.createElement(CodeBlock_1.CodeBlock, { lang: "text", source: connection.url, header: snippetHeader(option, 'chatgpt-app') }));
     const assistantPromptClient = {
         headline: translate('page.mcpNotAllowed.snippets.prompt.headline', 'Prompt'),
         content: (react_1.default.createElement(react_1.default.Fragment, null,
             react_1.default.createElement(TabHint, null, translate('page.mcpNotAllowed.snippets.prompt.hint', 'Or paste this prompt into the chat to have it add the server for you:')),
-            react_1.default.createElement(CodeBlock_1.CodeBlock, { lang: "text", source: (0, utils_1.generateMcpInstallPrompt)(connection), header: CODE_BLOCK_HEADER, wrapContents: true }))),
+            react_1.default.createElement(CodeBlock_1.CodeBlock, { lang: "text", source: (0, utils_1.generateMcpInstallPrompt)(connection), header: snippetHeader(option, 'prompt'), wrapContents: true }))),
     };
     switch (option) {
         case 'claude':
@@ -98,13 +108,13 @@ function renderTabContent(option, connection, translate) {
                     headline: translate('page.mcpNotAllowed.snippets.claudeCode.headline', 'Claude Code'),
                     content: (react_1.default.createElement(react_1.default.Fragment, null,
                         terminalHint,
-                        react_1.default.createElement(CodeBlock_1.CodeBlock, { lang: "shell", source: (0, utils_1.generateClaudeCodeCommand)(connection), header: CODE_BLOCK_HEADER, wrapContents: true }))),
+                        react_1.default.createElement(CodeBlock_1.CodeBlock, { lang: "shell", source: (0, utils_1.generateClaudeCodeCommand)(connection), header: snippetHeader(option, 'claude-code'), wrapContents: true }))),
                 },
                 {
                     headline: translate('page.mcpNotAllowed.snippets.claudeDesktop.headline', 'Claude Desktop'),
                     content: (react_1.default.createElement(react_1.default.Fragment, null,
                         react_1.default.createElement(TabHint, null, translate('page.mcpNotAllowed.snippets.claudeDesktop.instruction', 'In Claude Desktop, open Settings → Developer → Edit Config, add this to the configuration file, and restart Claude Desktop:')),
-                        react_1.default.createElement(CodeBlock_1.CodeBlock, { lang: "json", source: (0, utils_1.generateClaudeDesktopConfig)(connection), header: CODE_BLOCK_HEADER }))),
+                        react_1.default.createElement(CodeBlock_1.CodeBlock, { lang: "json", source: (0, utils_1.generateClaudeDesktopConfig)(connection), header: snippetHeader(option, 'claude-desktop') }))),
                 },
             ]);
         case 'chatgpt':
@@ -113,7 +123,7 @@ function renderTabContent(option, connection, translate) {
                     headline: translate('page.mcpNotAllowed.snippets.codexCli.headline', 'Codex CLI'),
                     content: (react_1.default.createElement(react_1.default.Fragment, null,
                         terminalHint,
-                        react_1.default.createElement(CodeBlock_1.CodeBlock, { lang: "shell", source: (0, utils_1.generateCodexCommand)(connection), header: CODE_BLOCK_HEADER, wrapContents: true }))),
+                        react_1.default.createElement(CodeBlock_1.CodeBlock, { lang: "shell", source: (0, utils_1.generateCodexCommand)(connection), header: snippetHeader(option, 'codex'), wrapContents: true }))),
                 },
                 {
                     headline: translate('page.mcpNotAllowed.snippets.chatgptApp.headline', 'ChatGPT desktop app'),
@@ -126,7 +136,7 @@ function renderTabContent(option, connection, translate) {
         case 'json':
             return (react_1.default.createElement(react_1.default.Fragment, null,
                 react_1.default.createElement(TabHint, null, translate('page.mcpNotAllowed.snippets.json.hint', 'Add this server entry to your MCP client configuration file:')),
-                react_1.default.createElement(CodeBlock_1.CodeBlock, { lang: "json", source: JSON.stringify({ [connection.serverName]: { url: connection.url, description: 'MCP Server' } }, null, 2), header: CODE_BLOCK_HEADER })));
+                react_1.default.createElement(CodeBlock_1.CodeBlock, { lang: "json", source: JSON.stringify({ [connection.serverName]: { url: connection.url, description: 'MCP Server' } }, null, 2), header: snippetHeader(option, 'json') })));
     }
 }
 function renderClientList(clients) {

package/lib/components/Markdown/Markdown.js

@@ -178,10 +178,8 @@ exports.Markdown = styled_components_1.default.main
   }
 
   hr {
-    border-top: 1px solid var(--md-hr-border-color);
-    background-color: var(--md-hr-bg-color);
-    height: var(--md-hr-height);
     margin: var(--md-hr-margin-vertical) 0;
+    border: var(--md-hr-border);
   }
 
   details:not(${constants_1.ACCORDION_SELECTOR}) {

package/lib/components/Markdown/styles/base-table.js

@@ -46,6 +46,14 @@ exports.markdownBaseTableCss = (0, styled_components_1.css) `
       background-color: var(--md-table-header-bg-color);
     }
 
+    /* hide the header row when every cell is empty; one labelled cell keeps it visible */
+    thead:has(th:empty) {
+      display: none;
+    }
+    thead:has(th:not(:empty)) {
+      display: table-header-group;
+    }
+
     tr {
       background-color: var(--md-table-stripe-bg-color);
     }

package/lib/components/Markdown/variables.js

@@ -62,9 +62,8 @@ exports.markdown = (0, styled_components_1.css) `
   * @tokens Markdown Horizontal Rule
   */
 
-  --md-hr-bg-color: transparent; // @presenter Color
   --md-hr-border-color: var(--border-color-secondary); // @presenter Color
-  --md-hr-height: unset;
+  --md-hr-border: 0.5px solid var(--md-hr-border-color); // @presenter Border
   --md-hr-margin-vertical: 20px; // @presenter Spacing
 
   /**

package/lib/components/Search/SearchAiDialog.js

@@ -80,6 +80,7 @@ function SearchAiDialog({ isGeneratingResponse, response, initialMessage, error,
         if (!(initialMessage === null || initialMessage === void 0 ? void 0 : initialMessage.trim().length)) {
             return;
         }
+        // oxlint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent -- appends the initial message into the conversation state lifted to the search root once the dialog mounts
         setConversation((prev) => [
             ...prev,
             { role: constants_1.AiSearchConversationRole.USER, content: initialMessage },
@@ -89,6 +90,7 @@ function SearchAiDialog({ isGeneratingResponse, response, initialMessage, error,
         if (response === undefined || conversation.length === 0 || error) {
             return;
         }
+        // oxlint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent -- merges the streamed assistant response into the lifted conversation state as chunks arrive
         setConversation((prev) => {
             const lastMessage = prev[prev.length - 1];
             const content = response || '';
@@ -127,6 +129,7 @@ function SearchAiDialog({ isGeneratingResponse, response, initialMessage, error,
     ]);
     (0, react_1.useEffect)(() => {
         if (error) {
+            // oxlint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent -- drops the pending message from the lifted conversation state once the request errors
             setConversation((prev) => prev.slice(0, -1));
         }
     }, [error, setConversation]);

package/lib/core/contexts/AccordionGroupContext.d.ts

@@ -0,0 +1 @@
+export declare const AccordionGroupContext: import("react").Context<string | null>;

package/lib/core/contexts/AccordionGroupContext.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccordionGroupContext = void 0;
+const react_1 = require("react");
+exports.AccordionGroupContext = (0, react_1.createContext)(null);
+//# sourceMappingURL=AccordionGroupContext.js.map

package/lib/core/contexts/PageActionsContext.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether the first heading inside the enclosing `Markdown` mounts the page actions.
+ * Without a provider `Heading` falls back to the page type in the page metadata.
+ */
+export declare const PageActionsContext: import("react").Context<boolean | null>;

package/lib/core/contexts/PageActionsContext.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageActionsContext = void 0;
+const react_1 = require("react");
+/**
+ * Whether the first heading inside the enclosing `Markdown` mounts the page actions.
+ * Without a provider `Heading` falls back to the page type in the page metadata.
+ */
+exports.PageActionsContext = (0, react_1.createContext)(null);
+//# sourceMappingURL=PageActionsContext.js.map

package/lib/core/contexts/index.d.ts

@@ -1,7 +1,9 @@
 export * from './ThemeDataContext';
 export * from './MarkdownLinkContext';
+export * from './PageActionsContext';
 export * from './CodeWalkthrough/CodeWalkthroughControlsContext';
 export * from './CodeWalkthrough/CodeWalkthroughStepsContext';
+export * from './AccordionGroupContext';
 export * from './CodeSnippetContext';
 export * from './SearchContext';
 export * from './Toast/ToastContext';

package/lib/core/contexts/index.js

@@ -16,8 +16,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./ThemeDataContext"), exports);
 __exportStar(require("./MarkdownLinkContext"), exports);
+__exportStar(require("./PageActionsContext"), exports);
 __exportStar(require("./CodeWalkthrough/CodeWalkthroughControlsContext"), exports);
 __exportStar(require("./CodeWalkthrough/CodeWalkthroughStepsContext"), exports);
+__exportStar(require("./AccordionGroupContext"), exports);
 __exportStar(require("./CodeSnippetContext"), exports);
 __exportStar(require("./SearchContext"), exports);
 __exportStar(require("./Toast/ToastContext"), exports);

package/lib/core/hooks/code-walkthrough/use-code-walkthrough-steps.js

@@ -58,6 +58,7 @@ function useCodeWalkthroughSteps({ steps, enableDeepLink, root, }) {
                 startOffset: markersMinTopOffset < endOffset ? startOffset : 0,
             });
         }
+        // oxlint-disable-next-line react-you-might-not-need-an-effect/no-chain-state-updates -- marker geometry is derived from post-layout measurements (offsetTop, clientHeight, window.innerHeight)
         setMarkers(markers.reduce((acc, marker, index) => {
             var _a;
             const step = visibleSteps[index];

package/lib/core/hooks/use-active-heading.js

@@ -205,19 +205,23 @@ function useActiveHeading(contentElement, displayedHeadings) {
             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(((_a = headers[headers.length - 1]) === null || _a === void 0 ? void 0 : _a.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/lib/core/hooks/use-connect-mcp-button.js

@@ -11,15 +11,20 @@ const use_mcp_config_1 = require("./use-mcp-config");
 const clipboard_service_1 = require("../utils/clipboard-service");
 const mcp_1 = require("../constants/mcp");
 const mcp_2 = require("../utils/mcp");
+const get_base_data_attributes_1 = require("../utils/telemetry/get-base-data-attributes");
 const COPIED_RESET_TIMEOUT = 1000;
 function useConnectMCPButton({ options = mcp_1.DEFAULT_MCP_OPTIONS, } = {}) {
-    const { useTranslate } = (0, use_theme_hooks_1.useThemeHooks)();
+    const { useTranslate, useTelemetry } = (0, use_theme_hooks_1.useThemeHooks)();
     const { translate } = useTranslate();
+    const telemetry = useTelemetry();
     const { serverName, serverUrl, cursorUrl, vscodeUrl } = (0, use_mcp_config_1.useMCPConfig)();
     const [copiedOption, setCopiedOption] = (0, react_1.useState)(null);
     // eslint-disable-next-line react-hooks/exhaustive-deps
     const resetCopied = (0, react_1.useCallback)((0, lodash_debounce_1.default)(() => setCopiedOption(null), COPIED_RESET_TIMEOUT), []);
     const handleAction = (0, react_1.useCallback)((action) => {
+        telemetry.sendConnectMcpClickedMessage([
+            Object.assign(Object.assign({}, (0, get_base_data_attributes_1.getBaseDataAttributes)('connectMcp', 'button')), { option: action }),
+        ]);
         const connection = { serverName, url: serverUrl };
         const copyTextMap = {
             copy: JSON.stringify({ [serverName]: { url: serverUrl, description: 'MCP Server' } }, null, 2),
@@ -38,7 +43,7 @@ function useConnectMCPButton({ options = mcp_1.DEFAULT_MCP_OPTIONS, } = {}) {
             vscode: vscodeUrl,
         };
         window.open(urlMap[action], '_blank');
-    }, [cursorUrl, vscodeUrl, serverUrl, serverName, resetCopied]);
+    }, [cursorUrl, vscodeUrl, serverUrl, serverName, resetCopied, telemetry]);
     const triggerButtonText = (0, react_1.useMemo)(() => translate('page.actions.connectMcp', 'Connect MCP'), [translate]);
     const visibleOptions = (0, react_1.useMemo)(() => options.filter(Boolean), [options]);
     return {

package/lib/core/hooks/use-product-picker.js

@@ -33,7 +33,7 @@ function useProductPicker() {
             Array.from(root.classList)
                 .filter((c) => c.startsWith('product-'))
                 .forEach((c) => root.classList.remove(c));
-            root.classList.add((0, utils_1.getProductClassName)(freshProduct.name));
+            root.classList.add((0, utils_2.getSafeClassName)((0, utils_1.getProductClassName)(freshProduct.name)));
         }
         loadAndNavigate({ navigate, to: (0, utils_2.withPathPrefix)(freshProduct.link) });
     }

package/lib/core/hooks/use-tabs.js

@@ -220,12 +220,14 @@ const useActiveTab = ({ initialTab, tabsId }) => {
     const [activeTab, setActiveTab] = (0, react_1.useState)(undefined);
     const resolvedActiveTab = activeTab !== null && activeTab !== void 0 ? activeTab : initialTab;
     const prevActiveTabRef = (0, react_1.useRef)(resolvedActiveTab);
+    const isTabResolvedFromHashRef = (0, react_1.useRef)(false);
     (0, react_1.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]);
     (0, react_1.useEffect)(() => {
         const hasActiveTabChanged = prevActiveTabRef.current !== resolvedActiveTab;
         if (!tabsId || !hasActiveTabChanged) {

package/lib/core/hooks/use-telemetry-fallback.d.ts

@@ -34,6 +34,8 @@ export declare const useTelemetryFallback: () => {
     sendProductPickerChangedMessage: () => void;
     sendLogoClickedMessage: () => void;
     sendCodeSnippetReportedMessage: () => void;
+    sendConnectMcpClickedMessage: () => void;
+    sendMcpConnectionSnippetCopiedMessage: () => void;
     sendMobileMenuClosedMessage: () => void;
     sendMobileMenuOpenedMessage: () => void;
     sendPageViewedMessage: () => void;

package/lib/core/hooks/use-telemetry-fallback.js

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

package/lib/core/styles/global.js

@@ -592,6 +592,7 @@ const links = (0, styled_components_1.css) `
 
   // @tokens End
 `;
+// oxlint-disable-next-line theme/css-variable-pattern -- `--schema-labels--text-color` is a documented public variable
 const apiReferenceDocs = (0, styled_components_1.css) `
   /* === ref docs and graphql docs specific === */
 

package/lib/core/utils/class-names.d.ts

@@ -1 +1,2 @@
+export declare function getSafeClassName(className: string): string;
 export declare function concatClassNames(...args: Array<string | undefined>): string;

package/lib/core/utils/class-names.js

@@ -1,7 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSafeClassName = getSafeClassName;
 exports.concatClassNames = concatClassNames;
 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']);
+function getSafeClassName(className) {
+    return ADBLOCK_HIDDEN_CLASS_NAMES.has(className) ? `${className}_` : className;
+}
 function concatClassNames(...args) {
     return args
         .map((className) => (className ? className.trim() : className))

package/lib/markdoc/components/Accordion/Accordion.js

@@ -32,21 +32,21 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Accordion = Accordion;
-const react_1 = __importDefault(require("react"));
+const react_1 = __importStar(require("react"));
 const styled_components_1 = __importStar(require("styled-components"));
 const ChevronRightIcon_1 = require("../../../icons/ChevronRightIcon/ChevronRightIcon");
 const constants_1 = require("../../../core/constants");
+const contexts_1 = require("../../../core/contexts");
 function Accordion({ title, expanded = false, className, children, 'data-source': dataSource, 'data-hash': dataHash, }) {
-    return (react_1.default.createElement(AccordionWrapper, { className: className, open: expanded, "data-component-name": constants_1.ACCORDION_COMPONENT_NAME, "data-source": dataSource, "data-hash": dataHash },
+    const groupName = (0, react_1.useContext)(contexts_1.AccordionGroupContext);
+    return (react_1.default.createElement(AccordionWrapper, { className: className, open: expanded, name: groupName !== null && groupName !== void 0 ? groupName : undefined, "data-component-name": constants_1.ACCORDION_COMPONENT_NAME, "data-source": dataSource, "data-hash": dataHash },
         react_1.default.createElement(AccordionSummary, null,
             react_1.default.createElement(ChevronRightIcon_1.ChevronRightIcon, { color: "--md-accordion-chevron-icon-color", size: "var(--md-accordion-chevron-icon-size)" }),
             title),
-        react_1.default.createElement(AccordionBody, null, children)));
+        react_1.default.createElement(AccordionBody, null,
+            react_1.default.createElement(contexts_1.AccordionGroupContext.Provider, { value: null }, children))));
 }
 const AccordionWrapper = styled_components_1.default.details `
   margin: var(--md-accordion-margin);

package/lib/markdoc/components/Accordion/AccordionGroup.d.ts

@@ -1,5 +1,6 @@
 import type { JSX, PropsWithChildren } from 'react';
 export type AccordionGroupProps = {
+    singleExpanded?: boolean;
     className?: string;
 };
-export declare function AccordionGroup({ className, children, }: PropsWithChildren<AccordionGroupProps>): JSX.Element;
+export declare function AccordionGroup({ singleExpanded, className, children, }: PropsWithChildren<AccordionGroupProps>): JSX.Element;

package/lib/markdoc/components/Accordion/AccordionGroup.js

@@ -1,14 +1,50 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AccordionGroup = AccordionGroup;
-const react_1 = __importDefault(require("react"));
+const react_1 = __importStar(require("react"));
 const styled_components_1 = __importDefault(require("styled-components"));
 const constants_1 = require("../../../core/constants");
-function AccordionGroup({ className, children, }) {
-    return (react_1.default.createElement(AccordionGroupWrapper, { className: className, "data-component-name": constants_1.ACCORDION_GROUP_COMPONENT_NAME }, children));
+const contexts_1 = require("../../../core/contexts");
+function AccordionGroup({ singleExpanded = false, className, children, }) {
+    const groupName = (0, react_1.useId)();
+    return (react_1.default.createElement(AccordionGroupWrapper, { className: className, "data-component-name": constants_1.ACCORDION_GROUP_COMPONENT_NAME },
+        react_1.default.createElement(contexts_1.AccordionGroupContext.Provider, { value: singleExpanded ? groupName : null }, children)));
 }
 const AccordionGroupWrapper = styled_components_1.default.div `
   margin: var(--md-accordion-group-margin);

package/lib/markdoc/components/Heading/Heading.js

@@ -45,6 +45,7 @@ const utils_1 = require("../../../core/utils");
 const LinkIcon_1 = require("../../../icons/LinkIcon/LinkIcon");
 const PageActions_1 = require("../../../components/PageActions/PageActions");
 const hooks_1 = require("../../../core/hooks");
+const contexts_1 = require("../../../core/contexts");
 const constants_1 = require("../../../core/constants");
 function renderWithSpanWrapper(children) {
     const childrenArray = react_1.default.Children.toArray(children);
@@ -68,10 +69,12 @@ function renderWithSpanWrapper(children) {
 }
 function Heading({ level, id, children, 'data-source': dataSource, 'data-hash': dataHash, className, __idx, }) {
     var _a, _b;
+    var _c;
     const { pathname } = (0, react_router_1.useLocation)();
     const { usePageProps } = (0, hooks_1.useThemeHooks)();
     const pageProps = usePageProps();
-    const isMarkdownPage = ((_a = pageProps === null || pageProps === void 0 ? void 0 : pageProps.metadata) === null || _a === void 0 ? void 0 : _a.type) === 'markdown' || ((_b = pageProps === null || pageProps === void 0 ? void 0 : pageProps.metadata) === null || _b === void 0 ? void 0 : _b.type) === 'asciidoc';
+    // The page-type fallback is only for backward compatibility; templates set the scope.
+    const withPageActions = (_c = (0, react_1.useContext)(contexts_1.PageActionsContext)) !== null && _c !== void 0 ? _c : (((_a = pageProps === null || pageProps === void 0 ? void 0 : pageProps.metadata) === null || _a === void 0 ? void 0 : _a.type) === 'markdown' || ((_b = pageProps === null || pageProps === void 0 ? void 0 : pageProps.metadata) === null || _b === void 0 ? void 0 : _b.type) === 'asciidoc');
     const headingTextId = `${id}-heading-text`;
     const linkEl = (react_1.default.createElement("a", { "aria-labelledby": headingTextId, href: `#${id}`, className: (0, utils_1.concatClassNames)(constants_1.ANCHOR_CLASS, 'before') },
         react_1.default.createElement(LinkIcon_1.LinkIcon, { "aria-hidden": "true", focusable: "false", color: "--heading-anchor-color" })));
@@ -80,7 +83,7 @@ function Heading({ level, id, children, 'data-source': dataSource, 'data-hash':
         react_1.default.createElement(HeadingContentWrapper, null,
             linkEl,
             headingText,
-            isMarkdownPage && __idx === 0 ? react_1.default.createElement(PageActions_1.PageActions, { pageSlug: pathname }) : null)));
+            withPageActions && __idx === 0 ? react_1.default.createElement(PageActions_1.PageActions, { pageSlug: pathname }) : null)));
 }
 const HeadingContentWrapper = styled_components_1.default.div `
   display: flex;

package/lib/markdoc/tags/accordion-group.js

@@ -4,6 +4,9 @@ exports.accordionGroup = void 0;
 exports.accordionGroup = {
     schema: {
         render: 'AccordionGroup',
+        attributes: {
+            singleExpanded: { type: Boolean, default: false },
+        },
     },
     tagName: 'accordion-group',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redocly/theme",
-  "version": "0.69.0-next.9",
+  "version": "0.69.0",
   "description": "Shared UI components lib",
   "keywords": [
     "theme",
@@ -42,7 +42,7 @@
   "devDependencies": {
     "@babel/core": "7.29.7",
     "@markdoc/markdoc": "0.5.2",
-    "@redocly/realm-asyncapi-sdk": "0.15.0-next.3",
+    "@redocly/realm-asyncapi-sdk": "0.15.0",
     "@shikijs/types": "3.21.0",
     "@testing-library/react": "16.3.0",
     "@testing-library/user-event": "14.6.1",

package/src/components/Catalog/CatalogEntities.tsx

@@ -88,6 +88,7 @@ export function CatalogEntities(props: CatalogEntitiesProps): JSX.Element {
     (query.isPlaceholderData && entities && entities.length >= LOAD_MORE_THRESHOLD);
 
   useEffect(() => {
+    // oxlint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent -- the entities query lives in this ejectable component; the fetched total is mirrored up so the portal page header can show the count
     setEntitiesCounter(total || 0);
   }, [total, setEntitiesCounter]);
 

package/src/components/MCP/McpConnectionTabs.tsx

@@ -3,6 +3,8 @@ import styled from 'styled-components';
 
 import type { JSX, ReactNode } from 'react';
 import type { TFunction } from '@redocly/theme/core/types';
+import type { AsyncApiRealmUI } from '@redocly/realm-asyncapi-sdk';
+import type { CodeBlockControlsProps } from '@redocly/theme/components/CodeBlock/CodeBlockControls';
 
 import { useMCPConfig, useThemeHooks } from '@redocly/theme/core/hooks';
 import {
@@ -10,6 +12,7 @@ import {
   generateClaudeDesktopConfig,
   generateCodexCommand,
   generateMcpInstallPrompt,
+  getBaseDataAttributes,
 } from '@redocly/theme/core/utils';
 import { CodeBlock } from '@redocly/theme/components/CodeBlock/CodeBlock';
 import { ClaudeIcon } from '@redocly/theme/icons/ClaudeIcon/ClaudeIcon';
@@ -47,15 +50,18 @@ const TAB_LABELS: Record<
 
 type TabClient = { headline: string; content: ReactNode };
 
-// The report control is docs feedback, not useful on the connection page.
-const CODE_BLOCK_HEADER = { controls: { copy: {}, report: { hidden: true } } };
+type SnippetId =
+  AsyncApiRealmUI.EventPayload<'com.redocly.mcpConnectionSnippet.copied'>[0]['snippet'];
+
+type SnippetHeader = (client: McpConnectionTab, snippet: SnippetId) => CodeBlockControlsProps;
 
 export function McpConnectionTabs({
   options = DEFAULT_TAB_OPTIONS,
   className,
 }: McpConnectionTabsProps): JSX.Element | null {
-  const { useTranslate } = useThemeHooks();
+  const { useTranslate, useTelemetry } = useThemeHooks();
   const { translate } = useTranslate();
+  const telemetry = useTelemetry();
   const { serverName, serverUrl, isMcpDisabled } = useMCPConfig();
   // The SSR markup of error pages is cached with the build-time origin, so the
   // tabs remount after hydration to pick up the real browser origin.
@@ -69,6 +75,19 @@ export function McpConnectionTabs({
 
   const connection = { serverName, url: serverUrl };
 
+  const snippetHeader: SnippetHeader = (client, snippet) => ({
+    controls: {
+      copy: {
+        onClick: () =>
+          telemetry.sendMcpConnectionSnippetCopiedMessage([
+            { ...getBaseDataAttributes('mcpConnectionSnippet', 'button'), client, snippet },
+          ]),
+      },
+      // The report control is docs feedback, not useful on the connection page.
+      report: { hidden: true },
+    },
+  });
+
   return (
     <McpConnectionTabsWrapper
       key={hydrated ? 'client' : 'ssr'}
@@ -86,7 +105,7 @@ export function McpConnectionTabs({
               label={translate(translationKey, defaultLabel)}
               icon={TabIcon ? <TabIcon /> : undefined}
             >
-              {renderTabContent(option, connection, translate)}
+              {renderTabContent(option, connection, translate, snippetHeader)}
             </TabItemFragment>
           );
         })}
@@ -99,6 +118,7 @@ function renderTabContent(
   option: McpConnectionTab,
   connection: { serverName: string; url: string },
   translate: TFunction,
+  snippetHeader: SnippetHeader,
 ): ReactNode {
   const terminalHint = (
     <TabHint>
@@ -106,7 +126,9 @@ function renderTabContent(
     </TabHint>
   );
 
-  const urlBlock = <CodeBlock lang="text" source={connection.url} header={CODE_BLOCK_HEADER} />;
+  const urlBlock = (
+    <CodeBlock lang="text" source={connection.url} header={snippetHeader(option, 'chatgpt-app')} />
+  );
 
   const assistantPromptClient: TabClient = {
     headline: translate('page.mcpNotAllowed.snippets.prompt.headline', 'Prompt'),
@@ -121,7 +143,7 @@ function renderTabContent(
         <CodeBlock
           lang="text"
           source={generateMcpInstallPrompt(connection)}
-          header={CODE_BLOCK_HEADER}
+          header={snippetHeader(option, 'prompt')}
           wrapContents
         />
       </>
@@ -139,7 +161,7 @@ function renderTabContent(
               <CodeBlock
                 lang="shell"
                 source={generateClaudeCodeCommand(connection)}
-                header={CODE_BLOCK_HEADER}
+                header={snippetHeader(option, 'claude-code')}
                 wrapContents
               />
             </>
@@ -161,7 +183,7 @@ function renderTabContent(
               <CodeBlock
                 lang="json"
                 source={generateClaudeDesktopConfig(connection)}
-                header={CODE_BLOCK_HEADER}
+                header={snippetHeader(option, 'claude-desktop')}
               />
             </>
           ),
@@ -177,7 +199,7 @@ function renderTabContent(
               <CodeBlock
                 lang="shell"
                 source={generateCodexCommand(connection)}
-                header={CODE_BLOCK_HEADER}
+                header={snippetHeader(option, 'codex')}
                 wrapContents
               />
             </>
@@ -218,7 +240,7 @@ function renderTabContent(
               null,
               2,
             )}
-            header={CODE_BLOCK_HEADER}
+            header={snippetHeader(option, 'json')}
           />
         </>
       );

package/src/components/Markdown/Markdown.tsx

@@ -167,10 +167,8 @@ export const Markdown = styled.main
   }
 
   hr {
-    border-top: 1px solid var(--md-hr-border-color);
-    background-color: var(--md-hr-bg-color);
-    height: var(--md-hr-height);
     margin: var(--md-hr-margin-vertical) 0;
+    border: var(--md-hr-border);
   }
 
   details:not(${ACCORDION_SELECTOR}) {

package/src/components/Markdown/styles/base-table.ts

@@ -45,6 +45,14 @@ export const markdownBaseTableCss = css`
       background-color: var(--md-table-header-bg-color);
     }
 
+    /* hide the header row when every cell is empty; one labelled cell keeps it visible */
+    thead:has(th:empty) {
+      display: none;
+    }
+    thead:has(th:not(:empty)) {
+      display: table-header-group;
+    }
+
     tr {
       background-color: var(--md-table-stripe-bg-color);
     }

package/src/components/Markdown/variables.ts

@@ -60,9 +60,8 @@ export const markdown = css`
   * @tokens Markdown Horizontal Rule
   */
 
-  --md-hr-bg-color: transparent; // @presenter Color
   --md-hr-border-color: var(--border-color-secondary); // @presenter Color
-  --md-hr-height: unset;
+  --md-hr-border: 0.5px solid var(--md-hr-border-color); // @presenter Border
   --md-hr-margin-vertical: 20px; // @presenter Spacing
 
   /**

package/src/components/Search/SearchAiDialog.tsx

@@ -94,6 +94,7 @@ export function SearchAiDialog({
     if (!initialMessage?.trim().length) {
       return;
     }
+    // oxlint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent -- appends the initial message into the conversation state lifted to the search root once the dialog mounts
     setConversation((prev) => [
       ...prev,
       { role: AiSearchConversationRole.USER, content: initialMessage },
@@ -105,6 +106,7 @@ export function SearchAiDialog({
       return;
     }
 
+    // oxlint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent -- merges the streamed assistant response into the lifted conversation state as chunks arrive
     setConversation((prev) => {
       const lastMessage = prev[prev.length - 1];
       const content: string = response || '';
@@ -146,6 +148,7 @@ export function SearchAiDialog({
 
   useEffect(() => {
     if (error) {
+      // oxlint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent -- drops the pending message from the lifted conversation state once the request errors
       setConversation((prev) => prev.slice(0, -1));
     }
   }, [error, setConversation]);

package/src/core/contexts/AccordionGroupContext.tsx

@@ -0,0 +1,3 @@
+import { createContext } from 'react';
+
+export const AccordionGroupContext = createContext<string | null>(null);

package/src/core/contexts/PageActionsContext.tsx

@@ -0,0 +1,7 @@
+import { createContext } from 'react';
+
+/**
+ * Whether the first heading inside the enclosing `Markdown` mounts the page actions.
+ * Without a provider `Heading` falls back to the page type in the page metadata.
+ */
+export const PageActionsContext = createContext<boolean | null>(null);

package/src/core/contexts/index.ts

@@ -1,7 +1,9 @@
 export * from './ThemeDataContext';
 export * from './MarkdownLinkContext';
+export * from './PageActionsContext';
 export * from './CodeWalkthrough/CodeWalkthroughControlsContext';
 export * from './CodeWalkthrough/CodeWalkthroughStepsContext';
+export * from './AccordionGroupContext';
 export * from './CodeSnippetContext';
 export * from './SearchContext';
 export * from './Toast/ToastContext';

package/src/core/hooks/__mocks__/use-theme-hooks.ts

@@ -18,6 +18,8 @@ export const useThemeHooks = vi.fn(() => ({
   useTelemetry: vi.fn(() => ({
     send: vi.fn(),
     sendCodeSnippetReportedMessage: vi.fn(),
+    sendConnectMcpClickedMessage: vi.fn(),
+    sendMcpConnectionSnippetCopiedMessage: vi.fn(),
     sendPageActionsButtonClickedMessage: vi.fn(),
     sendColorModeSwitchedMessage: vi.fn(),
   })),

package/src/core/hooks/code-walkthrough/use-code-walkthrough-steps.ts

@@ -95,6 +95,7 @@ export function useCodeWalkthroughSteps({
       });
     }
 
+    // oxlint-disable-next-line react-you-might-not-need-an-effect/no-chain-state-updates -- marker geometry is derived from post-layout measurements (offsetTop, clientHeight, window.innerHeight)
     setMarkers(
       markers.reduce(
         (acc, marker, index) => {

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-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-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/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/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/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/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',
 };