Fix title being parsed as highlight text in code blocks, display titles instead of language name when title present

Author: webstackdev

_TODO.md

@@ -147,25 +147,19 @@ See comp images in Breadcrumbs component directory
 
 ## Code Block Problems
 
-- Inline code blocks are not wrapping. They're breaking to a new line. An example is in the "Scenario: CRD Sync Order Problem" section of `argocd-sync-failures-gitops-debugging-troubleshooting#specific-failure-scenarios`.
-
 - 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.
 
-- We're getting random highlighting in code blocks, like the word "app" in teh first code block in `http://localhost:4321/deep-dive/argocd-sync-failures-gitops-debugging-troubleshooting#sync-waves-and-resource-ordering`
+- 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:
 
 - 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.
 
-- The title for a code block with yaml as the language type in "Sync wave annotations controlling resource application order" section of `src/content/articles/argocd-sync-failures-gitops-debugging-troubleshooting/index.mdx` is not displaying, it's showing the YAML language tag instead of the title. Also, the word "app" is being highlighted for some reason in this code block.
-
-- Code block formatting for 'text' language is very plain.
-
 - The "❌" symbol is not showing in sql code block, it's rendering as a plain "X". But "✅" renders okay. `src/content/articles/database-schema-migrations-continuous-deployment-zero-downtime/index.mdx`
 
 - Language "haproxy" is not highlighting Shiki, need to adjust allowed languages in config
 
 - add "cel" language to code blocks
 
-- The code language is in teh tab order and getting focus-visible
+- The code language is in the tab order and getting focus-visible
 
 ## Callout Issues
 

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

@@ -42,6 +42,11 @@ function getTabLabel(pre: HTMLPreElement): string | null {
   const explicit = pre.getAttribute('data-code-tabs-tab')
   if (explicit && explicit.trim()) return explicit.trim()
 
+  // Use title from code fence meta (e.g. title="otel-tail-sampling.yaml")
+  // in place of the language label when present.
+  const codeTitle = pre.getAttribute('data-code-title')
+  if (codeTitle && codeTitle.trim()) return codeTitle.trim()
+
   const language = pre.getAttribute('data-language')
   if (!language || !language.trim()) return null
   if (EXCLUDED_SINGLE_TAB_LANGUAGES.has(language.trim().toLowerCase())) return null

src/lib/config/markdown.ts

@@ -445,9 +445,9 @@ export const markdownConfig: Partial<MdxOptions> = {
         theme: shikiConfigOptions.theme,
         themeRegistrations: shikiConfigOptions.themeRegistrations,
         langAlias: shikiConfigOptions.langAlias,
-        wrap: true,
+        wrap: shikiConfigOptions.wrap,
         transformers: shikiTransformers,
-        excludeLangs: ['text', 'mermaid', 'math'],
+        excludeLangs: shikiConfigOptions.excludeLangs,
       },
     ],
     /**

src/lib/config/shiki.ts

@@ -8,6 +8,13 @@ import {
   transformerNotationErrorLevel,
 } from '@shikijs/transformers'
 
+export const langAlias = {
+  js: 'javascript',
+  ts: 'typescript',
+  md: 'markdown',
+  promql: 'go',
+}
+
 const insMetaRegex = /(?:^|\s)ins=\{([^}]+)\}/
 const delMetaRegex = /(?:^|\s)del=\{([^}]+)\}/
 const errorMetaRegex = /(?:^|\s)error=\{([^}]+)\}/
@@ -117,11 +124,7 @@ export const shikiConfigOptions = {
       fontStyle: true,
     }),
   ],
-  langAlias: {
-    js: 'javascript',
-    ts: 'typescript',
-    md: 'markdown',
-    promql: 'go',
-  },
+  excludeLangs: ['mermaid', 'math'],
+  langAlias,
   wrap: true,
 } as const

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

@@ -209,6 +209,23 @@ function extractPre(highlighted: Root | Element): Element | null {
   return null
 }
 
+/**
+ * Extract and strip `title="..."` (or `title='...'` or `title=word`) from a
+ * code-fence meta string. The title is a display-only concern and must be
+ * removed before the meta reaches Shiki transformers—otherwise path separators
+ * like `/app/` get misinterpreted as `/word/` highlight patterns by
+ * `transformerMetaWordHighlight`.
+ */
+function extractTitle(meta: string): { title: string | undefined; cleaned: string } {
+  const titleRegex = /\btitle=(?:"([^"]*)"|'([^']*)'|(\S+))/
+  const match = titleRegex.exec(meta)
+  if (!match) return { title: undefined, cleaned: meta }
+
+  const title = (match[1] ?? match[2] ?? match[3] ?? '').trim() || undefined
+  const cleaned = meta.replace(match[0], '').trim()
+  return { title, cleaned }
+}
+
 const DEFAULT_EXCLUDED_LANGS = ['mermaid', 'math']
 
 const rehypeShiki: Plugin<[RehypeShikiOptions], Root> = (options: RehypeShikiOptions) => {
@@ -254,6 +271,7 @@ const rehypeShiki: Plugin<[RehypeShikiOptions], Root> = (options: RehypeShikiOpt
       lang: string
       codeText: string
       metaRaw: string | undefined
+      title: string | undefined
     }> = []
 
     visit(
@@ -283,13 +301,18 @@ const rehypeShiki: Plugin<[RehypeShikiOptions], Root> = (options: RehypeShikiOpt
 
         const metaRaw = typeof metaValue === 'string' && metaValue.trim() ? metaValue.trim() : undefined
 
+        const { title, cleaned: metaForShiki } = metaRaw
+          ? extractTitle(metaRaw)
+          : { title: undefined, cleaned: undefined }
+
         replacements.push({
           parent,
           index,
           original: node,
           lang,
           codeText: stripTrailingFenceNewline(codeText),
-          metaRaw,
+          metaRaw: metaForShiki || undefined,
+          title,
         })
       }
     )
@@ -355,6 +378,10 @@ const rehypeShiki: Plugin<[RehypeShikiOptions], Root> = (options: RehypeShikiOpt
 
       highlightedPre.properties['data-language'] = replacement.lang
 
+      if (replacement.title) {
+        highlightedPre.properties['data-code-title'] = replacement.title
+      }
+
       highlightedPre.properties['className'] = mergeClassNames(
         highlightedPre.properties['className'],
         [