Auto-generate aria-labels for octicons and remove linter rule (#58349)

Author: heiskr

data/reusables/contributing/content-linter-rules.md

@@ -52,7 +52,6 @@
 | GHD041 | third-party-action-pinning | Code examples that use third-party actions must always pin to a full length commit SHA | error | feature, actions |
 | GHD042 | liquid-tag-whitespace | Liquid tags should start and end with one whitespace. Liquid tag arguments should be separated by only one whitespace. | error | liquid, format |
 | GHD043 | link-quotation | Internal link titles must not be surrounded by quotations | error | links, url |
-| GHD044 | octicon-aria-labels | Octicons should always have an aria-label attribute even if aria-hidden. | warning | accessibility, octicons |
 | GHD045 | code-annotation-comment-spacing | Code comments in annotation blocks must have exactly one space after the comment character(s) | warning | code, comments, annotate, spacing |
 | GHD046 | outdated-release-phase-terminology | Outdated release phase terminology should be replaced with current GitHub terminology | warning | terminology, consistency, release-phases |
 | GHD047 | table-column-integrity | Tables must have consistent column counts across all rows | warning | tables, accessibility, formatting |

src/article-api/tests/article-body.ts

@@ -0,0 +1,69 @@
+import { beforeAll, describe, expect, test } from 'vitest'
+
+import { get } from '@/tests/helpers/e2etest'
+
+const makeURL = (pathname: string): string =>
+  `/api/article/body?${new URLSearchParams({ pathname })}`
+
+describe('article body api', () => {
+  beforeAll(() => {
+    // If you didn't set the `ROOT` variable, the tests will fail rather
+    // cryptically. So as a warning for engineers running these tests,
+    // alert in case it was accidentally forgotten.
+    if (!process.env.ROOT) {
+      console.warn(
+        'WARNING: The article body tests require the ROOT environment variable to be set to the fixture root',
+      )
+    }
+  })
+
+  test('happy path', async () => {
+    const res = await get(makeURL('/en/get-started/start-your-journey/hello-world'))
+    expect(res.statusCode).toBe(200)
+    expect(res.body).toContain('## Introduction')
+    expect(res.body).toContain('This is just a test.')
+    expect(res.headers['content-type']).toContain('text/markdown')
+  })
+
+  test('octicons auto-generate aria-labels', async () => {
+    const res = await get(makeURL('/en/get-started/start-your-journey/hello-world'))
+    expect(res.statusCode).toBe(200)
+
+    // Check that octicons without aria-label get auto-generated ones
+    expect(res.body).toContain('aria-label="check icon"')
+    expect(res.body).toContain('aria-label="git branch icon"')
+  })
+
+  test('octicons with custom aria-labels use the custom value', async () => {
+    const res = await get(makeURL('/en/get-started/start-your-journey/hello-world'))
+    expect(res.statusCode).toBe(200)
+
+    // Check that custom aria-labels are preserved
+    expect(res.body).toContain('aria-label="Supported"')
+    expect(res.body).toContain('aria-label="Not supported"')
+  })
+
+  test('octicons with other attributes still get auto-generated aria-labels', async () => {
+    const res = await get(makeURL('/en/get-started/start-your-journey/hello-world'))
+    expect(res.statusCode).toBe(200)
+
+    // Check that octicons with width attribute still get aria-labels
+    expect(res.body).toContain('aria-label="rocket icon"')
+    expect(res.body).toContain('width="32"')
+  })
+
+  test('a pathname that does not exist', async () => {
+    const res = await get(makeURL('/en/never/heard/of'))
+    expect(res.statusCode).toBe(404)
+    const { error } = JSON.parse(res.body)
+    expect(error).toBe("No page found for '/en/never/heard/of'")
+  })
+
+  test('non-article pages return error', async () => {
+    // Index pages are not articles and should not be renderable
+    const res = await get(makeURL('/en/get-started'))
+    expect(res.statusCode).toBe(403)
+    const { error } = JSON.parse(res.body)
+    expect(error).toContain("isn't yet available in markdown")
+  })
+})

src/content-linter/lib/linting-rules/index.ts

@@ -42,7 +42,6 @@ import { tableColumnIntegrity } from '@/content-linter/lib/linting-rules/table-c
 import { thirdPartyActionPinning } from '@/content-linter/lib/linting-rules/third-party-action-pinning'
 import { liquidTagWhitespace } from '@/content-linter/lib/linting-rules/liquid-tag-whitespace'
 import { linkQuotation } from '@/content-linter/lib/linting-rules/link-quotation'
-import { octiconAriaLabels } from '@/content-linter/lib/linting-rules/octicon-aria-labels'
 import { liquidIfversionVersions } from '@/content-linter/lib/linting-rules/liquid-ifversion-versions'
 import { outdatedReleasePhaseTerminology } from '@/content-linter/lib/linting-rules/outdated-release-phase-terminology'
 import { frontmatterVersionsWhitespace } from '@/content-linter/lib/linting-rules/frontmatter-versions-whitespace'
@@ -105,7 +104,7 @@ export const gitHubDocsMarkdownlint = {
     thirdPartyActionPinning, // GHD041
     liquidTagWhitespace, // GHD042
     linkQuotation, // GHD043
-    octiconAriaLabels, // GHD044
+    // GHD044 removed - octicon aria-labels are now auto-generated
     codeAnnotationCommentSpacing, // GHD045
     outdatedReleasePhaseTerminology, // GHD046
     tableColumnIntegrity, // GHD047

src/content-linter/lib/linting-rules/octicon-aria-labels.ts

@@ -162,12 +162,7 @@ const githubDocsConfig = {
     'partial-markdown-files': true,
     'yml-files': true,
   },
-  'octicon-aria-labels': {
-    // GHD044
-    severity: 'warning',
-    'partial-markdown-files': true,
-    'yml-files': true,
-  },
+  // GHD044 removed - octicon aria-labels are now auto-generated
   'code-annotation-comment-spacing': {
     // GHD045
     severity: 'warning',

src/content-linter/style/github-docs.ts

@@ -24,7 +24,10 @@ const SyntaxHelp = 'Syntax Error in tag \'octicon\' - Valid syntax: octicon "<na
  * Uses the octicons library to render the chosen icon. Also
  * supports passing attributes like `width="64"`.
  *
- * {% octicon "check" %}
+ * If no aria-label is provided, a default one will be auto-generated
+ * based on the icon name (e.g., "check icon", "git-branch icon").
+ *
+ * {% octicon "check" %} <!-- auto-generates aria-label="check icon" -->
  * {% octicon "check" width="64" aria-label="Example label" %}
  */
 const Octicon: LiquidTag = {
@@ -70,6 +73,13 @@ const Octicon: LiquidTag = {
       throw new Error(`Octicon ${this.icon} does not exist`)
     }
 
+    // Auto-generate aria-label if not provided
+    // Replace non-alphanumeric characters with spaces and append " icon"
+    if (!this.options['aria-label']) {
+      const defaultLabel = `${this.icon.toLowerCase().replace(/[^a-z0-9]+/gi, ' ')} icon`
+      this.options['aria-label'] = defaultLabel
+    }
+
     const result: string = octicons[this.icon].toSVG(this.options)
     return result
   },

src/content-linter/tests/unit/octicon-aria-labels.ts

@@ -42,4 +42,34 @@ describe('octicon tag', () => {
       'Octicon pizza-patrol does not exist',
     )
   })
+
+  test('auto-generates aria-label when not provided', async () => {
+    const actual = await renderContent('{% octicon "check" %}')
+    expect(actual).toContain('<svg ')
+    expect(actual).toContain('class="octicon octicon-check"')
+    expect(actual).toContain('aria-label="check icon"')
+  })
+
+  test('auto-generates aria-label with spaces for hyphenated icon names', async () => {
+    const actual = await renderContent('{% octicon "git-branch" %}')
+    expect(actual).toContain('<svg ')
+    expect(actual).toContain('class="octicon octicon-git-branch"')
+    expect(actual).toContain('aria-label="git branch icon"')
+  })
+
+  test('uses custom aria-label instead of auto-generated one when provided', async () => {
+    const actual = await renderContent('{% octicon "check" aria-label="Supported" %}')
+    expect(actual).toContain('<svg ')
+    expect(actual).toContain('class="octicon octicon-check"')
+    expect(actual).toContain('aria-label="Supported"')
+    expect(actual).not.toContain('aria-label="check icon"')
+  })
+
+  test('auto-generates aria-label even when other attributes are provided', async () => {
+    const actual = await renderContent('{% octicon "filter" width="32" %}')
+    expect(actual).toContain('<svg ')
+    expect(actual).toContain('class="octicon octicon-filter"')
+    expect(actual).toContain('aria-label="filter icon"')
+    expect(actual).toContain('width="32"')
+  })
 })