feat: add bespoke landing transformer for Article API (#59079)

Author: heiskr

src/article-api/tests/bespoke-landing-transformer.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from 'vitest'
+
+import { get } from '@/tests/helpers/e2etest'
+
+const makeURL = (pathname: string): string =>
+  `/api/article/body?${new URLSearchParams({ pathname })}`
+
+describe('bespoke landing transformer', () => {
+  test('renders a bespoke landing page with all sections', async () => {
+    // /en/get-started/article-grid-bespoke is a bespoke landing page
+    const res = await get(makeURL('/en/get-started/article-grid-bespoke'))
+    expect(res.statusCode).toBe(200)
+    expect(res.headers['content-type']).toContain('text/markdown')
+
+    // Check for title
+    expect(res.body).toContain('# Article Grid Bespoke Landing')
+
+    // Should have intro
+    expect(res.body).toContain('A test page for testing')
+  })
+
+  test('renders all descendant articles recursively', async () => {
+    const res = await get(makeURL('/en/get-started/article-grid-bespoke'))
+    expect(res.statusCode).toBe(200)
+
+    // 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]')
+  })
+})

src/article-api/transformers/bespoke-landing-transformer.ts

@@ -0,0 +1,121 @@
+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 BespokeLandingPage extends Omit<Page, 'featuredLinks'> {
+  featuredLinks?: Record<string, Array<string | { href: string; title: string; intro?: string }>>
+  children?: string[]
+  recommended?: RecommendedItem[]
+  rawRecommended?: string[]
+  includedCategories?: string[]
+}
+
+/**
+ * Transforms bespoke-landing pages into markdown format.
+ * Handles recommended carousel and full article listings.
+ * Note: Unlike discovery-landing, bespoke-landing shows ALL articles
+ * regardless of includedCategories.
+ */
+export class BespokeLandingTransformer implements PageTransformer {
+  templateName = 'landing-page.template.md'
+
+  canTransform(page: Page): boolean {
+    return page.layout === 'bespoke-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 bespokePage = page as BespokeLandingPage
+    const sections: Section[] = []
+
+    // Recommended carousel
+    const recommended = bespokePage.recommended ?? bespokePage.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 }],
+        })
+      }
+    }
+
+    // Articles section: recursively gather ALL descendant articles
+    // This matches the behavior of the site which uses genericTocFlat/genericTocNested
+    // Note: For bespoke-landing pages, the site shows ALL articles regardless of includedCategories
+    // (includedCategories only filters for discovery-landing pages)
+    if (bespokePage.children && bespokePage.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)
+      const allArticles = flattenTocItems(tocItems, { excludeParents: true })
+
+      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,
+    }
+  }
+}

src/article-api/transformers/index.ts

@@ -7,6 +7,7 @@ import { GraphQLTransformer } from './graphql-transformer'
 import { GithubAppsTransformer } from './github-apps-transformer'
 import { WebhooksTransformer } from './webhooks-transformer'
 import { TocTransformer } from './toc-transformer'
+import { BespokeLandingTransformer } from './bespoke-landing-transformer'
 import { JourneyLandingTransformer } from './journey-landing-transformer'
 import { CategoryLandingTransformer } from './category-landing-transformer'
 import { DiscoveryLandingTransformer } from './discovery-landing-transformer'
@@ -27,6 +28,7 @@ transformerRegistry.register(new GraphQLTransformer())
 transformerRegistry.register(new GithubAppsTransformer())
 transformerRegistry.register(new WebhooksTransformer())
 transformerRegistry.register(new TocTransformer())
+transformerRegistry.register(new BespokeLandingTransformer())
 transformerRegistry.register(new JourneyLandingTransformer())
 transformerRegistry.register(new CategoryLandingTransformer())
 transformerRegistry.register(new DiscoveryLandingTransformer())