feat: add discovery landing transformer for Article API (#59074)

heiskr · web-flow · commit 7206b3aa9edf · 2026-01-13T16:55:05.000Z
diff --git a/src/article-api/lib/get-all-toc-items.ts b/src/article-api/lib/get-all-toc-items.ts
@@ -0,0 +1,127 @@
+import type { Context, Page } from '@/types'
+import type { LinkData } from '@/article-api/transformers/types'
+import { resolvePath } from './resolve-path'
+
+interface PageWithChildren extends Page {
+  children?: string[]
+  category?: string[]
+}
+
+interface TocItem extends LinkData {
+  category?: string[]
+  childTocItems?: TocItem[]
+}
+
+/**
+ * Recursively gathers all TOC items from a page and its descendants.
+ * This mirrors the behavior of getTocItems() in the generic-toc middleware
+ * but works with the page.children frontmatter property.
+ *
+ * @param page - The page to gather TOC items from
+ * @param context - The rendering context
+ * @param options - Configuration options
+ * @returns Array of TocItems with nested childTocItems
+ */
+export async function getAllTocItems(
+  page: Page,
+  context: Context,
+  options: {
+    recurse?: boolean
+    renderIntros?: boolean
+  } = {},
+): Promise<TocItem[]> {
+  const { recurse = true, renderIntros = true } = options
+  const pageWithChildren = page as PageWithChildren
+  const languageCode = page.languageCode || 'en'
+
+  if (!pageWithChildren.children || pageWithChildren.children.length === 0) {
+    return []
+  }
+
+  // Get the page's pathname for resolving children
+  const pagePermalink = page.permalinks.find(
+    (p) => p.languageCode === languageCode && p.pageVersion === context.currentVersion,
+  )
+  const pathname = pagePermalink ? pagePermalink.href : `/${languageCode}`
+
+  const items: TocItem[] = []
+
+  for (const childHref of pageWithChildren.children) {
+    const childPage = resolvePath(childHref, languageCode, pathname, context) as
+      | PageWithChildren
+      | undefined
+
+    if (!childPage) continue
+
+    const title = await childPage.renderTitle(context, { unwrap: true })
+    const intro =
+      renderIntros && childPage.intro
+        ? await childPage.renderProp('intro', context, { textOnly: true })
+        : ''
+
+    const childPermalink = childPage.permalinks.find(
+      (p) => p.languageCode === languageCode && p.pageVersion === context.currentVersion,
+    )
+    const href = childPermalink ? childPermalink.href : childHref
+
+    const category = childPage.category || []
+
+    const item: TocItem = {
+      href,
+      title,
+      intro,
+      category,
+      childTocItems: [],
+    }
+
+    // Recursively get children if enabled
+    if (recurse && childPage.children && childPage.children.length > 0) {
+      item.childTocItems = await getAllTocItems(childPage, context, options)
+    }
+
+    items.push(item)
+  }
+
+  return items
+}
+
+/**
+ * Flattens nested TOC items into a single array.
+ * Only includes leaf nodes (items without children) or all items based on options.
+ *
+ * @param tocItems - The nested TOC items to flatten
+ * @param options - Configuration options
+ * @returns Flat array of LinkData items
+ */
+export function flattenTocItems(
+  tocItems: TocItem[],
+  options: {
+    excludeParents?: boolean // If true, only include items without children
+  } = {},
+): LinkData[] {
+  const { excludeParents = true } = options
+  const result: LinkData[] = []
+
+  function recurse(items: TocItem[]) {
+    for (const item of items) {
+      const hasChildren = item.childTocItems && item.childTocItems.length > 0
+
+      // Include this item if it's a leaf or if we're including parents
+      if (!hasChildren || !excludeParents) {
+        result.push({
+          href: item.href,
+          title: item.title,
+          intro: item.intro,
+        })
+      }
+
+      // Recurse into children
+      if (hasChildren) {
+        recurse(item.childTocItems!)
+      }
+    }
+  }
+
+  recurse(tocItems)
+  return result
+}
diff --git a/src/article-api/tests/discovery-landing-transformer.ts b/src/article-api/tests/discovery-landing-transformer.ts
@@ -0,0 +1,54 @@
+import { describe, expect, test } from 'vitest'
+
+import { get } from '@/tests/helpers/e2etest'
+
+const makeURL = (pathname: string): string =>
+  `/api/article/body?${new URLSearchParams({ pathname })}`
+
+describe('discovery landing transformer', () => {
+  test('renders a discovery landing page in markdown', async () => {
+    // /en/get-started/carousel is a discovery landing page with recommended carousel
+    const res = await get(makeURL('/en/get-started/carousel'))
+    expect(res.statusCode).toBe(200)
+    expect(res.headers['content-type']).toContain('text/markdown')
+
+    // Check for title and intro
+    expect(res.body).toContain('# Landing Page Carousel')
+    expect(res.body).toContain('A test category page for testing the LandingCarousel component')
+
+    // Should have Articles section with all descendant articles
+    expect(res.body).toContain('## Articles')
+    expect(res.body).toContain('[Carousel Article One]')
+    expect(res.body).toContain('[Carousel Article Two]')
+    expect(res.body).toContain('[Carousel Article Three]')
+  })
+
+  test('renders a discovery landing page with children', async () => {
+    // /en/get-started/article-grid-discovery has discovery landing with children
+    const res = await get(makeURL('/en/get-started/article-grid-discovery'))
+    expect(res.statusCode).toBe(200)
+    expect(res.headers['content-type']).toContain('text/markdown')
+
+    // Check for title
+    expect(res.body).toContain('# Article Grid Discovery')
+
+    // Should have Articles section with all descendant articles (recursive)
+    expect(res.body).toContain('## Articles')
+    expect(res.body).toContain('[Grid Article One]')
+    expect(res.body).toContain('[Grid Article Two]')
+    expect(res.body).toContain('[Grid Article Three]')
+    expect(res.body).toContain('[Grid Article Four]')
+  })
+
+  test('handles discovery landing structure consistently', async () => {
+    // Discovery pages should have a consistent structure
+    const res = await get(makeURL('/en/get-started/carousel'))
+    expect(res.statusCode).toBe(200)
+
+    // Should have intro
+    expect(res.body).toMatch(/^# .+\n\n.+\n\n/)
+
+    // Should have at least one section
+    expect(res.body).toContain('##')
+  })
+})
diff --git a/src/article-api/transformers/discovery-landing-transformer.ts b/src/article-api/transformers/discovery-landing-transformer.ts
@@ -0,0 +1,211 @@
+import type { Context, Page } from '@/types'
+import type { PageTransformer, TemplateData, Section, LinkData } from './types'
+import { renderContent } from '@/content-render/index'
+import { loadTemplate } from '@/article-api/lib/load-template'
+import { getAllTocItems, flattenTocItems } from '@/article-api/lib/get-all-toc-items'
+
+interface RecommendedItem {
+  href: string
+  title?: string
+  intro?: string
+}
+
+interface DiscoveryPage extends Page {
+  rawIntroLinks?: Record<string, string>
+  introLinks?: Record<string, string>
+  recommended?: RecommendedItem[]
+  rawRecommended?: string[]
+  includedCategories?: string[]
+  children?: string[]
+}
+
+/**
+ * Transforms discovery-landing pages into markdown format.
+ * Handles recommended carousel, intro links, article grids with
+ * category filtering, and children listings.
+ */
+export class DiscoveryLandingTransformer implements PageTransformer {
+  templateName = 'landing-page.template.md'
+
+  canTransform(page: Page): boolean {
+    return page.layout === 'discovery-landing'
+  }
+
+  async transform(page: Page, pathname: string, context: Context): Promise<string> {
+    const templateData = await this.prepareTemplateData(page, pathname, context)
+
+    const templateContent = loadTemplate(this.templateName)
+
+    const rendered = await renderContent(templateContent, {
+      ...context,
+      ...templateData,
+      markdownRequested: true,
+    })
+
+    return rendered
+  }
+
+  private async prepareTemplateData(
+    page: Page,
+    _pathname: string,
+    context: Context,
+  ): Promise<TemplateData> {
+    const discoveryPage = page as DiscoveryPage
+    const sections: Section[] = []
+
+    // Recommended carousel
+    const recommended = discoveryPage.recommended ?? discoveryPage.rawRecommended
+    if (recommended && recommended.length > 0) {
+      const { default: getLearningTrackLinkData } = await import(
+        '@/learning-track/lib/get-link-data'
+      )
+
+      let links: LinkData[]
+      if (typeof recommended[0] === 'object' && 'title' in recommended[0]) {
+        links = recommended.map((item) => ({
+          href: typeof item === 'string' ? item : item.href,
+          title: (typeof item === 'object' && item.title) || '',
+          intro: (typeof item === 'object' && item.intro) || '',
+        }))
+      } else {
+        const linkData = await getLearningTrackLinkData(recommended as string[], context, {
+          title: true,
+          intro: true,
+        })
+        links = (linkData || []).map((item: { href: string; title?: string; intro?: string }) => ({
+          href: item.href,
+          title: item.title || '',
+          intro: item.intro || '',
+        }))
+      }
+
+      const validLinks = links.filter((l) => l.href && l.title)
+      if (validLinks.length > 0) {
+        sections.push({
+          title: 'Recommended',
+          groups: [{ title: null, links: validLinks }],
+        })
+      }
+    }
+
+    // Intro links (getting started)
+    const rawIntroLinks = discoveryPage.introLinks ?? discoveryPage.rawIntroLinks
+    if (rawIntroLinks) {
+      const { default: getLearningTrackLinkData } = await import(
+        '@/learning-track/lib/get-link-data'
+      )
+      const links = await Promise.all(
+        Object.values(rawIntroLinks).map(async (href): Promise<LinkData> => {
+          if (typeof href === 'string') {
+            const linkData = await getLearningTrackLinkData(href, context)
+            if (Array.isArray(linkData) && linkData.length > 0) {
+              const item = linkData[0]
+              return { href: item.href || '', title: item.title || '', intro: item.intro || '' }
+            } else if (
+              linkData &&
+              typeof linkData === 'object' &&
+              !Array.isArray(linkData) &&
+              'href' in linkData
+            ) {
+              const item = linkData as { href?: string; title?: string; intro?: string }
+              return {
+                href: item.href || '',
+                title: item.title || '',
+                intro: item.intro || '',
+              }
+            }
+          }
+          return { href: '', title: '' }
+        }),
+      )
+      const validLinks = links.filter((l) => l.href)
+      if (validLinks.length > 0) {
+        sections.push({
+          title: 'Links',
+          groups: [{ title: 'Getting started', links: validLinks }],
+        })
+      }
+    }
+
+    // Articles section: recursively gather ALL descendant articles
+    // This matches the behavior of the site which uses genericTocFlat/genericTocNested
+    if (discoveryPage.children && discoveryPage.children.length > 0) {
+      const tocItems = await getAllTocItems(page, context, {
+        recurse: true,
+        renderIntros: true,
+      })
+
+      // Flatten to get all leaf articles (excludeParents: true means only get articles, not category pages)
+      let allArticles = flattenTocItems(tocItems, { excludeParents: true })
+
+      // Apply includedCategories filter if specified
+      if (discoveryPage.includedCategories && discoveryPage.includedCategories.length > 0) {
+        const includedCategories = discoveryPage.includedCategories.map((c) => c.toLowerCase())
+        // Filter tocItems before flattening to preserve category info
+        const filterByCategory = (items: typeof tocItems): typeof tocItems => {
+          return items.filter((item) => {
+            const itemCategories = (item.category || []).map((c: string) => c.toLowerCase())
+            return itemCategories.some((cat) => includedCategories.includes(cat))
+          })
+        }
+
+        // Re-flatten with category filtering
+        const filteredTocItems = filterByCategory(flattenTocItemsWithCategory(tocItems))
+        allArticles = filteredTocItems.map((item) => ({
+          href: item.href,
+          title: item.title,
+          intro: item.intro,
+        }))
+      }
+
+      if (allArticles.length > 0) {
+        sections.push({
+          title: 'Articles',
+          groups: [{ title: null, links: allArticles }],
+        })
+      }
+    }
+
+    const intro = page.intro ? await page.renderProp('intro', context, { textOnly: true }) : ''
+    const title = await page.renderTitle(context, { unwrap: true })
+
+    return {
+      title,
+      intro,
+      sections,
+    }
+  }
+}
+
+/**
+ * Helper to flatten TOC items while preserving category info for filtering
+ */
+interface TocItemWithCategory {
+  href: string
+  title: string
+  intro?: string
+  category?: string[]
+  childTocItems?: TocItemWithCategory[]
+}
+
+function flattenTocItemsWithCategory(tocItems: TocItemWithCategory[]): TocItemWithCategory[] {
+  const result: TocItemWithCategory[] = []
+
+  function recurse(items: TocItemWithCategory[]) {
+    for (const item of items) {
+      const hasChildren = item.childTocItems && item.childTocItems.length > 0
+
+      // Only include leaf nodes (articles, not category pages)
+      if (!hasChildren) {
+        result.push(item)
+      }
+
+      if (hasChildren) {
+        recurse(item.childTocItems!)
+      }
+    }
+  }
+
+  recurse(tocItems)
+  return result
+}
diff --git a/src/article-api/transformers/index.ts b/src/article-api/transformers/index.ts
