@redocly/theme 0.68.0-next.0 → 0.68.0-next.2

package/src/components/Catalog/CatalogEntity/CatalogEntityRelations/CatalogEntityRelationsTable.tsx

@@ -8,7 +8,8 @@ import type { BffCatalogEntity, BffCatalogRelatedEntity } from '@redocly/theme/c
 import { CatalogColumn } from '@redocly/theme/components/Catalog/CatalogTableView/CatalogTableView';
 import { CatalogActionsRow } from '@redocly/theme/components/Catalog/CatalogActionsRow';
 import { CatalogEntityRelationsTableContent } from '@redocly/theme/components/Catalog/CatalogEntity/CatalogEntityRelations/CatalogEntityRelationsTableContent';
-import { useCatalogEntityDetails, useThemeHooks } from '@redocly/theme/core/hooks';
+import { useThemeHooks } from '@redocly/theme/core/hooks';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 import { reverseRelationMap } from '@redocly/theme/core/constants';
 
 export type CatalogEntityRelationsTableProps = {
@@ -51,22 +52,20 @@ export function CatalogEntityRelationsTable({
 }: CatalogEntityRelationsTableProps): JSX.Element {
   const { useTelemetry } = useThemeHooks();
   const telemetry = useTelemetry();
-  const { getEntityDetailsLink } = useCatalogEntityDetails({
-    catalogConfig,
-    entitiesCatalogConfig,
-  });
 
   const onRowClick = (relatedEntity: BffCatalogRelatedEntity) => {
     if (searchQuery) {
-      telemetry.sendCatalogEntitiesRelatedEntitiesListSearchResultClickMessage([
+      telemetry.sendCatalogEntitiesRelatedEntitiesListSearchResultClickedMessage([
         {
-          id: relatedEntity.id,
-          object: 'catalog_entity',
-          uri: getEntityDetailsLink(relatedEntity),
+          ...getBaseDataAttributes(
+            'catalogEntitiesRelatedEntitiesListSearchResultId',
+            'catalogEntitiesRelatedEntitiesListSearchResult',
+          ),
           query: searchQuery,
           entityKey: entity.key,
           entityType: entity.type,
           relationType: reverseRelationMap[relatedEntity.relationType],
+          relatedEntityId: relatedEntity.id,
           relatedEntityKey: relatedEntity.key,
           relatedEntityType: relatedEntity.type,
         },

package/src/components/Catalog/CatalogEntity/CatalogEntitySchema.tsx

@@ -5,8 +5,9 @@ import * as Sampler from 'openapi-sampler';
 import type { CatalogEntityConfig } from '@redocly/config';
 import type { BffCatalogEntity, BffCatalogRelatedEntity } from '@redocly/theme/core/types';
 
-import { useCatalogEntityDetails, useThemeHooks } from '@redocly/theme/core/hooks';
+import { useThemeHooks } from '@redocly/theme/core/hooks';
 import { useCatalogEntitySchema } from '@redocly/theme/core/hooks';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 import { JsonViewer } from '@redocly/theme/components/JsonViewer/JsonViewer';
 import { CopyButton } from '@redocly/theme/components/Buttons/CopyButton';
 
@@ -24,7 +25,6 @@ export type CatalogEntitySchemaProps = {
 export function CatalogEntitySchema({
   entity,
   relatedEntity,
-  catalogConfig,
   RedocSchema,
   StoreProvider,
   GraphqlTypeRenderer,
@@ -35,9 +35,6 @@ export function CatalogEntitySchema({
   const { definition, parsedSchema, rawSchema } = useCatalogEntitySchema({ entity, relatedEntity });
   const isGraphql = entity.metadata?.specType === 'graphql';
   const graphqlSDL = entity?.metadata?.sdl;
-  const { getEntityDetailsLink } = useCatalogEntityDetails({
-    catalogConfig,
-  });
 
   return (
     <MetadataWrapper data-component-name="Catalog/CatalogEntity/CatalogEntitySchema">
@@ -54,9 +51,10 @@ export function CatalogEntitySchema({
             onCopyClick={() =>
               telemetry.sendCatalogEntitiesCopyDataSchemaClickedMessage([
                 {
-                  id: entity.id,
-                  object: 'catalog_entity',
-                  uri: getEntityDetailsLink(entity),
+                  ...getBaseDataAttributes('catalogEntitiesCopyDataSchemaId', 'button'),
+                  entityId: entity.id,
+                  entityKey: entity.key,
+                  entityType: entity.type,
                 },
               ])
             }

package/src/components/Catalog/CatalogFilter/CatalogFilterCheckboxes.tsx

@@ -12,7 +12,7 @@ import { FilterInput } from '@redocly/theme/components/Filter/FilterInput';
 import { useThemeHooks } from '@redocly/theme/core/hooks';
 import { CheckboxIcon } from '@redocly/theme/icons/CheckboxIcon/CheckboxIcon';
 import { CounterTag } from '@redocly/theme/components/Tags/CounterTag';
-import { changeTextCasing } from '@redocly/theme/core/utils';
+import { changeTextCasing, getBaseDataAttributes } from '@redocly/theme/core/utils';
 import { Accordion } from '@redocly/theme/components/Accordion/Accordion';
 
 export type CatalogFilterCheckboxesProps = FilterProps & {
@@ -104,9 +104,7 @@ export function CatalogFilterCheckboxes({
                   filter.toggleOption(value);
                   telemetry.sendCatalogEntitiesFilterCheckboxToggledMessage([
                     {
-                      id: filter.property + '--' + value,
-                      object: 'checkbox',
-                      uri: window.location.href,
+                      ...getBaseDataAttributes('catalogEntitiesFilterCheckboxId', 'checkbox'),
                       category: filter.property,
                       value: value,
                     },

package/src/components/Feedback/Feedback.tsx

@@ -11,6 +11,7 @@ import { Comment } from '@redocly/theme/components/Feedback/Comment';
 import { Mood } from '@redocly/theme/components/Feedback/Mood';
 import { Scale } from '@redocly/theme/components/Feedback/Scale';
 import { DEFAULT_FEEDBACK_TYPE } from '@redocly/theme/core/constants';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 
 const feedbackComponents = {
   rating: Rating,
@@ -58,7 +59,16 @@ export function Feedback(props: FeedbackProps & { path?: string }) {
           settings={settings}
           onSubmit={(values) => {
             submitFeedback({ type, values, path });
-            telemetry.sendFeedbackMessage({ feedbackType: type });
+            telemetry.sendFeedbackMessage([
+              {
+                ...getBaseDataAttributes<
+                  'feedbackFormId',
+                  'feedbackForm',
+                  'urn:redocly:realm:ui:feedbackForm:feedbackFormId'
+                >('feedbackFormId', 'feedbackForm'),
+                feedbackType: type,
+              },
+            ]);
           }}
         />
       </FeedbackWrapper>

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

@@ -64,8 +64,13 @@ export function useActiveHeading(
     const headers = Array.from(allHeaders);
 
     if (displayedHeadingsRef.current && displayedHeadingsRef.current.length > 0) {
-      const displayedIds = displayedHeadingsRef.current.map((h) => h?.id).filter(Boolean);
-      return headers.filter((header) => displayedIds.includes(header.id));
+      // Resolve targets by id so anchors that are not headings (e.g. numbered
+      // list items with a lifted headline) can be scrolled to and tracked.
+      return displayedHeadingsRef.current
+        .map((heading) =>
+          heading?.id ? allContent.querySelector<HTMLElement>(`[id="${heading.id}"]`) : null,
+        )
+        .filter((element): element is HTMLElement => element !== null);
     }
 
     return headers;

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

@@ -8,7 +8,7 @@ export const useTelemetryFallback = () => ({
   sendCatalogEntitiesCopyDataSchemaClickedMessage: () => {},
   sendCatalogEntitiesViewModeChangedMessage: () => {},
   sendCatalogEntitiesRelatedEntitiesListSearchQueryMessage: () => {},
-  sendCatalogEntitiesRelatedEntitiesListSearchResultClickMessage: () => {},
+  sendCatalogEntitiesRelatedEntitiesListSearchResultClickedMessage: () => {},
   sendCatalogEntitiesListSearchQueryMessage: () => {},
   sendCatalogEntitiesListSearchResultClickedMessage: () => {},
   sendRedirectMessage: () => {},

package/src/core/styles/dark.ts

@@ -60,6 +60,17 @@ const badgesDarkMode = css`
   // @tokens End
 `
 
+const numberedListDarkMode = css`
+  /**
+    * @tokens Markdown Numbered List
+    */
+
+  --md-numbered-list-marker-bg-color: var(--color-warm-grey-3); // @presenter Color
+  --md-numbered-list-marker-bg-color-hover: var(--color-warm-grey-4); // @presenter Color
+
+  // @tokens End
+`
+
 
 export const darkMode = css`
   /* === Dark Theme Colors  === */
@@ -352,6 +363,7 @@ export const darkMode = css`
   ${bannerDarkMode}
   ${admonitionDarkMode}
   ${badgesDarkMode}
+  ${numberedListDarkMode}
   ${activeBrandPaletteDark}
   ${codeBlockDarkMode}
   /**

package/src/core/styles/global.ts

@@ -29,6 +29,7 @@ import { productPicker } from '@redocly/theme/components/Product/variables';
 import { markdown } from '@redocly/theme/components/Markdown/variables';
 import { banner } from '@redocly/theme/components/Banner/variables';
 import { markdownTabs } from '@redocly/theme/markdoc/components/Tabs/variables';
+import { markdownNumberedList } from '@redocly/theme/markdoc/components/NumberedList/variables';
 import { diagram } from '@redocly/theme/markdoc/components/Diagram/variables';
 import { lastUpdated } from '@redocly/theme/components/LastUpdated/variables';
 import { logo } from '@redocly/theme/components/Logo/variables';
@@ -1344,6 +1345,7 @@ export const styles = css<{ palette?: string }>`
     ${logo}
     ${markdown}
     ${markdownTabs}
+    ${markdownNumberedList}
     ${diagram}
     ${menu}
     ${mobileMenu}

package/src/markdoc/components/NumberedList/NumberedItem.tsx

@@ -0,0 +1,274 @@
+import React, { createElement } from 'react';
+import styled, { css } from 'styled-components';
+
+import type { JSX, PropsWithChildren, ReactNode } from 'react';
+
+import { GenericIcon } from '@redocly/theme/icons/GenericIcon/GenericIcon';
+import { LinkIcon } from '@redocly/theme/icons/LinkIcon/LinkIcon';
+
+export const NumberedListType = {
+  ICON: 'icon',
+  NUMBER: 'number',
+  DOT: 'dot',
+} as const;
+
+export type NumberedListType = (typeof NumberedListType)[keyof typeof NumberedListType];
+
+export const NumberedListSize = {
+  SMALL: 'small',
+  MEDIUM: 'medium',
+} as const;
+
+export type NumberedListSize = (typeof NumberedListSize)[keyof typeof NumberedListSize];
+
+export type NumberedItemProps = PropsWithChildren<{
+  headline?: ReactNode;
+  anchorId?: string;
+  headlineLevel?: number;
+  icon?: string | ReactNode;
+  /* Internal use only: raw SVG content resolved for relative `.svg` icons */
+  iconRawContent?: string;
+  className?: string;
+  /* Injected by the parent NumberedList component */
+  type?: NumberedListType;
+  size?: NumberedListSize;
+  index?: number;
+  isLast?: boolean;
+}>;
+
+export function NumberedItem({
+  headline,
+  anchorId,
+  headlineLevel,
+  icon,
+  iconRawContent,
+  className,
+  type = NumberedListType.NUMBER,
+  size = NumberedListSize.MEDIUM,
+  index = 1,
+  isLast = true,
+  children,
+}: NumberedItemProps): JSX.Element {
+  const isDot = type === NumberedListType.DOT;
+  const headlineTextId = anchorId ? `${anchorId}-heading-text` : undefined;
+
+  const marker = (
+    <Marker $type={type} $size={size} data-dot={isDot || undefined}>
+      {type === NumberedListType.ICON && (
+        <MarkerContent className="numbered-item-marker-content">
+          <GenericIcon icon={icon} rawContent={iconRawContent} />
+        </MarkerContent>
+      )}
+      {type === NumberedListType.NUMBER && (
+        <MarkerContent className="numbered-item-marker-content">{index}</MarkerContent>
+      )}
+      {anchorId && (
+        <MarkerLink className="numbered-item-marker-link" $isDot={isDot}>
+          <MarkerLinkIcon
+            aria-hidden="true"
+            focusable="false"
+            color="--md-numbered-list-marker-text-color"
+          />
+        </MarkerLink>
+      )}
+    </Marker>
+  );
+
+  return (
+    <NumberedItemWrapper
+      data-component-name="Markdoc/NumberedList/NumberedItem"
+      className={className}
+      id={anchorId}
+      $size={size}
+      $isDot={isDot}
+    >
+      <MarkerRail>
+        {anchorId ? (
+          <a
+            href={`#${anchorId}`}
+            {...(headline
+              ? { 'aria-labelledby': headlineTextId }
+              : { 'aria-label': 'Link to this item' })}
+          >
+            {marker}
+          </a>
+        ) : (
+          marker
+        )}
+        <Tail data-testid="numbered-item-tail" $isLast={isLast} />
+      </MarkerRail>
+      <NumberedItemContent>
+        {headline &&
+          createElement(
+            NumberedItemHeadline,
+            { as: `h${headlineLevel ?? 3}` as keyof JSX.IntrinsicElements, id: headlineTextId },
+            headline,
+          )}
+        <NumberedItemBody>{children}</NumberedItemBody>
+      </NumberedItemContent>
+    </NumberedItemWrapper>
+  );
+}
+
+const markerSize = css<{ $size?: string }>`
+  ${({ $size }) =>
+    $size === NumberedListSize.SMALL
+      ? css`
+          width: var(--md-numbered-list-marker-small-size);
+          height: var(--md-numbered-list-marker-small-size);
+          --icon-width: var(--md-numbered-list-icon-small-size);
+          --icon-height: var(--md-numbered-list-icon-small-size);
+        `
+      : css`
+          width: var(--md-numbered-list-marker-medium-size);
+          height: var(--md-numbered-list-marker-medium-size);
+          --icon-width: var(--md-numbered-list-icon-medium-size);
+          --icon-height: var(--md-numbered-list-icon-medium-size);
+        `}
+`;
+
+const Marker = styled.span<{ $type: string; $size: string }>`
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  border-radius: 50%;
+  color: var(--md-numbered-list-marker-text-color);
+  font-size: var(--md-numbered-list-marker-font-size);
+
+  ${({ $type }) =>
+    $type === NumberedListType.DOT
+      ? css`
+          width: var(--md-numbered-list-dot-size);
+          height: var(--md-numbered-list-dot-size);
+          background-color: var(--text-color-primary);
+        `
+      : css`
+          ${markerSize}
+          background-color: var(--md-numbered-list-marker-bg-color);
+        `}
+`;
+
+const MarkerContent = styled.span`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+`;
+
+const MarkerLink = styled.span<{ $isDot?: boolean }>`
+  display: none;
+  align-items: center;
+  justify-content: center;
+
+  svg {
+    width: var(--icon-width, 16px);
+    height: var(--icon-height, 16px);
+  }
+
+  ${({ $isDot }) =>
+    $isDot &&
+    css`
+      position: absolute;
+      inset-inline-end: calc(100% + var(--md-numbered-list-dot-link-gap));
+    `}
+`;
+
+const MarkerLinkIcon = styled(LinkIcon)`
+  path:first-of-type {
+    fill: var(--md-numbered-list-marker-icon-bg-color);
+  }
+`;
+
+const MarkerRail = styled.span`
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  align-self: stretch;
+  flex-shrink: 0;
+
+  a {
+    display: flex;
+    border-radius: 50%;
+    /* Overrides the global markdown link rule a:not([role='button']), which is more specific. */
+    text-decoration: none !important;
+
+    &:hover,
+    &:focus {
+      text-decoration: none !important;
+    }
+  }
+`;
+
+const Tail = styled.span<{ $isLast: boolean }>`
+  flex: 1 0 0;
+  min-height: var(--spacing-xs);
+  width: var(--md-numbered-list-tail-width);
+  background: ${({ $isLast }) =>
+    $isLast
+      ? 'var(--md-numbered-list-tail-fade-gradient)'
+      : 'var(--md-numbered-list-tail-bg-color)'};
+`;
+
+const NumberedItemHeadline = styled.h3`
+  margin: 0;
+  color: var(--md-numbered-list-headline-text-color);
+  font-size: var(--md-numbered-list-headline-font-size);
+  font-weight: var(--md-numbered-list-headline-font-weight);
+  line-height: var(--md-numbered-list-headline-line-height);
+`;
+
+const NumberedItemBody = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: var(--md-numbered-list-body-gap);
+  color: var(--md-numbered-list-body-text-color);
+  font-size: var(--md-numbered-list-body-font-size);
+
+  > p {
+    margin: 0;
+  }
+`;
+
+const NumberedItemContent = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-unit);
+  flex: 1;
+  min-width: 0;
+  padding-bottom: var(--spacing-sm);
+`;
+
+const NumberedItemWrapper = styled.li<{ $size?: string; $isDot?: boolean }>`
+  display: flex;
+  gap: var(--md-numbered-list-gap);
+  align-items: stretch;
+
+  ${({ $isDot }) =>
+    $isDot &&
+    css`
+      ${MarkerRail} {
+        padding-top: var(--md-numbered-list-dot-rail-padding-top);
+      }
+    `}
+
+  &:last-child ${NumberedItemContent} {
+    padding-bottom: 0;
+  }
+
+  &:hover,
+  &:focus-within {
+    ${Marker} {
+      background-color: ${({ $isDot }) =>
+        $isDot ? 'var(--text-color-primary)' : 'var(--md-numbered-list-marker-bg-color-hover)'};
+    }
+
+    a ${Marker}:not([data-dot]) .numbered-item-marker-content {
+      display: none;
+    }
+
+    a ${Marker} .numbered-item-marker-link {
+      display: flex;
+    }
+  }
+`;

package/src/markdoc/components/NumberedList/NumberedList.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { JSX, PropsWithChildren } from 'react';
+
+export type NumberedListProps = PropsWithChildren<{
+  className?: string;
+}>;
+
+export function NumberedList({ className, children }: NumberedListProps): JSX.Element | null {
+  if (React.Children.count(children) === 0) {
+    return null;
+  }
+
+  return (
+    <NumberedListWrapper
+      data-component-name="Markdoc/NumberedList/NumberedList"
+      className={className}
+    >
+      {children}
+    </NumberedListWrapper>
+  );
+}
+
+const NumberedListWrapper = styled.ol`
+  display: flex;
+  flex-direction: column;
+  margin: var(--md-numbered-list-margin);
+  padding: 0;
+  list-style: none;
+
+  && {
+    & > li:not(:last-child) {
+      margin-bottom: 0;
+    }
+  }
+`;

package/src/markdoc/components/NumberedList/variables.ts

@@ -0,0 +1,39 @@
+import { css } from 'styled-components';
+
+export const markdownNumberedList = css`
+  /**
+  *  @tokens Markdown Numbered List
+  */
+
+  --md-numbered-list-margin: var(--spacing-sm) 0; // @presenter Spacing
+  --md-numbered-list-gap: var(--spacing-base); // @presenter Spacing
+
+  --md-numbered-list-marker-bg-color: var(--color-warm-grey-2); // @presenter Color
+  --md-numbered-list-marker-bg-color-hover: var(--color-warm-grey-3); // @presenter Color
+  --md-numbered-list-marker-icon-bg-color: transparent; // @presenter Color
+  --md-numbered-list-marker-text-color: var(--text-color-primary); // @presenter Color
+  --md-numbered-list-marker-font-size: var(--font-size-base); // @presenter FontSize
+
+  --md-numbered-list-marker-medium-size: 28px; // @presenter Spacing
+  --md-numbered-list-icon-medium-size: 16px; // @presenter Spacing
+  --md-numbered-list-tail-width: 1px; // @presenter Spacing
+  --md-numbered-list-marker-small-size: 24px; // @presenter Spacing
+  --md-numbered-list-icon-small-size: 12px; // @presenter Spacing
+  --md-numbered-list-dot-size: 10px; // @presenter Spacing
+  --md-numbered-list-dot-rail-padding-top: 7px; // @presenter Spacing
+  --md-numbered-list-dot-link-gap: 6px; // @presenter Spacing
+
+  --md-numbered-list-tail-bg-color: var(--md-numbered-list-marker-bg-color); // @presenter Color
+  --md-numbered-list-tail-fade-gradient: linear-gradient(to bottom, var(--md-numbered-list-tail-bg-color), transparent); // @presenter Color
+
+  --md-numbered-list-headline-text-color: var(--text-color-primary); // @presenter Color
+  --md-numbered-list-headline-font-size: var(--font-size-base); // @presenter FontSize
+  --md-numbered-list-headline-font-weight: var(--font-weight-medium); // @presenter FontWeight
+  --md-numbered-list-headline-line-height: var(--line-height-base); // @presenter LineHeight
+
+  --md-numbered-list-body-text-color: var(--text-color-secondary); // @presenter Color
+  --md-numbered-list-body-gap: var(--spacing-xs); // @presenter Spacing
+  --md-numbered-list-body-font-size: var(--font-size-base); // @presenter FontSize
+
+  // @tokens End
+`;

package/src/markdoc/components/default.ts

@@ -8,6 +8,8 @@ export * from '@redocly/theme/markdoc/components/Tabs/TabItemFragment';
 export * from '@redocly/theme/markdoc/components/Tabs/Tab';
 export * from '@redocly/theme/markdoc/components/Tabs/TabList';
 export * from '@redocly/theme/markdoc/components/Tabs/Tabs';
+export * from '@redocly/theme/markdoc/components/NumberedList/NumberedItem';
+export * from '@redocly/theme/markdoc/components/NumberedList/NumberedList';
 export * from '@redocly/theme/markdoc/components/CodeBlock/CodeBlock';
 export * from '@redocly/theme/markdoc/components/Cards/Cards';
 export * from '@redocly/theme/markdoc/components/Cards/Card';

package/src/markdoc/default.ts

@@ -14,6 +14,8 @@ import { markdocExample } from '@redocly/theme/markdoc/tags/markdoc-example';
 import { partial } from '@redocly/theme/markdoc/tags/partial';
 import { tab } from '@redocly/theme/markdoc/tags/tab';
 import { tabs } from '@redocly/theme/markdoc/tags/tabs';
+import { numberedItem } from '@redocly/theme/markdoc/tags/numbered-item';
+import { numberedList } from '@redocly/theme/markdoc/tags/numbered-list';
 import { debug } from '@redocly/theme/markdoc/tags/debug';
 import { codeSnippet } from '@redocly/theme/markdoc/tags/code-snippet';
 import { inlineSvg } from '@redocly/theme/markdoc/tags/inline-svg';
@@ -38,6 +40,8 @@ export const tags = {
   [partial.tagName]: partial.schema,
   [tab.tagName]: tab.schema,
   [tabs.tagName]: tabs.schema,
+  [numberedItem.tagName]: numberedItem.schema,
+  [numberedList.tagName]: numberedList.schema,
   [codeSnippet.tagName]: codeSnippet.schema,
   [inlineSvg.tagName]: inlineSvg.schema,
   [cards.tagName]: cards.schema,

package/src/markdoc/tags/numbered-item.ts

@@ -0,0 +1,46 @@
+import markdoc from '@markdoc/markdoc';
+
+import type { MarkdocSchemaWrapper } from '@redocly/theme/markdoc/tags/types';
+
+import { isTag } from '@redocly/theme/core/utils';
+
+const HEADING_TAG_NAME = /^(Heading|h[1-6])$/;
+
+export const numberedItem: MarkdocSchemaWrapper = {
+  schema: {
+    transform(node, config) {
+      const attributes = node.transformAttributes(config);
+      const children = node.transformChildren(config);
+      const [first, ...body] = children;
+
+      if (isTag(first) && HEADING_TAG_NAME.test(String(first.name))) {
+        const headlineLevel =
+          typeof first.attributes.level === 'number'
+            ? first.attributes.level
+            : Number(String(first.name).slice(1)) || undefined;
+
+        return new markdoc.Tag(
+          'NumberedItem',
+          {
+            ...attributes,
+            headline: first.children,
+            anchorId: first.attributes.id,
+            headlineLevel,
+          },
+          body,
+        );
+      }
+
+      return new markdoc.Tag('NumberedItem', attributes, children);
+    },
+    attributes: {
+      icon: { type: String, resolver: 'relativeOrCdnIcon' },
+      iconRawContent: {
+        // internal use only
+        type: String,
+        render: true,
+      },
+    },
+  },
+  tagName: 'numbered-item',
+};

package/src/markdoc/tags/numbered-list.ts

@@ -0,0 +1,34 @@
+import markdoc from '@markdoc/markdoc';
+
+import type { Tag } from '@markdoc/markdoc';
+import type { MarkdocSchemaWrapper } from '@redocly/theme/markdoc/tags/types';
+
+import { isTag } from '@redocly/theme/core/utils';
+
+export const numberedList: MarkdocSchemaWrapper = {
+  schema: {
+    transform(node, config) {
+      const attributes = node.transformAttributes(config);
+      const items = node
+        .transformChildren(config)
+        .filter((child): child is Tag => isTag(child) && child.name === 'NumberedItem');
+
+      items.forEach((item, index) => {
+        item.attributes = {
+          ...item.attributes,
+          type: attributes.type,
+          size: attributes.size,
+          index: index + 1,
+          isLast: index === items.length - 1,
+        };
+      });
+
+      return new markdoc.Tag('NumberedList', attributes, items);
+    },
+    attributes: {
+      type: { type: String, matches: ['icon', 'number', 'dot'], default: 'number' },
+      size: { type: String, matches: ['small', 'medium'], default: 'medium' },
+    },
+  },
+  tagName: 'numbered-list',
+};