Add per-language code tabs for SDK documentation (#61324)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Sarah Schneider <sarahs@users.noreply.github.com>

Author: 4 people

data/ui.yml

@@ -25,6 +25,9 @@ picker:
   product_picker_default_text: All products
   version_picker_default_text: Choose a version
 
+code_tabs:
+  aria_label: Code languages
+
 release_notes:
   banner_text: GitHub began rolling these changes out to enterprises on
 

src/code-tabs/lib/languages.ts

@@ -0,0 +1,11 @@
+export const codeLanguages: Record<string, string> = {
+  typescript: 'TypeScript',
+  python: 'Python',
+  go: 'Go',
+  csharp: 'C#',
+  java: 'Java',
+  ruby: 'Ruby',
+  shell: 'Shell',
+  javascript: 'JavaScript',
+  dotnet: '.NET',
+}

src/content-render/liquid/codetabs.ts

@@ -0,0 +1,127 @@
+import { encode } from 'html-entities'
+import { TokenizationError, type TagToken, type TopLevelToken } from 'liquidjs'
+
+import { codeLanguages } from '@/code-tabs/lib/languages'
+
+interface LiquidTemplate {
+  [key: string]: unknown
+}
+
+interface LiquidStream {
+  on(event: string, callback: (template?: LiquidTemplate) => void): LiquidStream
+  stop(): void
+  start(): void
+}
+
+interface LiquidEngine {
+  parser: {
+    parseStream(tokens: TopLevelToken[]): LiquidStream
+  }
+  renderer: {
+    renderTemplates(templates: LiquidTemplate[], scope: Record<string, unknown>): string
+  }
+  parseAndRender(template: string, context: Record<string, string>): string
+}
+
+interface LiquidBlockTag {
+  type: 'block'
+  templates: LiquidTemplate[]
+  liquid: LiquidEngine | null
+  parse(tagToken: TagToken, remainTokens: TopLevelToken[]): void
+  render(scope: Record<string, unknown>): Generator<unknown, unknown, unknown>
+}
+
+const codeTabsTemplate = '<div class="ghd-codetabs">{{ output }}</div>\n'
+const codeTabTemplate =
+  '<div class="ghd-codetab" data-lang="{{ languageKey }}" data-label="{{ label }}"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">{{ label }}</div>{{ output }}</div>\n'
+const codeTabSyntax = /^(?<key>[a-z0-9-]+)(?:\s+"(?<label>[^"]+)")?$/
+const codeTabSyntaxHelp =
+  'Syntax Error in tag \'codetab\' - Valid syntax: codetab <language-key> ["Label"]'
+
+export const tags = ['codetabs', 'codetab']
+
+function parseBlockTemplates(
+  context: LiquidBlockTag,
+  tagToken: TagToken,
+  remainTokens: TopLevelToken[],
+  endTagName: string,
+): void {
+  context.templates = []
+
+  const stream = context.liquid!.parser.parseStream(remainTokens)
+  stream
+    .on(`tag:${endTagName}`, () => stream.stop())
+    .on('template', (template?: LiquidTemplate) => {
+      if (template) context.templates.push(template)
+    })
+    .on('end', () => {
+      throw new Error(`tag ${tagToken.getText()} not closed`)
+    })
+  stream.start()
+}
+
+export const CodeTabs: LiquidBlockTag = {
+  type: 'block',
+  templates: [],
+  liquid: null,
+
+  parse(tagToken: TagToken, remainTokens: TopLevelToken[]): void {
+    if (tagToken.args.trim()) {
+      throw new TokenizationError(
+        "Syntax Error in tag 'codetabs' - This tag does not accept arguments",
+        tagToken,
+      )
+    }
+
+    parseBlockTemplates(this, tagToken, remainTokens, 'endcodetabs')
+  },
+
+  *render(scope: Record<string, unknown>): Generator<unknown, unknown, unknown> {
+    const output = yield this.liquid!.renderer.renderTemplates(this.templates, scope)
+    return yield this.liquid!.parseAndRender(codeTabsTemplate, { output })
+  },
+}
+
+interface CodeTabTag extends LiquidBlockTag {
+  languageKey: string
+  label: string
+}
+
+export const CodeTab: CodeTabTag = {
+  type: 'block',
+  templates: [],
+  liquid: null,
+  languageKey: '',
+  label: '',
+
+  parse(tagToken: TagToken, remainTokens: TopLevelToken[]): void {
+    const args = tagToken.args.trim()
+    const match = args.match(codeTabSyntax)
+
+    if (!match?.groups) {
+      throw new TokenizationError(codeTabSyntaxHelp, tagToken)
+    }
+
+    const { key, label } = match.groups
+    if (!Object.prototype.hasOwnProperty.call(codeLanguages, key)) {
+      throw new TokenizationError(
+        `Unknown codetab language '${key}'. Valid values: ${Object.keys(codeLanguages).join(', ')}`,
+        tagToken,
+      )
+    }
+
+    this.languageKey = encode(key)
+    this.label = encode(label || codeLanguages[key])
+
+    parseBlockTemplates(this, tagToken, remainTokens, 'endcodetab')
+  },
+
+  *render(scope: Record<string, unknown>): Generator<unknown, unknown, unknown> {
+    const output = yield this.liquid!.renderer.renderTemplates(this.templates, scope)
+    return yield this.liquid!.parseAndRender(codeTabTemplate, {
+      languageKey: this.languageKey,
+      label: this.label,
+      output,
+    })
+  },
+}

src/content-render/liquid/engine.ts

@@ -6,6 +6,7 @@ import Ifversion from './ifversion'
 import { Tool, tags as toolTags } from './tool'
 import { Spotlight, tags as spotlightTags } from './spotlight'
 import { Prompt } from './prompt'
+import { CodeTab, CodeTabs, tags as codeTabTags } from './codetabs'
 import IndentedDataReference from './indented-data-reference'
 
 type LiquidTagDef = Parameters<Liquid['registerTag']>[1]
@@ -15,6 +16,8 @@ const ifversionTag = Ifversion as unknown as LiquidTagDef
 const toolTag = Tool as unknown as LiquidTagDef
 const spotlightTag = Spotlight as unknown as LiquidTagDef
 const promptTag = Prompt as unknown as LiquidTagDef
+const codeTabsTag = CodeTabs as unknown as LiquidTagDef
+const codeTabTag = CodeTab as unknown as LiquidTagDef
 const indentedDataReferenceTag = IndentedDataReference as unknown as LiquidTagDef
 
 export const engine = new Liquid({
@@ -35,6 +38,10 @@ for (const tag in spotlightTags) {
   engine.registerTag(tag, spotlightTag)
 }
 
+for (const tag of codeTabTags) {
+  engine.registerTag(tag, tag === 'codetabs' ? codeTabsTag : codeTabTag)
+}
+
 engine.registerTag('prompt', promptTag)
 
 /**

src/events/lib/schema.ts

@@ -2,6 +2,7 @@ import { languageKeys } from '@/languages/lib/languages-server'
 import { allVersionKeys } from '@/versions/lib/all-versions'
 import { productIds } from '@/products/lib/all-products'
 import { allTools } from '@/tools/lib/all-tools'
+import { codeLanguages } from '@/code-tabs/lib/languages'
 import { contentTypesEnum } from '@/frame/lib/frontmatter'
 
 const versionPattern = '^\\d+(\\.\\d+)?(\\.\\d+)?$'
@@ -613,29 +614,34 @@ const preference = {
     },
     preference_name: {
       type: 'string',
-      enum: ['application', 'color_mode', 'os', 'code_display'],
-      description: 'The preference name, such as os, application, or color_mode',
+      enum: ['application', 'color_mode', 'os', 'code_display', 'code_language'],
+      description: 'The preference name, such as os, application, color_mode, or code_language',
     },
     preference_value: {
       type: 'string',
       enum: [
-        // application
-        ...Object.keys(allTools),
-        // color_mode
-        'dark',
-        'light',
-        'auto',
-        'auto:dark',
-        'auto:light',
-        // os
-        'linux',
-        'mac',
-        'windows',
-        // code_display
-        'beside',
-        'inline',
+        ...new Set([
+          // application
+          ...Object.keys(allTools),
+          // color_mode
+          'dark',
+          'light',
+          'auto',
+          'auto:dark',
+          'auto:light',
+          // os
+          'linux',
+          'mac',
+          'windows',
+          // code_display
+          'beside',
+          'inline',
+          // code_language (may overlap with allTools, e.g. 'javascript')
+          ...Object.keys(codeLanguages),
+        ]),
       ],
-      description: 'The application, color_mode, os, or code_display selected by the user.',
+      description:
+        'The application, color_mode, os, code_display, or code_language selected by the user.',
     },
   },
 }

src/fixtures/fixtures/content/get-started/liquid/code-tabs-test.md

@@ -0,0 +1,68 @@
+---
+title: Code tabs test
+versions:
+  fpt: "*"
+---
+
+## Basic code tabs
+
+{% codetabs %}
+{% codetab typescript %}
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+const session = await client.createSession({
+  model: "gpt-4.1",
+});
+```
+
+{% endcodetab %}
+{% codetab python %}
+
+```python
+from copilot import CopilotClient
+
+client = CopilotClient()
+await client.start()
+session = await client.create_session(model='gpt-4.1')
+```
+
+{% endcodetab %}
+{% codetab go %}
+
+```golang
+package main
+
+import copilot "github.com/github/copilot-sdk/go"
+
+func main() {
+    client := copilot.NewClient(nil)
+    client.Start(ctx)
+}
+```
+
+{% endcodetab %}
+{% endcodetabs %}
+
+## Synced language groups
+
+{% codetabs %}
+{% codetab python "Python" %}
+
+```python
+client = CopilotClient()
+await client.start()
+```
+
+{% endcodetab %}
+{% codetab typescript "TypeScript" %}
+
+```typescript
+const client = new CopilotClient();
+await client.start();
+```
+
+{% endcodetab %}
+{% endcodetabs %}

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

@@ -2,9 +2,9 @@
 title: Liquid tags
 intro: Testing various fancy Liquid rendering functionality
 versions:
-  fpt: '*'
-  ghes: '*'
-  ghec: '*'
+  fpt: "*"
+  ghes: "*"
+  ghec: "*"
 children:
   - /warnings
   - /danger
@@ -20,4 +20,5 @@ children:
   - /tool-platform-switcher
   - /tool-picker-issue
   - /data
+  - /code-tabs-test
 ---

src/fixtures/fixtures/data/ui.yml

@@ -25,6 +25,9 @@ picker:
   product_picker_default_text: All products
   version_picker_default_text: Choose a version
 
+code_tabs:
+  aria_label: Code languages
+
 release_notes:
   banner_text: GitHub began rolling these changes out to enterprises on
 

src/fixtures/tests/liquid.ts

@@ -66,6 +66,17 @@ describe('tool', () => {
   })
 })
 
+describe('codetabs', () => {
+  test('renders code tabs with language metadata', async () => {
+    const $: CheerioAPI = await getDOM('/get-started/liquid/code-tabs-test')
+
+    expect($('.ghd-codetabs').length).toBe(2)
+    expect($('.ghd-codetab[data-lang="typescript"][data-label="TypeScript"]').length).toBe(2)
+    expect($('.ghd-codetab[data-lang="python"][data-label="Python"]').length).toBe(2)
+    expect($('.ghd-codetab-fallback-label').first().text()).toBe('TypeScript')
+  })
+})
+
 describe('post', () => {
   test('whitespace control', async () => {
     const $: CheerioAPI = await getDOM('/get-started/liquid/whitespace')

src/fixtures/tests/playwright-rendering.spec.ts

@@ -310,6 +310,44 @@ test.describe('tool picker', () => {
   })
 })
 
+test.describe('code tabs', () => {
+  test('switch languages across groups', async ({ page }) => {
+    await page.goto('/get-started/liquid/code-tabs-test')
+    await turnOffExperimentsInPage(page)
+
+    const firstGroup = page.locator('.ghd-codetabs').nth(0)
+    const secondGroup = page.locator('.ghd-codetabs').nth(1)
+
+    await expect(firstGroup.getByRole('link', { name: 'TypeScript' })).toHaveAttribute(
+      'aria-current',
+      'page',
+    )
+    await firstGroup.getByRole('link', { name: 'Python' }).click()
+
+    await expect(firstGroup.getByRole('link', { name: 'Python' })).toHaveAttribute(
+      'aria-current',
+      'page',
+    )
+    await expect(secondGroup.getByRole('link', { name: 'Python' })).toHaveAttribute(
+      'aria-current',
+      'page',
+    )
+    await expect(firstGroup.getByText('from copilot import CopilotClient')).toBeVisible()
+    await expect(firstGroup.getByText('@github/copilot-sdk')).not.toBeVisible()
+  })
+
+  test('remembers the last selected language', async ({ page }) => {
+    await page.goto('/get-started/liquid/code-tabs-test')
+    await turnOffExperimentsInPage(page)
+    await page.locator('.ghd-codetabs').nth(0).getByRole('link', { name: 'Python' }).click()
+
+    await page.goto('/get-started/liquid/code-tabs-test')
+    await expect(
+      page.locator('.ghd-codetabs').nth(0).getByRole('link', { name: 'Python' }),
+    ).toHaveAttribute('aria-current', 'page')
+  })
+})
+
 test('navigate with side bar into article inside a subcategory inside a category', async ({
   page,
 }) => {