supabase/apps/docs/internals/markdown-schema/ContentListings.ts

import { withDocsBasePath } from '~/internals/internal-links'
import type { ContentListingGroup } from '~/lib/content-listings.schema'
import {
  filterContentListingItems,
  getContentListingById,
  isExternalContentListingHref,
} from '~/lib/content-listings.utils'

import { getInternalLinkBaseUrl } from '../internal-links'

const HEADING_MARKDOWN: Record<'h2' | 'h3' | 'h4', string> = {
  h2: '##',
  h3: '###',
  h4: '####',
}

export function serializeContentListingGroupToMarkdown(
  group: ContentListingGroup,
  linkBaseUrl: string
): string {
  const items = filterContentListingItems(group.items)
  if (!items.length) return ''

  const lines: string[] = []
  if (group.heading) {
    const level = group.headingLevel ?? 'h2'
    lines.push(`${HEADING_MARKDOWN[level]} ${group.heading}`)
    lines.push('')
  }

  if (group.description) {
    lines.push(group.description)
    lines.push('')
  }

  for (const item of items) {
    if (!item.href) {
      lines.push(`- **${item.title}:** ${item.description}`)
      continue
    }

    const href = isExternalContentListingHref(item.href)
      ? item.href
      : `${linkBaseUrl}${withDocsBasePath(item.href)}`
    const description = item.subtitle ? `${item.subtitle}. ${item.description}` : item.description
    lines.push(`- **[${item.title}](${href}):** ${description}`)
  }

  return lines.join('\n')
}

/**
 * Markdown export handler for `<ContentListings id="..." />`. Looks up the
 * group by id in the same data registry the React component uses.
 */
export const ContentListings = ({ props }: { props: Record<string, unknown> }): string => {
  const id = typeof props.id === 'string' ? props.id : ''
  if (!id) return ''

  const group = getContentListingById(id)
  if (!group) return ''

  return serializeContentListingGroupToMarkdown(group, getInternalLinkBaseUrl())
}