refactor: parallelize docs rendering and Shiki setup

- Render doc sections, symbols, markdown blocks, and examples concurrently
- Cache in-flight Shiki highlighter initialization to avoid duplicate work
- Add ordering tests for parallel docs rendering

Author: trivikr

server/utils/docs/render.ts

@@ -57,16 +57,14 @@ export async function renderDocNodes(
   symbolLookup: SymbolLookup,
 ): Promise<string> {
   const grouped = groupMergedByKind(symbols)
-  const sections: string[] = []
-
-  for (const kind of KIND_DISPLAY_ORDER) {
+  const sectionPromises = KIND_DISPLAY_ORDER.map(async kind => {
     const kindSymbols = grouped[kind]
-    if (!kindSymbols || kindSymbols.length === 0) continue
+    if (!kindSymbols || kindSymbols.length === 0) return ''
+    return renderKindSection(kind, kindSymbols, symbolLookup)
+  })
 
-    sections.push(await renderKindSection(kind, kindSymbols, symbolLookup))
-  }
-
-  return sections.join('\n')
+  const sections = await Promise.all(sectionPromises)
+  return sections.filter(Boolean).join('\n')
 }
 
 /**
@@ -79,13 +77,13 @@ async function renderKindSection(
 ): Promise<string> {
   const title = KIND_TITLES[kind] || kind
   const lines: string[] = []
+  const renderedSymbols = await Promise.all(
+    symbols.map(symbol => renderMergedSymbol(symbol, symbolLookup)),
+  )
 
   lines.push(`<section class="docs-section" id="section-${kind}">`)
   lines.push(`<h2 class="docs-section-title">${title}</h2>`)
-
-  for (const symbol of symbols) {
-    lines.push(await renderMergedSymbol(symbol, symbolLookup))
-  }
+  lines.push(...renderedSymbols)
 
   lines.push(`</section>`)
 
@@ -129,9 +127,21 @@ async function renderMergedSymbol(
     .map(n => getNodeSignature(n))
     .filter(Boolean) as string[]
 
+  const description = symbol.jsDoc?.doc?.trim()
+  const signaturePromise =
+    signatures.length > 0 ? highlightCodeBlock(signatures.join('\n'), 'typescript') : null
+  const descriptionPromise = description ? renderMarkdown(description, symbolLookup) : null
+  const jsDocTagsPromise =
+    symbol.jsDoc?.tags && symbol.jsDoc.tags.length > 0
+      ? renderJsDocTags(symbol.jsDoc.tags, symbolLookup)
+      : null
+  const [highlightedSignature, renderedDescription, renderedJsDocTags] = await Promise.all([
+    signaturePromise,
+    descriptionPromise,
+    jsDocTagsPromise,
+  ])
+
   if (signatures.length > 0) {
-    const signatureCode = signatures.join('\n')
-    const highlightedSignature = await highlightCodeBlock(signatureCode, 'typescript')
     lines.push(`<div class="docs-signature">${highlightedSignature}</div>`)
 
     if (symbol.nodes.length > MAX_OVERLOAD_SIGNATURES) {
@@ -141,16 +151,13 @@ async function renderMergedSymbol(
   }
 
   // Description
-  if (symbol.jsDoc?.doc) {
-    const description = symbol.jsDoc.doc.trim()
-    lines.push(
-      `<div class="docs-description">${await renderMarkdown(description, symbolLookup)}</div>`,
-    )
+  if (renderedDescription) {
+    lines.push(`<div class="docs-description">${renderedDescription}</div>`)
   }
 
   // JSDoc tags
-  if (symbol.jsDoc?.tags && symbol.jsDoc.tags.length > 0) {
-    lines.push(await renderJsDocTags(symbol.jsDoc.tags, symbolLookup))
+  if (renderedJsDocTags) {
+    lines.push(renderedJsDocTags)
   }
 
   // Type-specific members
@@ -178,16 +185,29 @@ async function renderJsDocTags(tags: JsDocTag[], symbolLookup: SymbolLookup): Pr
   const examples = tags.filter(t => t.kind === 'example')
   const deprecated = tags.find(t => t.kind === 'deprecated')
   const see = tags.filter(t => t.kind === 'see')
+  const deprecatedMessagePromise = deprecated?.doc
+    ? renderMarkdown(deprecated.doc.replace(/\n/g, ' '), symbolLookup)
+    : null
+  const examplePromises = examples.map(async example => {
+    if (!example.doc) return ''
+    const langMatch = example.doc.match(/```(\w+)?/)
+    const lang = langMatch?.[1] || 'typescript'
+    const code = example.doc.replace(/```\w*\n?/g, '').trim()
+    return highlightCodeBlock(code, lang)
+  })
+  const [renderedDeprecatedMessage, renderedExamples] = await Promise.all([
+    deprecatedMessagePromise,
+    Promise.all(examplePromises),
+  ])
 
   // Deprecated warning
   if (deprecated) {
     lines.push(`<div class="docs-deprecated">`)
     lines.push(`<strong>Deprecated</strong>`)
-    if (deprecated.doc) {
+    if (renderedDeprecatedMessage) {
       // We remove new lines because they look weird when rendered into the deprecated block
       // I think markdown is actually supposed to collapse single new lines automatically but this function doesn't do that so if that changes remove this
-      const renderedMessage = await renderMarkdown(deprecated.doc.replace(/\n/g, ' '), symbolLookup)
-      lines.push(`<div class="docs-deprecated-message">${renderedMessage}</div>`)
+      lines.push(`<div class="docs-deprecated-message">${renderedDeprecatedMessage}</div>`)
     }
     lines.push(`</div>`)
   }
@@ -221,15 +241,7 @@ async function renderJsDocTags(tags: JsDocTag[], symbolLookup: SymbolLookup): Pr
   if (examples.length > 0) {
     lines.push(`<div class="docs-examples">`)
     lines.push(`<h4>Example${examples.length > 1 ? 's' : ''}</h4>`)
-    for (const example of examples) {
-      if (example.doc) {
-        const langMatch = example.doc.match(/```(\w+)?/)
-        const lang = langMatch?.[1] || 'typescript'
-        const code = example.doc.replace(/```\w*\n?/g, '').trim()
-        const highlighted = await highlightCodeBlock(code, lang)
-        lines.push(highlighted)
-      }
-    }
+    lines.push(...renderedExamples.filter(Boolean))
     lines.push(`</div>`)
   }
 

server/utils/docs/text.ts

@@ -131,9 +131,12 @@ export async function renderMarkdown(text: string, symbolLookup: SymbolLookup):
     .replace(/\n/g, '<br>')
 
   // Highlight and restore code blocks
-  for (let i = 0; i < codeBlockData.length; i++) {
-    const { lang, code } = codeBlockData[i]!
-    const highlighted = await highlightCodeBlock(code, lang)
+  const highlightedCodeBlocks = await Promise.all(
+    codeBlockData.map(({ lang, code }) => highlightCodeBlock(code, lang)),
+  )
+
+  for (let i = 0; i < highlightedCodeBlocks.length; i++) {
+    const highlighted = highlightedCodeBlocks[i]!
     result = result.replace(`__CODE_BLOCK_${i}__`, highlighted)
   }
 

server/utils/shiki.ts

@@ -3,6 +3,7 @@ import { createHighlighterCore, type HighlighterCore } from 'shiki/core'
 import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
 
 let highlighter: HighlighterCore | null = null
+let highlighterPromise: Promise<HighlighterCore> | null = null
 
 function replaceThemeColors(
   theme: ThemeRegistration,
@@ -18,8 +19,12 @@ function replaceThemeColors(
 }
 
 export async function getShikiHighlighter(): Promise<HighlighterCore> {
-  if (!highlighter) {
-    highlighter = await createHighlighterCore({
+  if (highlighter) {
+    return highlighter
+  }
+
+  if (!highlighterPromise) {
+    highlighterPromise = createHighlighterCore({
       themes: [
         import('@shikijs/themes/github-dark'),
         import('@shikijs/themes/github-light').then(t =>
@@ -75,8 +80,17 @@ export async function getShikiHighlighter(): Promise<HighlighterCore> {
       },
       engine: createJavaScriptRegexEngine(),
     })
+      .then(createdHighlighter => {
+        highlighter = createdHighlighter
+        return createdHighlighter
+      })
+      .catch(error => {
+        highlighterPromise = null
+        throw error
+      })
   }
-  return highlighter
+
+  return highlighterPromise
 }
 
 /**

test/unit/server/utils/docs/render.spec.ts

@@ -21,6 +21,37 @@ function createClassSymbol(classDef: DenoDocNode['classDef']): MergedSymbol {
   }
 }
 
+function createFunctionSymbol(name: string): MergedSymbol {
+  const node: DenoDocNode = {
+    name,
+    kind: 'function',
+    functionDef: {
+      params: [],
+      returnType: { repr: 'void', kind: 'keyword', keyword: 'void' },
+    },
+  }
+
+  return {
+    name,
+    kind: 'function',
+    nodes: [node],
+  }
+}
+
+function createInterfaceSymbol(name: string): MergedSymbol {
+  const node: DenoDocNode = {
+    name,
+    kind: 'interface',
+    interfaceDef: {},
+  }
+
+  return {
+    name,
+    kind: 'interface',
+    nodes: [node],
+  }
+}
+
 describe('issue #1943 - class getters separated from methods', () => {
   it('renders getters under a "Getters" heading, not "Methods"', async () => {
     const symbol = createClassSymbol({
@@ -131,3 +162,33 @@ describe('issue #1943 - class getters separated from methods', () => {
     expect(html).toContain('static get instance')
   })
 })
+
+describe('renderDocNodes ordering', () => {
+  it('preserves kind display order while rendering sections in parallel', async () => {
+    const html = await renderDocNodes(
+      [createInterfaceSymbol('Config'), createFunctionSymbol('run')],
+      new Map(),
+    )
+
+    const functionsIndex = html.indexOf('id="section-function"')
+    const interfacesIndex = html.indexOf('id="section-interface"')
+
+    expect(functionsIndex).toBeGreaterThanOrEqual(0)
+    expect(interfacesIndex).toBeGreaterThanOrEqual(0)
+    expect(functionsIndex).toBeLessThan(interfacesIndex)
+  })
+
+  it('preserves symbol order within a section while rendering symbols in parallel', async () => {
+    const html = await renderDocNodes(
+      [createFunctionSymbol('alpha'), createFunctionSymbol('beta')],
+      new Map(),
+    )
+
+    const alphaIndex = html.indexOf('id="function-alpha"')
+    const betaIndex = html.indexOf('id="function-beta"')
+
+    expect(alphaIndex).toBeGreaterThanOrEqual(0)
+    expect(betaIndex).toBeGreaterThanOrEqual(0)
+    expect(alphaIndex).toBeLessThan(betaIndex)
+  })
+})