From f21b48589d58148b07fec63853f385e8a7bc44e8 Mon Sep 17 00:00:00 2001
From: Elecmonkey <elecmonkey@hotmail.com>
Date: Sun, 28 Sep 2025 01:09:05 +0800
Subject: [PATCH 1/2] feat(markdown): add languageLabel config and improve
 languageAlias display

---
 src/node/markdown/markdown.ts           | 20 ++++++++++++++++++--
 src/node/markdown/plugins/highlight.ts  |  5 ++++-
 src/node/markdown/plugins/preWrapper.ts | 12 +++++++++++-
 3 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/src/node/markdown/markdown.ts b/src/node/markdown/markdown.ts
index 7e6d09e8..9cdaff85 100644
--- a/src/node/markdown/markdown.ts
+++ b/src/node/markdown/markdown.ts
@@ -88,11 +88,24 @@ export interface MarkdownOptions extends Options {
   languages?: (LanguageInput | BuiltinLanguage)[]
   /**
    * Custom language aliases.
+   * Maps custom language names to existing languages for syntax highlighting.
+   * Language identifiers with underscores will automatically display with spaces.
+   * Alias lookup is case-insensitive.
+   *
+   * @example { 'my_lang': 'python' } 
+   * 
+   * ```My_Lang uses Python highlighting, displays "My Lang"
    *
-   * @example { 'my-lang': 'js' }
    * @see https://shiki.style/guide/load-lang#custom-language-aliases
    */
   languageAlias?: Record<string, string>
+  /**
+   * Custom language labels for display.
+   * Overrides the default language label shown in code blocks.
+   *
+   * @example { 'vue': 'Vue SFC' }
+   */
+  languageLabel?: Record<string, string>
   /**
    * Show line numbers in code blocks
    * @default false
@@ -249,7 +262,10 @@ export async function createMarkdownRenderer(
   // custom plugins
   md.use(componentPlugin, { ...options.component })
     .use(highlightLinePlugin)
-    .use(preWrapperPlugin, { codeCopyButtonTitle })
+    .use(preWrapperPlugin, {
+      codeCopyButtonTitle,
+      languageLabel: options.languageLabel
+    })
     .use(snippetPlugin, srcDir)
     .use(containerPlugin, options.container)
     .use(imagePlugin, options.image)
diff --git a/src/node/markdown/plugins/highlight.ts b/src/node/markdown/plugins/highlight.ts
index f1285ed7..4e62d3d1 100644
--- a/src/node/markdown/plugins/highlight.ts
+++ b/src/node/markdown/plugins/highlight.ts
@@ -68,7 +68,10 @@ export async function highlight(
       ...(options.languages || []),
       ...Object.values(options.languageAlias || {})
     ],
-    langAlias: options.languageAlias
+    langAlias: options.languageAlias ?
+      Object.fromEntries(
+        Object.entries(options.languageAlias).map(([key, value]) => [key.toLowerCase(), value])
+      ) : undefined
   })
 
   await options?.shikiSetup?.(highlighter)
diff --git a/src/node/markdown/plugins/preWrapper.ts b/src/node/markdown/plugins/preWrapper.ts
index e7d553b3..d68043a1 100644
--- a/src/node/markdown/plugins/preWrapper.ts
+++ b/src/node/markdown/plugins/preWrapper.ts
@@ -2,6 +2,7 @@ import type { MarkdownItAsync } from 'markdown-it-async'
 
 export interface Options {
   codeCopyButtonTitle: string
+  languageLabel?: Record<string, string>
 }
 
 export function preWrapperPlugin(md: MarkdownItAsync, options: Options) {
@@ -17,11 +18,12 @@ export function preWrapperPlugin(md: MarkdownItAsync, options: Options) {
     token.info = token.info.replace(/ active$/, '').replace(/ active /, ' ')
 
     const lang = extractLang(token.info)
+    const langLabel = getLangLabel(lang, options.languageLabel)
 
     return (
       `<div class="language-${lang}${active}">` +
       `<button title="${options.codeCopyButtonTitle}" class="copy"></button>` +
-      `<span class="lang">${lang}</span>` +
+      `<span class="lang">${langLabel}</span>` +
       fence(...args) +
       '</div>'
     )
@@ -46,3 +48,11 @@ function extractLang(info: string) {
     .replace(/^vue-html$/, 'template')
     .replace(/^ansi$/, '')
 }
+
+function getLangLabel(lang: string, languageLabel?: Record<string, string>): string {
+  if (languageLabel && languageLabel[lang]) {
+    return languageLabel[lang]
+  }
+
+  return lang.replace(/_/g, ' ')
+}

From 597e8e4468a9e2e0916cc460b5558b7064d3167b Mon Sep 17 00:00:00 2001
From: Elecmonkey <elecmonkey@hotmail.com>
Date: Sun, 28 Sep 2025 01:10:54 +0800
Subject: [PATCH 2/2] docs(en,zh): update for language label & language alias
 features

---
 docs/en/guide/markdown.md | 2 +-
 docs/zh/guide/markdown.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/en/guide/markdown.md b/docs/en/guide/markdown.md
index c3342474..e1be3e6b 100644
--- a/docs/en/guide/markdown.md
+++ b/docs/en/guide/markdown.md
@@ -365,7 +365,7 @@ export default {
 
 A [list of valid languages](https://shiki.style/languages) is available on Shiki's repository.
 
-You may also customize syntax highlight theme in app config. Please see [`markdown` options](../reference/site-config#markdown) for more details.
+You may also customize syntax highlight theme, configure language aliases, and set custom language labels in app config. Please see [`markdown` options](../reference/site-config#markdown) for more details.
 
 ## Line Highlighting in Code Blocks
 
diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md
index cda368ee..a401774c 100644
--- a/docs/zh/guide/markdown.md
+++ b/docs/zh/guide/markdown.md
@@ -343,7 +343,7 @@ export default {
 
 在 Shiki 的代码仓库中，可以找到[合法的编程语言列表](https://shiki.style/languages)。
 
-还可以全局配置中自定义语法高亮主题。有关详细信息，参见 [`markdown` 选项](../reference/site-config#markdown)得到更多信息。
+还可以在全局配置中自定义语法高亮主题、配置语言别名和自定义语言标签。有关详细信息，参见 [`markdown` 选项](../reference/site-config#markdown)得到更多信息。
 
 ## 在代码块中实现行高亮 {#line-highlighting-in-code-blocks}