Support AUTOTITLE in code annotation blocks (#56214)

Author: heiskr

src/content-render/tests/__snapshots__/annotate.js.snap

@@ -18,12 +18,50 @@ on:
 
 describe('annotate', () => {
   test('renders annotations', async () => {
-    // We don't normally use snapshots,
-    // but in this case its a short and concise example
-    // that won't change regularly.
-    // If it fails, study the output and make sure it's correct.
-    // If it is indeed correct, run `vitest --updateSnapshot` to update it.
-    expect(await renderContent(example)).toMatchSnapshot()
+    const res = await renderContent(example)
+    const $ = cheerio.load(res)
+
+    // Check that the annotation structure is rendered correctly
+    const annotation = $('.annotate')
+    expect(annotation.length).toBe(1)
+    expect(annotation.hasClass('beside')).toBe(true)
+
+    // Check annotation header exists
+    const header = $('.annotate-header')
+    expect(header.length).toBe(1)
+
+    // Check both beside and inline modes are rendered
+    const beside = $('.annotate-beside')
+    const inline = $('.annotate-inline')
+    expect(beside.length).toBe(1)
+    expect(inline.length).toBe(1)
+
+    // Check that we have the correct number of annotation rows
+    const rows = $('.annotate-row')
+    expect(rows.length).toBe(2)
+
+    // Check that each row has both code and note sections
+    rows.each((i, row) => {
+      const $row = $(row)
+      expect($row.find('.annotate-code').length).toBe(1)
+      expect($row.find('.annotate-note').length).toBe(1)
+    })
+
+    // Check specific content of the annotations
+    const notes = $('.annotate-note p')
+    const noteTexts = notes.map((i, el) => $(el).text()).get()
+    expect(noteTexts).toEqual([
+      'The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.',
+      'Add the pull_request event, so that the workflow runs automatically\nevery time a pull request is created.',
+    ])
+
+    // Check code content
+    const codes = $('.annotate-code pre')
+    const codeTexts = codes.map((i, el) => $(el).text()).get()
+    expect(codeTexts).toEqual([
+      'name: Post welcome comment',
+      'on:\n  pull_request:\n    types: [opened]',
+    ])
   })
 
   test('renders bash with hash bang annotations', async () => {
@@ -63,6 +101,7 @@ on:
 
 \`\`\`
 `.trim()
+
     const res = await renderContent(example)
     const $ = cheerio.load(res)
 
@@ -79,4 +118,50 @@ on:
       "on:\n  push:\n    branches: ['release']",
     ])
   })
+
+  test('supports AUTOTITLE links in annotations', async () => {
+    const example = `
+\`\`\`yaml annotate copy
+# For more information about workflow syntax, see [AUTOTITLE](/get-started/start-your-journey/hello-world).
+name: Test workflow
+
+# This uses the checkout action. See [AUTOTITLE](/get-started/foo) for details.
+on: [push]
+\`\`\`
+`
+
+    // Create a mock context with pages for AUTOTITLE resolution
+    const mockPages = {
+      '/get-started/start-your-journey/hello-world': {
+        href: '/get-started/start-your-journey/hello-world',
+        rawTitle: 'Hello World',
+      },
+      '/get-started/foo': {
+        href: '/get-started/foo',
+        rawTitle: 'Fooing Around',
+      },
+    }
+
+    const mockContext = {
+      currentLanguage: 'en',
+      currentVersion: 'free-pro-team@latest',
+      pages: mockPages,
+      redirects: {},
+    }
+
+    const res = await renderContent(example, mockContext)
+    const $ = cheerio.load(res)
+
+    const rows = $('.annotate-row')
+    const notes = $('.annotate-note', rows)
+
+    // Check that AUTOTITLE links were resolved to actual titles
+    const firstNote = notes.eq(0).html()
+    const secondNote = notes.eq(1).html()
+
+    expect(firstNote).toContain('Hello World')
+    expect(firstNote).not.toContain('[AUTOTITLE]')
+    expect(secondNote).toContain('Fooing Around')
+    expect(secondNote).not.toContain('[AUTOTITLE]')
+  })
 })

src/content-render/tests/annotate.js

@@ -36,6 +36,7 @@ import { h } from 'hastscript'
 import { fromMarkdown } from 'mdast-util-from-markdown'
 import { toHast } from 'mdast-util-to-hast'
 import { header } from './code-header.js'
+import findPage from '#src/frame/lib/find-page.js'
 
 const languages = yaml.load(fs.readFileSync('./data/code-languages.yml', 'utf8'))
 
@@ -66,15 +67,15 @@ const commentRegexes = {
 const matcher = (node) =>
   node.type === 'element' && node.tagName === 'pre' && getPreMeta(node).annotate
 
-export default function annotate() {
+export default function annotate(context) {
   return (tree) => {
     visit(tree, matcher, (node, index, parent) => {
-      parent.children[index] = createAnnotatedNode(node)
+      parent.children[index] = createAnnotatedNode(node, context)
     })
   }
 }
 
-function createAnnotatedNode(node) {
+function createAnnotatedNode(node, context) {
   const lang = node.children[0].properties.className[0].replace('language-', '')
   const code = node.children[0].children[0].value
 
@@ -98,7 +99,7 @@ function createAnnotatedNode(node) {
   }
 
   // Render the HTML
-  return template({ lang, code, rows })
+  return template({ lang, code, rows, context })
 }
 
 function validate(lang, code) {
@@ -178,7 +179,7 @@ function getSubnav() {
   return h('div', { className: 'annotate-toggle' }, [besideBtn, inlineBtn])
 }
 
-function template({ lang, code, rows }) {
+function template({ lang, code, rows, context }) {
   return h(
     'div',
     { class: 'annotate beside' },
@@ -197,7 +198,7 @@ function template({ lang, code, rows }) {
           h(
             'div',
             { className: 'annotate-note' },
-            mdToHast(note.map(removeComment(lang)).join('\n')),
+            mdToHast(note.map(removeComment(lang)).join('\n'), context),
           ),
         ]),
       ),
@@ -209,8 +210,39 @@ function template({ lang, code, rows }) {
   )
 }
 
-function mdToHast(text) {
-  return toHast(fromMarkdown(text))
+function mdToHast(text, context) {
+  const mdast = fromMarkdown(text)
+
+  // Process AUTOTITLE links if context is available
+  if (context) {
+    processAutotitleInMdast(mdast, context)
+  }
+
+  return toHast(mdast)
+}
+
+// Helper method to process AUTOTITLE links in MDAST
+// This can be reused for other MDAST processing that needs AUTOTITLE support
+function processAutotitleInMdast(mdast, context) {
+  visit(mdast, 'link', (node) => {
+    if (node.url && node.url.startsWith('/')) {
+      for (const child of node.children) {
+        if (child.type === 'text' && /^\s*AUTOTITLE\s*$/.test(child.value)) {
+          // Find the page and get its title
+          const page = findPage(node.url, context.pages, context.redirects)
+          if (page) {
+            try {
+              // Use rawTitle for synchronous processing in annotations
+              child.value = page.rawTitle || 'AUTOTITLE'
+            } catch (error) {
+              // Keep AUTOTITLE if we can't get the title
+              console.warn(`Could not resolve AUTOTITLE for ${node.url}:`, error.message)
+            }
+          }
+        }
+      }
+    }
+  })
 }
 
 function removeComment(lang) {

src/content-render/unified/annotate.js

@@ -47,7 +47,7 @@ export function createProcessor(context) {
       .use(useEnglishHeadings, context)
       .use(headingLinks)
       .use(codeHeader)
-      .use(annotate)
+      .use(annotate, context)
       .use(highlight, {
         languages: { ...common, graphql, dockerfile, http, groovy, erb, powershell },
         subset: false,

src/content-render/unified/processor.js

@@ -29,12 +29,12 @@ Or, a combination of query string and hash:
 // This is a code sample
 console.log("Hello, World!");
 
-// for more info on this, visit [AUTOTITLE](/get-started/markdown).
+// for more info on this, visit the documentation.
 function greet(name: string): void {
   console.log(`Hello, ${name}!`);
 }
 
-// another example is [AUTOTITLE](/get-started/markdown/alerts)
+// another example is using TypeScript types
 const userName: string = "TypeScript User";
 greet(userName);
 ```
@@ -47,7 +47,7 @@ const { Octokit } = require("octokit");
 
 //
 async function checkAndRedeliverWebhooks() {
-   // See [AUTOTITLE](/get-started/markdown/permissions)
+   // See the API documentation for permissions
   const TOKEN = process.env.TOKEN;
   const ORGANIZATION_NAME = process.env.ORGANIZATION_NAME;
   const HOOK_ID = process.env.HOOK_ID;

src/fixtures/fixtures/content/get-started/foo/autotitling.md

@@ -17,20 +17,6 @@ describe('autotitle', () => {
     expect.assertions(4)
   })
 
-  // skipped because autotitles aren't supported in annotated code blocks yet
-  // see docs-engineering#3691
-  test.skip('internal links in codeblocks with AUTOTITLE resolves', async () => {
-    const $ = await getDOM('/get-started/foo/autotitling')
-    const links = $('#article-contents a[href]')
-    links.each((i, element) => {
-      if ($(element).attr('href').includes('/get-started/markdown')) {
-        expect($(element).text()).toContain('Markdown')
-      }
-    })
-    // There are 2 links on the `autotitling.md` content.
-    expect.assertions(2)
-  })
-
   test('typos lead to error when NODE_ENV !== production', async () => {
     // The fixture typo-autotitling.md contains two different typos
     // of the word "AUTOTITLE", separated by `{% if version ghes %}`