Fix article API 30s+ hangs on discovery-landing pages (#60416)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: heiskr

src/article-api/lib/get-all-toc-items.ts

@@ -1,5 +1,6 @@
 import type { Context, Page } from '@/types'
 import type { LinkData } from '@/article-api/transformers/types'
+import { renderLiquid } from '@/content-render/liquid/index'
 import { resolvePath } from './resolve-path'
 
 interface PageWithChildren extends Page {
@@ -28,9 +29,16 @@ export async function getAllTocItems(
   options: {
     recurse?: boolean
     renderIntros?: boolean
+    /** Use Liquid-only rendering for titles and intros instead of the full
+     *  Markdown/unified pipeline. Resolves {% data %} variables without
+     *  the cost of Markdown parsing, unified processing, and Cheerio unwrap. */
+    liquidOnly?: boolean
+    /** Only recurse into children whose resolved path starts with this prefix.
+     *  Prevents cross-product traversal (e.g. /en/rest listing /enterprise-admin). */
+    basePath?: string
   } = {},
 ): Promise<TocItem[]> {
-  const { recurse = true, renderIntros = true } = options
+  const { recurse = true, renderIntros = true, liquidOnly = false } = options
   const pageWithChildren = page as PageWithChildren
   const languageCode = page.languageCode || 'en'
 
@@ -44,43 +52,69 @@ export async function getAllTocItems(
   )
   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,
+  // On the first call, set basePath to this page's path so recursion
+  // stays within the same product section.
+  const basePath = options.basePath ?? pathname
+
+  const resolvedChildren = pageWithChildren.children
+    .map((childHref) => ({
+      childHref,
+      childPage: resolvePath(childHref, languageCode, pathname, context) as
+        | PageWithChildren
+        | undefined,
+    }))
+    .filter(
+      (entry): entry is { childHref: string; childPage: PageWithChildren } =>
+        entry.childPage !== undefined,
     )
-    const href = childPermalink ? childPermalink.href : childHref
 
-    const category = childPage.category || []
+  const items = await Promise.all(
+    resolvedChildren.map(async ({ childHref, childPage }) => {
+      const childPermalink = childPage.permalinks.find(
+        (p) => p.languageCode === languageCode && p.pageVersion === context.currentVersion,
+      )
+      const href = childPermalink ? childPermalink.href : childHref
+
+      let title: string
+      if (liquidOnly) {
+        const raw = childPage.shortTitle || childPage.title
+        try {
+          title = await renderLiquid(raw, context)
+        } catch {
+          // Fall back to raw frontmatter string if Liquid rendering fails
+          // (e.g. translation errors in non-English pages)
+          title = raw
+        }
+      } else {
+        title = await childPage.renderTitle(context, { unwrap: true })
+      }
 
-    const item: TocItem = {
-      href,
-      title,
-      intro,
-      category,
-      childTocItems: [],
-    }
+      let intro = ''
+      if (renderIntros && childPage.intro) {
+        if (liquidOnly) {
+          const rawIntro = childPage.rawIntro || childPage.intro
+          try {
+            intro = await renderLiquid(rawIntro, context)
+          } catch {
+            intro = rawIntro
+          }
+        } else {
+          intro = await childPage.renderProp('intro', context, { textOnly: true })
+        }
+      }
 
-    // Recursively get children if enabled
-    if (recurse && childPage.children && childPage.children.length > 0) {
-      item.childTocItems = await getAllTocItems(childPage, context, options)
-    }
+      const category = childPage.category || []
 
-    items.push(item)
-  }
+      // Only recurse if the child is within the same product section
+      const withinSection = href.startsWith(basePath)
+      const childTocItems =
+        recurse && withinSection && childPage.children && childPage.children.length > 0
+          ? await getAllTocItems(childPage, context, { ...options, basePath })
+          : []
+
+      return { href, title, intro, category, childTocItems } as TocItem
+    }),
+  )
 
   return items
 }

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

@@ -51,4 +51,39 @@ describe('discovery landing transformer', () => {
     // Should have at least one section
     expect(res.body).toContain('##')
   })
+
+  test('articles include intros rendered with Liquid', async () => {
+    const res = await get(makeURL('/en/get-started/article-grid-discovery'))
+    expect(res.statusCode).toBe(200)
+
+    // Articles should have intros (Liquid-rendered from frontmatter)
+    expect(res.body).toContain('This is the first test article for the article grid component.')
+    expect(res.body).toContain('This is the fourth test article for the article grid component.')
+  })
+
+  test('filters articles by includedCategories', async () => {
+    const res = await get(makeURL('/en/get-started/discovery-filtered'))
+    expect(res.statusCode).toBe(200)
+
+    // "Included Article" has category "Getting started" and should appear
+    expect(res.body).toContain('[Included Article]')
+
+    // "Excluded Article" has category "Advanced" and should be filtered out
+    expect(res.body).not.toContain('[Excluded Article]')
+  })
+
+  test('recursive articles stay within product section (basePath guard)', async () => {
+    const res = await get(makeURL('/en/get-started/article-grid-discovery'))
+    expect(res.statusCode).toBe(200)
+
+    // All four articles from both categories should appear
+    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]')
+
+    // Category pages themselves should NOT appear (excludeParents: true)
+    expect(res.body).not.toContain('[Grid Category One]')
+    expect(res.body).not.toContain('[Grid Category Two]')
+  })
 })

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

@@ -129,12 +129,17 @@ export class DiscoveryLandingTransformer implements PageTransformer {
       }
     }
 
-    // Articles section: recursively gather ALL descendant articles
-    // This matches the behavior of the site which uses genericTocFlat/genericTocNested
+    // Articles section: recursively gather descendant articles within
+    // this product section. Uses Liquid-only rendering for titles and intros
+    // instead of the full Markdown/unified pipeline, which would take 30s+
+    // for large sections like /rest (297 descendants × 2 renderContent calls).
+    // The basePath guard prevents cross-product recursion (e.g. /rest listing
+    // /enterprise-admin children that point outside the /rest hierarchy).
     if (discoveryPage.children && discoveryPage.children.length > 0) {
       const tocItems = await getAllTocItems(page, context, {
         recurse: true,
         renderIntros: true,
+        liquidOnly: true,
       })
 
       // Flatten to get all leaf articles (excludeParents: true means only get articles, not category pages)
@@ -143,21 +148,31 @@ export class DiscoveryLandingTransformer implements PageTransformer {
       // 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))
-          })
+
+        // Build a map of href → category from the full tree
+        const categoryMap = new Map<string, string[]>()
+        interface TocNode {
+          href: string
+          category?: string[]
+          childTocItems?: TocNode[]
+        }
+        function collectCategories(items: TocNode[]) {
+          for (const item of items) {
+            if (item.category && item.category.length > 0) {
+              categoryMap.set(item.href, item.category)
+            }
+            if (item.childTocItems) collectCategories(item.childTocItems)
+          }
         }
+        collectCategories(tocItems)
 
-        // Re-flatten with category filtering
-        const filteredTocItems = filterByCategory(flattenTocItemsWithCategory(tocItems))
-        allArticles = filteredTocItems.map((item) => ({
-          href: item.href,
-          title: item.title,
-          intro: item.intro,
-        }))
+        allArticles = allArticles.filter((item) => {
+          const itemCategories = (categoryMap.get(item.href) || []).map((c) => c.toLowerCase())
+          return (
+            itemCategories.length === 0 ||
+            itemCategories.some((cat) => includedCategories.includes(cat))
+          )
+        })
       }
 
       if (allArticles.length > 0) {
@@ -178,36 +193,3 @@ export class DiscoveryLandingTransformer implements PageTransformer {
     }
   }
 }
-
-/**
- * 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
-}

src/fixtures/fixtures/content/get-started/discovery-filtered/filtered-category/excluded-article.md

@@ -0,0 +1,13 @@
+---
+title: Excluded Article
+intro: "This article has the Advanced category and should be excluded."
+versions:
+  fpt: "*"
+  ghes: "*"
+  ghec: "*"
+category:
+  - Advanced
+layout: inline
+---
+
+This article should not appear when filtering by Getting started.

src/fixtures/fixtures/content/get-started/discovery-filtered/filtered-category/included-article.md

@@ -0,0 +1,13 @@
+---
+title: Included Article
+intro: "This article has the Getting started category and should be included."
+versions:
+  fpt: "*"
+  ghes: "*"
+  ghec: "*"
+category:
+  - Getting started
+layout: inline
+---
+
+This article should appear when filtering by Getting started.

src/fixtures/fixtures/content/get-started/discovery-filtered/filtered-category/index.md

@@ -0,0 +1,11 @@
+---
+title: Filtered Category
+intro: "A test category for filtering."
+versions:
+  fpt: "*"
+  ghes: "*"
+  ghec: "*"
+children:
+  - /included-article
+  - /excluded-article
+---

src/fixtures/fixtures/content/get-started/discovery-filtered/index.md

@@ -0,0 +1,15 @@
+---
+title: Discovery Filtered
+intro: "A test page for discovery landing with includedCategories filtering."
+versions:
+  fpt: "*"
+  ghes: "*"
+  ghec: "*"
+layout: discovery-landing
+includedCategories:
+  - Getting started
+children:
+  - /filtered-category
+---
+
+This page tests includedCategories filtering on discovery landing pages.

src/fixtures/fixtures/content/get-started/index.md

@@ -47,6 +47,7 @@ children:
   - /article-grid-bespoke
   - /multi-carousel
   - /non-child-resolution
+  - /discovery-filtered
 communityRedirect:
   name: Provide HubGit Feedback
   href: 'https://hubgit.com/orgs/community/discussions/categories/get-started'