@redocly/theme 0.61.1 → 0.62.0-custom.1

package/src/core/utils/transform-revisions-to-version-history.ts

@@ -8,72 +8,6 @@ import { VERSION_NOT_SPECIFIED } from '@redocly/theme/core/constants';
 
 import { toLocalizedShortDate, toLocalizedShortDateTime } from './date';
 
-function compareVersionsDescending(versionA: string, versionB: string): number {
-  return versionB.localeCompare(versionA, undefined, { numeric: true });
-}
-
-function extractGroupComparisonData(group: CatalogEntityVersionHistoryGroup): {
-  version: string;
-  isNotSpecified: boolean;
-  time: number;
-  hasCurrent: boolean;
-} {
-  const version = group.version;
-  const isNotSpecified = version === VERSION_NOT_SPECIFIED;
-
-  // Get version dates (oldest revision date for each group - the version's creation date)
-  // This ensures versions stay in their original order even when new revisions are added
-  const date =
-    group.singleRevisionDate ||
-    (group.revisions && group.revisions.length > 0
-      ? group.revisions[group.revisions.length - 1]?.revisionDate
-      : undefined) ||
-    '';
-  const time = date ? new Date(date).getTime() : 0;
-
-  const hasCurrent = group.hasCurrentRevisionFromBackend ?? false;
-
-  return { version, isNotSpecified, time, hasCurrent };
-}
-
-function compareVersionGroupsDescending(
-  groupA: CatalogEntityVersionHistoryGroup,
-  groupB: CatalogEntityVersionHistoryGroup,
-): number {
-  const {
-    version: versionA,
-    isNotSpecified: isNotSpecifiedA,
-    time: timeA,
-    hasCurrent: hasCurrentA,
-  } = extractGroupComparisonData(groupA);
-  const {
-    version: versionB,
-    isNotSpecified: isNotSpecifiedB,
-    time: timeB,
-    hasCurrent: hasCurrentB,
-  } = extractGroupComparisonData(groupB);
-
-  // First, compare by version date (oldest first, so most recent versions come first)
-  const dateComparison = timeB - timeA;
-  if (dateComparison !== 0) {
-    return dateComparison;
-  }
-
-  // If dates are equal, prioritize the one with isCurrent from backend
-  if (hasCurrentA !== hasCurrentB) {
-    return hasCurrentB ? 1 : -1; // hasCurrentB comes first if true
-  }
-
-  // If both have same isCurrent status, compare by version
-  // If both are unknown or both are real versions, compare by version
-  if (isNotSpecifiedA === isNotSpecifiedB) {
-    return compareVersionsDescending(versionA, versionB);
-  }
-
-  // If one is unknown and one is a real version, unknown comes last
-  return isNotSpecifiedA ? 1 : -1;
-}
-
 export type TransformRevisionsToVersionHistoryParams = {
   revisions: BffCatalogEntityRevision[];
   currentRevisionDate?: string;
@@ -100,13 +34,7 @@ export function transformRevisionsToVersionHistory({
   });
 
   const versionGroups = Array.from(versionMap.entries()).map(([version, versionRevisions]) => {
-    const sortedRevisions = [...versionRevisions].sort((a, b) => {
-      const dateA = a.revision ? new Date(a.revision).getTime() : 0;
-      const dateB = b.revision ? new Date(b.revision).getTime() : 0;
-      return dateB - dateA;
-    });
-
-    const latestRevision = sortedRevisions[0];
+    const latestRevision = versionRevisions[0];
 
     const versionMatches =
       normalizedCurrentVersion === undefined || normalizedCurrentVersion === version;
@@ -114,7 +42,7 @@ export function transformRevisionsToVersionHistory({
     let isCurrent: boolean;
     if (currentRevisionDate !== undefined) {
       // Check if revision matches AND version matches
-      const revisionMatches = sortedRevisions.some((rev) => rev.revision === currentRevisionDate);
+      const revisionMatches = versionRevisions.some((rev) => rev.revision === currentRevisionDate);
       isCurrent = revisionMatches && versionMatches;
     } else {
       // When no revision is specified, use isCurrent flag from the latest revision
@@ -123,29 +51,21 @@ export function transformRevisionsToVersionHistory({
     }
 
     // Check if any revision in this version group is the default version
-    const isDefaultVersion = sortedRevisions.some((rev) => rev.isDefaultVersion === true);
-
-    const revisions =
-      sortedRevisions.length > 1
-        ? sortedRevisions.map((rev, index): CatalogEntityRevision => {
-            const revisionMatches = currentRevisionDate
-              ? rev.revision === currentRevisionDate
-              : false;
-            const isActiveRevision = revisionMatches && versionMatches;
-            const isCurrentByDefault =
-              !currentRevisionDate &&
-              normalizedCurrentVersion === undefined &&
-              index === 0 &&
-              isCurrent;
-            return {
-              name: `r.${sortedRevisions.length - index}`,
-              date: toLocalizedShortDateTime(rev.revision, locale),
-              revisionDate: rev.revision,
-              isActive: isActiveRevision || isCurrentByDefault,
-              isCurrent: rev.isCurrent ?? false,
-            };
-          })
-        : undefined;
+    const isDefaultVersion = versionRevisions.some((rev) => rev.isDefaultVersion === true);
+
+    const revisions = versionRevisions.map((rev, index): CatalogEntityRevision => {
+      const revisionMatches = currentRevisionDate ? rev.revision === currentRevisionDate : false;
+      const isActiveRevision = revisionMatches && versionMatches;
+      const isCurrentByDefault =
+        !currentRevisionDate && normalizedCurrentVersion === undefined && index === 0 && isCurrent;
+      return {
+        name: `r.${versionRevisions.length - index}`,
+        date: toLocalizedShortDateTime(rev.revision, locale),
+        revisionDate: rev.revision,
+        isActive: isActiveRevision || isCurrentByDefault,
+        isCurrent: rev.isCurrent ?? false,
+      };
+    });
 
     return {
       version,
@@ -155,9 +75,9 @@ export function transformRevisionsToVersionHistory({
       hasCurrentRevisionFromBackend: latestRevision?.isCurrent ?? false,
       isDefaultVersion,
       revisions,
-      singleRevisionDate: sortedRevisions.length === 1 ? sortedRevisions[0]?.revision : undefined,
+      singleRevisionDate: versionRevisions.length === 1 ? versionRevisions[0]?.revision : undefined,
     };
   });
 
-  return versionGroups.sort(compareVersionGroupsDescending);
+  return versionGroups;
 }

package/src/ext/process-scorecard.ts

@@ -0,0 +1,59 @@
+import { useCallback } from 'react';
+
+import type { CatalogItem } from '@redocly/theme/core/types';
+import type { ReactNode } from 'react';
+
+export type ScorecardApiTableRow<TScorecard = unknown> = {
+  api: CatalogItem;
+  scorecard?: TScorecard;
+};
+
+export type ScorecardApiTableColumnStatus = 'error' | 'warning' | 'success';
+
+export type ScorecardApiTableColumnDetails<TScorecard = unknown> = {
+  hidden?: boolean;
+  tabLabel?: string;
+  description?: ReactNode | ((row: ScorecardApiTableRow<TScorecard>) => ReactNode);
+  render?: (params: { row: ScorecardApiTableRow<TScorecard>; value: unknown }) => ReactNode;
+  status?:
+    | ScorecardApiTableColumnStatus
+    | ((params: {
+        row: ScorecardApiTableRow<TScorecard>;
+        value: unknown;
+      }) => ScorecardApiTableColumnStatus);
+  statusRule?: 'problem-if-truthy' | 'problem-if-falsy';
+};
+
+export type ScorecardApiTableColumn<TScorecard = unknown> = {
+  id: string;
+  header: string;
+  placement?: 'beforeLevels' | 'afterLevels';
+  size?: number;
+  minSize?: number;
+  maxSize?: number;
+  sortRule?: 'string' | 'number' | 'date';
+  sortDescFirst?: boolean;
+  getValue?: (row: ScorecardApiTableRow<TScorecard>) => unknown;
+  getSortValue?: (row: ScorecardApiTableRow<TScorecard>) => unknown;
+  render?: (params: { row: ScorecardApiTableRow<TScorecard>; value: unknown }) => ReactNode;
+  details?: ScorecardApiTableColumnDetails<TScorecard>;
+  sortingFn?: (params: {
+    rowA: ScorecardApiTableRow<TScorecard>;
+    rowB: ScorecardApiTableRow<TScorecard>;
+    valueA: unknown;
+    valueB: unknown;
+  }) => number;
+};
+
+export function useProcessScorecard(): {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  processScorecard: <T = any>(scorecard: T, api: CatalogItem) => T;
+  processInfo: <T>(info: T) => T;
+  getApiTableColumns: () => ScorecardApiTableColumn[];
+} {
+  return {
+    processScorecard: useCallback((scorecard) => scorecard, []),
+    processInfo: useCallback((info) => info, []),
+    getApiTableColumns: useCallback(() => [], []),
+  };
+}

package/src/icons/DirectionRightIcon/DirectionRightIcon.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { IconProps } from '@redocly/theme/icons/types';
+
+import { getCssColorVariable } from '@redocly/theme/core/utils';
+
+const Icon = (props: IconProps) => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M9.5 4L8.79295 4.70705L11.0859 7H5C4.73478 7 4.48043 7.10536 4.29289 7.29289C4.10536 7.48043 4 7.73478 4 8V14H5V8H11.0859L8.79295 10.2929L9.5 11L13 7.5L9.5 4Z"
+      fill="#1A1C21"
+    />
+    <path d="M5 2H4V6H5V2Z" fill="#1A1C21" />
+  </svg>
+);
+
+export const DirectionRightIcon = styled(Icon).attrs(() => ({
+  'data-component-name': 'icons/DirectionRightIcon/DirectionRightIcon',
+}))`
+  path {
+    fill: ${({ color }) => getCssColorVariable(color)};
+  }
+
+  height: ${({ size }) => size || '16px'};
+  width: ${({ size }) => size || '16px'};
+  vertical-align: middle;
+`;

package/src/icons/FitToViewIcon/FitToViewIcon.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { IconProps } from '@redocly/theme/icons/types';
+
+import { getCssColorVariable } from '@redocly/theme/core/utils';
+
+const Icon = (props: IconProps) => (
+  <svg viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" {...props}>
+    <path d="M1 1H5V2.5H2.5V5H1V1Z" />
+    <path d="M15 1H11V2.5H13.5V5H15V1Z" />
+    <path d="M1 15H5V13.5H2.5V11H1V15Z" />
+    <path d="M15 15H11V13.5H13.5V11H15V15Z" />
+  </svg>
+);
+
+export const FitToViewIcon = styled(Icon).attrs(() => ({
+  'data-component-name': 'icons/FitToViewIcon/FitToViewIcon',
+}))<IconProps>`
+  path {
+    fill: ${({ color }) => getCssColorVariable(color)};
+  }
+
+  height: ${({ size }) => size || '16px'};
+  width: ${({ size }) => size || '16px'};
+`;

package/src/index.ts

@@ -27,6 +27,7 @@ export * from '@redocly/theme/components/Tags/CounterTag';
 export * from '@redocly/theme/components/VersionPicker/VersionPicker';
 export * from '@redocly/theme/components/Marker/Marker';
 export * from '@redocly/theme/components/PageActions/PageActions';
+export * from '@redocly/theme/components/SvgViewer/SvgViewer';
 /* Buttons */
 export * from '@redocly/theme/components/Buttons/CopyButton';
 export * from '@redocly/theme/components/Buttons/EditPageButton';
@@ -95,9 +96,12 @@ export * from '@redocly/theme/components/Sidebar/Sidebar';
 /* OpenApiDocs */
 export * from '@redocly/theme/components/OpenApiDocs/hooks/AfterOpenApiOperation';
 export * from '@redocly/theme/components/OpenApiDocs/hooks/AfterOpenApiTitle';
+export * from '@redocly/theme/components/OpenApiDocs/hooks/AfterOpenApiDescription';
 export * from '@redocly/theme/components/OpenApiDocs/hooks/BeforeOpenApiOperation';
 export * from '@redocly/theme/components/OpenApiDocs/hooks/OpenApiFooter';
 export * from '@redocly/theme/components/OpenApiDocs/hooks/OpenApiHeader';
+export * from '@redocly/theme/components/OpenApiDocs/hooks/AdditionalOverviewInfo';
+export * from '@redocly/theme/components/AsyncApiDocs/hooks/AfterAsyncApiChannelDescription';
 /* SidebarActions */
 export * from '@redocly/theme/components/SidebarActions/ChangeViewButton';
 export * from '@redocly/theme/components/SidebarActions/SidebarActions';
@@ -293,6 +297,7 @@ export * from '@redocly/theme/icons/WorkflowHierarchyIcon/WorkflowHierarchyIcon'
 export * from '@redocly/theme/icons/GenericIcon/GenericIcon';
 export * from '@redocly/theme/icons/ShareIcon/ShareIcon';
 export * from '@redocly/theme/icons/HashtagIcon/HashtagIcon';
+export * from '@redocly/theme/icons/FitToViewIcon/FitToViewIcon';
 /* Layouts */
 export * from '@redocly/theme/layouts/RootLayout';
 export * from '@redocly/theme/layouts/PageLayout';
@@ -302,6 +307,9 @@ export * from '@redocly/theme/layouts/OIDCForbidden';
 export * from '@redocly/theme/layouts/ThreePanelLayout';
 export * from '@redocly/theme/layouts/CodeWalkthroughLayout';
 export * from '@redocly/theme/layouts/InternalServerErrorLayout';
+export * from '@redocly/theme/layouts/DocumentationLayout';
+export * from '@redocly/theme/layouts/DocumentationLayoutTop';
+export * from '@redocly/theme/layouts/DocumentationLayoutBottom';
 /* Markdoc */
 export * as markdoc from '@redocly/theme/markdoc/default';
 /* DatePicker */

package/src/layouts/DocumentationLayout.tsx

@@ -4,12 +4,10 @@ import styled from 'styled-components';
 import type { JSX } from 'react';
 import type { ResolvedNavItemWithLink, MarkdownConfig } from '@redocly/config';
 
-import { EditPageButton } from '@redocly/theme/components/Buttons/EditPageButton';
 import { breakpoints } from '@redocly/theme/core/utils';
-import { PageNavigation } from '@redocly/theme/components/PageNavigation/PageNavigation';
-import { LastUpdated } from '@redocly/theme/components/LastUpdated/LastUpdated';
-import { Breadcrumbs as ThemeBreadcrumbs } from '@redocly/theme/components/Breadcrumbs/Breadcrumbs';
 import { CodeSnippetProvider } from '@redocly/theme/core/contexts/CodeSnippetContext';
+import { DocumentationLayoutTop } from '@redocly/theme/layouts/DocumentationLayoutTop';
+import { DocumentationLayoutBottom } from '@redocly/theme/layouts/DocumentationLayoutBottom';
 
 type DocumentationLayoutProps = {
   tableOfContent: React.ReactNode;
@@ -36,21 +34,13 @@ export function DocumentationLayout({
   className,
   children,
 }: React.PropsWithChildren<DocumentationLayoutProps>): JSX.Element {
-  const { editPage: themeEditPage } = config || {};
-  const mergedConf = editPage ? { ...themeEditPage, ...editPage } : undefined;
-
   return (
     <CodeSnippetProvider>
       <LayoutWrapper data-component-name="Layout/DocumentationLayout" className={className}>
         <ContentWrapper withToc={!config?.toc?.hide}>
-          <Breadcrumbs />
-          <LayoutTop>
-            {lastModified && <LastUpdated lastModified={new Date(lastModified)} />}
-            {mergedConf && <EditPageButton to={mergedConf.to} />}
-          </LayoutTop>
+          <DocumentationLayoutTop config={config} editPage={editPage} lastModified={lastModified} />
           {children}
-          <LayoutBottom>{feedback}</LayoutBottom>
-          <PageNavigation nextPage={nextPage} prevPage={prevPage} />
+          <DocumentationLayoutBottom feedback={feedback} nextPage={nextPage} prevPage={prevPage} />
         </ContentWrapper>
         {tableOfContent}
       </LayoutWrapper>
@@ -89,19 +79,3 @@ const ContentWrapper = styled.section<{ withToc: boolean }>`
     width: ${({ withToc }) => (withToc ? `calc(90% - var(--toc-width))` : '90%')};
   }
 `;
-
-const LayoutTop = styled.div`
-  display: flex;
-  justify-content: space-between;
-  flex-flow: row nowrap;
-`;
-
-const Breadcrumbs = styled(ThemeBreadcrumbs)`
-  margin-bottom: var(--breadcrumbs-margin-bottom);
-`;
-
-const LayoutBottom = styled(LayoutTop)`
-  > * {
-    margin: 25px 0;
-  }
-`;

package/src/layouts/DocumentationLayoutBottom.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { JSX } from 'react';
+import type { ResolvedNavItemWithLink } from '@redocly/config';
+
+import { PageNavigation } from '@redocly/theme/components/PageNavigation/PageNavigation';
+
+type DocumentationLayoutBottomProps = {
+  feedback: React.ReactNode;
+  nextPage?: ResolvedNavItemWithLink | null;
+  prevPage?: ResolvedNavItemWithLink | null;
+  className?: string;
+};
+
+export function DocumentationLayoutBottom({
+  feedback,
+  nextPage,
+  prevPage,
+}: React.PropsWithChildren<DocumentationLayoutBottomProps>): JSX.Element {
+  return (
+    <Wrapper data-component-name="Layout/DocumentationLayoutBottom">
+      <LayoutBottom>{feedback}</LayoutBottom>
+      <PageNavigation nextPage={nextPage} prevPage={prevPage} />
+    </Wrapper>
+  );
+}
+
+const Wrapper = styled.div`
+  display: flex;
+  flex-direction: column;
+`;
+
+const LayoutBottom = styled.div`
+  display: flex;
+  justify-content: space-between;
+  flex-flow: row nowrap;
+
+  > * {
+    margin: 25px 0;
+  }
+`;

package/src/layouts/DocumentationLayoutTop.tsx

@@ -0,0 +1,52 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { JSX } from 'react';
+import type { MarkdownConfig } from '@redocly/config';
+
+import { EditPageButton } from '@redocly/theme/components/Buttons/EditPageButton';
+import { LastUpdated } from '@redocly/theme/components/LastUpdated/LastUpdated';
+import { Breadcrumbs as ThemeBreadcrumbs } from '@redocly/theme/components/Breadcrumbs/Breadcrumbs';
+
+type DocumentationLayoutTopProps = {
+  config?: MarkdownConfig;
+  editPage?: {
+    to: string;
+  };
+  /** String in ISO format */
+  lastModified?: string | null;
+};
+
+export function DocumentationLayoutTop({
+  config,
+  editPage,
+  lastModified,
+}: React.PropsWithChildren<DocumentationLayoutTopProps>): JSX.Element {
+  const { editPage: themeEditPage } = config || {};
+  const mergedConf = editPage ? { ...themeEditPage, ...editPage } : undefined;
+
+  return (
+    <Wrapper data-component-name="Layout/DocumentationLayoutTop">
+      <Breadcrumbs />
+      <LayoutTop>
+        {lastModified && <LastUpdated lastModified={new Date(lastModified)} />}
+        {mergedConf && <EditPageButton to={mergedConf.to} />}
+      </LayoutTop>
+    </Wrapper>
+  );
+}
+
+const Wrapper = styled.div`
+  display: flex;
+  flex-direction: column;
+`;
+
+const LayoutTop = styled.div`
+  display: flex;
+  justify-content: space-between;
+  flex-flow: row nowrap;
+`;
+
+const Breadcrumbs = styled(ThemeBreadcrumbs)`
+  margin-bottom: var(--breadcrumbs-margin-bottom);
+`;

package/src/layouts/Forbidden.tsx

@@ -5,50 +5,65 @@ import type { JSX } from 'react';
 
 import { useThemeHooks } from '@redocly/theme/core/hooks';
 import { Button } from '@redocly/theme/components/Button/Button';
+import { ArrowLeftIcon } from '@redocly/theme/icons/ArrowLeftIcon/ArrowLeftIcon';
 
 export function Forbidden(): JSX.Element {
   const { useTranslate } = useThemeHooks();
   const { translate } = useTranslate();
 
   return (
-    <Wrapper data-component-name="Pages/Forbidden">
-      <Header>403</Header>
-      <Description data-translation-key="page.forbidden.title">
+    <ForbiddenWrapper data-component-name="layouts/Forbidden">
+      <StatusText>403</StatusText>
+      <Title data-translation-key="page.forbidden.title">
         {translate('page.forbidden.title', 'Access forbidden')}
+      </Title>
+      <Description data-translation-key="page.forbidden.description">
+        {translate(
+          'page.forbidden.description',
+          "You don't have permission to access this page. If you believe this is an error, contact your administrator or return to the homepage.",
+        )}
       </Description>
-      <HomeButton variant="primary" size="large" to="/" data-translation-key="page.homeButton">
+      <Button
+        variant="primary"
+        size="large"
+        to="/"
+        data-translation-key="page.homeButton"
+        icon={<ArrowLeftIcon />}
+      >
         {translate('page.homeButton', 'Go home')}
-      </HomeButton>
-    </Wrapper>
+      </Button>
+    </ForbiddenWrapper>
   );
 }
 
-const Wrapper = styled.div`
+const ForbiddenWrapper = styled.div`
+  height: 100%;
+  max-width: var(--page-403-max-width);
   display: flex;
   flex-direction: column;
-  align-items: center;
   justify-content: center;
-  margin: 25px auto;
+  margin: var(--page-403-margin-vertical) var(--page-403-margin-horizontal);
   font-family: var(--page-403-font-family);
-  text-align: center;
+  gap: var(--page-403-gap);
 `;
 
-const Header = styled.div`
-  color: var(--page-403-header-text-color);
-  margin: var(--page-403-header-margin);
-  font-size: var(--page-403-header-font-size);
-  line-height: var(--page-403-header-line-height);
-  font-weight: var(--page-403-header-font-weight);
+const StatusText = styled.div`
+  color: var(--page-403-status-text-color);
+  font-size: var(--page-403-status-font-size);
+  line-height: var(--page-403-status-line-height);
+  font-weight: var(--page-403-status-font-weight);
+`;
+
+const Title = styled.div`
+  color: var(--page-403-title-text-color);
+  font-size: var(--page-403-title-font-size);
+  line-height: var(--page-403-title-line-height);
+  font-weight: var(--page-403-title-font-weight);
 `;
 
 const Description = styled.div`
   color: var(--page-403-description-text-color);
-  margin: var(--page-403-description-margin);
   font-size: var(--page-403-description-font-size);
   line-height: var(--page-403-description-line-height);
   font-weight: var(--page-403-description-font-weight);
 `;
-
-const HomeButton = styled(Button)`
-  margin-top: var(--page-403-button-margin);
-`;

package/src/markdoc/components/Cards/Card.tsx

@@ -167,6 +167,7 @@ const CardWrapper = styled.div.attrs<{
   overflow: hidden;
   transition: box-shadow 0.3s ease;
   position: relative;
+  text-decoration: none;
   --md-paragraph-margin: 0;
   --link-decoration-hover: none;
 

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

@@ -78,7 +78,7 @@ const FilterWrapper = styled.div`
   padding-bottom: var(--spacing-xs);
   top: var(--navbar-height);
   background-color: var(--bg-color);
-  z-index: 1;
+  z-index: var(--z-index-raised);
   max-width: var(--md-content-max-width);
 `;
 

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

@@ -1,14 +1,44 @@
-import React, { createElement } from 'react';
+import React, { createElement, isValidElement } from 'react';
 import styled from 'styled-components';
 import { useLocation } from 'react-router-dom';
 
-import type { JSX, PropsWithChildren } from 'react';
+import type { JSX, PropsWithChildren, ReactElement, ReactNode } from 'react';
 
+import { Image as MarkdocImage } from '@redocly/theme/markdoc/components/Image/Image';
 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';
 
+function renderWithSpanWrapper(children: ReactNode): ReactNode {
+  const childrenArray = React.Children.toArray(children);
+
+  if (childrenArray.length === 0) return null;
+
+  const first = childrenArray[0];
+  const last = childrenArray[childrenArray.length - 1];
+
+  // Check if an element is an <img> or the Markdoc Image component
+  const isImage = (node: ReactNode): node is ReactElement => {
+    if (!isValidElement(node)) return false;
+    if (typeof node.type === 'string') return node.type === 'img';
+    return node.type === MarkdocImage;
+  };
+
+  const middleChildren = childrenArray.slice(
+    isImage(first) ? 1 : 0,
+    isImage(last) ? childrenArray.length - 1 : childrenArray.length,
+  );
+
+  return (
+    <>
+      {isImage(first) && first}
+      {middleChildren.length > 0 && <StyledHeadingText>{middleChildren}</StyledHeadingText>}
+      {isImage(last) && last}
+    </>
+  );
+}
+
 /**
  * Class name for all MD tags
  */
@@ -57,7 +87,7 @@ export function Heading({
     },
     <HeadingContentWrapper>
       {linkEl}
-      <span>{children}</span>
+      <span>{renderWithSpanWrapper(children)}</span>
       {isMarkdownPage && __idx === 0 ? <PageActions pageSlug={pathname} /> : null}
     </HeadingContentWrapper>,
   );
@@ -66,5 +96,23 @@ export function Heading({
 const HeadingContentWrapper = styled.div`
   display: flex;
   gap: var(--spacing-xs);
-  align-items: center;
+
+  & > span {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--spacing-sm);
+  }
+
+  &:has([data-component-name='PageActions/PageActions']:hover) {
+    && .anchor svg {
+      visibility: hidden;
+    }
+  }
+`;
+
+const StyledHeadingText = styled.span`
+  margin: auto 0;
+  && > img:only-child {
+    display: inline-block;
+  }
 `;