Add aliasing for languages used in code block headers

Author: webstackdev

_TODO.md

@@ -147,9 +147,13 @@ See comp images in Breadcrumbs component directory
 
 ## Code Block Problems
 
-- I aliased 'promql' to 'go'. When a code fence using the alias is rendered with the language set to 'promql', it shows as 'go' incorrectly because of the alias. Also we need custom handling for all language names that are displayed: html should be uppercase, typescript as TypeScript, etc. Also we don't want all aliased names to show the alias - for example using the aliases 'ts', 'js', and 'md' would be better to show the full language names.
+- I aliased 'promql' to 'go'. When a code fence using the alias is rendered with the language set to 'promql', it shows as 'go' incorrectly because of the alias.
 
-- We're getting random highlighting in code blocks, like the word "app" in the first code block in `argocd-sync-failures-gitops-debugging-troubleshooting/pdf.astro`. If the problem is not straight forward, let's discuss the fix first. Here's outerhtml of the block from chrome inspector:
+- We need custom handling for all language names that are displayed:
+1. `html` should be displayed uppercase as `HTML`, `yaml` as `YAML`
+2. `typescript` and its alias `ts` as `TypeScript`, `javascript` and its alias `js` as `JavaScript`
+3. The alias `md` as `Markdown
+4. All languages with their first names uppercased
 
 - The "go" language code block in `src/content/articles/api-versioning-deprecation-sunset-headers-migration/index.mdx` is not being combined with the "typescript", "python", and "ruby" tabbed code block. Same with "python" block in "### Admission Control Strategies" section of `src/content/articles/backpressure-load-shedding-admission-control-overload/index.mdx`, plus the line numbering is weird in the code block.
 

src/components/Code/CodeTabs/client/index.ts

@@ -20,7 +20,12 @@ function getCodeText(pre: HTMLPreElement): string {
 
 const EXCLUDED_SINGLE_TAB_LANGUAGES = new Set(['text', 'mermaid', 'math'])
 
-function formatLanguageLabel(language: string): string {
+/**
+ * Fallback label formatter for cases where `data-language-label` is not set
+ * (e.g. cached HTML from before the server-side label was introduced).
+ * The canonical display name config lives in `src/lib/config/codeBlocks.ts`.
+ */
+function formatLanguageLabelFallback(language: string): string {
   const normalized = language.trim().toLowerCase()
   const labelMap: Record<string, string> = {
     js: 'JavaScript',
@@ -47,11 +52,15 @@ function getTabLabel(pre: HTMLPreElement): string | null {
   const codeTitle = pre.getAttribute('data-code-title')
   if (codeTitle && codeTitle.trim()) return codeTitle.trim()
 
+  // Use server-computed display label from the centralized config.
+  const label = pre.getAttribute('data-language-label')
+  if (label && label.trim()) return label.trim()
+
   const language = pre.getAttribute('data-language')
   if (!language || !language.trim()) return null
   if (EXCLUDED_SINGLE_TAB_LANGUAGES.has(language.trim().toLowerCase())) return null
 
-  return formatLanguageLabel(language)
+  return formatLanguageLabelFallback(language)
 }
 
 async function writeToClipboard(text: string): Promise<boolean> {

src/lib/config/codeBlocks.ts

@@ -0,0 +1,63 @@
+/**
+ * Centralized configuration for how code block language names are displayed.
+ *
+ * The `languageDisplayNames` map controls the label shown in code block headers.
+ * Keys are language identifiers as written in Markdown code fences (lowercase).
+ * Values are the display strings shown in the UI.
+ *
+ * Languages not listed here fall back to capitalizing the first letter
+ * (e.g. "python" → "Python", "ruby" → "Ruby").
+ *
+ * When a code fence uses a Shiki language alias (e.g. `ts` → `typescript`),
+ * the display label is resolved from the **original** identifier the author
+ * wrote, not the resolved Shiki language. This allows `promql` (aliased to
+ * `go` for highlighting) to display as "PromQL" while real `go` fences
+ * display as "Go".
+ */
+export const languageDisplayNames: Record<string, string> = {
+  // All-uppercase acronym languages
+  css: 'CSS',
+  hcl: 'HCL',
+  html: 'HTML',
+  http: 'HTTP',
+  json: 'JSON',
+  sql: 'SQL',
+  toml: 'TOML',
+  xml: 'XML',
+  yaml: 'YAML',
+  yml: 'YAML',
+
+  // Mixed-case languages
+  graphql: 'GraphQL',
+  javascript: 'JavaScript',
+  js: 'JavaScript',
+  jsx: 'JSX',
+  markdown: 'Markdown',
+  md: 'Markdown',
+  promql: 'PromQL',
+  ts: 'TypeScript',
+  tsx: 'TSX',
+  typescript: 'TypeScript',
+}
+
+/**
+ * Returns the display label for a code block language.
+ *
+ * Should be called with the **original** language identifier from the Markdown
+ * source (before Shiki alias resolution) so that aliases like `promql` display
+ * correctly instead of showing the resolved target (`go`).
+ *
+ * Lookup order:
+ * 1. Exact match in `languageDisplayNames`
+ * 2. Capitalize first letter (default)
+ */
+export function formatLanguageLabel(language: string): string {
+  const key = language.trim().toLowerCase()
+  if (!key) return language
+
+  const explicit = languageDisplayNames[key]
+  if (explicit) return explicit
+
+  // Default: capitalize first letter
+  return key.charAt(0).toUpperCase() + key.slice(1)
+}

src/lib/markdown/plugins/rehype-shiki/index.ts

@@ -2,6 +2,7 @@ import type { Root, Element, Parent, Text } from 'hast'
 import type { Plugin } from 'unified'
 import { visit } from 'unist-util-visit'
 import { createHighlighter } from 'shiki'
+import { formatLanguageLabel } from '@lib/config/codeBlocks'
 
 type ShikiThemes =
   | string
@@ -269,6 +270,7 @@ const rehypeShiki: Plugin<[RehypeShikiOptions], Root> = (options: RehypeShikiOpt
       index: number
       original: Element
       lang: string
+      rawLang: string
       codeText: string
       metaRaw: string | undefined
       title: string | undefined
@@ -310,6 +312,7 @@ const rehypeShiki: Plugin<[RehypeShikiOptions], Root> = (options: RehypeShikiOpt
           index,
           original: node,
           lang,
+          rawLang,
           codeText: stripTrailingFenceNewline(codeText),
           metaRaw: metaForShiki || undefined,
           title,
@@ -377,6 +380,7 @@ const rehypeShiki: Plugin<[RehypeShikiOptions], Root> = (options: RehypeShikiOpt
       delete (highlightedPre.properties as Record<string, unknown>)['data-shiki-meta']
 
       highlightedPre.properties['data-language'] = replacement.lang
+      highlightedPre.properties['data-language-label'] = formatLanguageLabel(replacement.rawLang)
 
       if (replacement.title) {
         highlightedPre.properties['data-code-title'] = replacement.title