From 99ff48bc9f61904e18847e1a24ec256969c3daba Mon Sep 17 00:00:00 2001
From: Gao Sheng <453491931@qq.com>
Date: Thu, 20 Aug 2026 02:17:26 +0800
Subject: [PATCH] feat(theme): render labels as inline markdown

---
 __tests__/e2e/.vitepress/config.ts         |   4 +
 __tests__/e2e/multi-sidebar/index.test.ts  |  14 ++
 __tests__/e2e/theme-labels/index.md        |   1 +
 __tests__/unit/node/config.test.ts         |  94 ++++++++++-
 docs/en/reference/default-theme-config.md  |   9 +-
 docs/en/reference/default-theme-nav.md     |  10 +-
 docs/en/reference/default-theme-sidebar.md |  15 ++
 src/node/config.ts                         |  17 +-
 src/node/themeConfig.ts                    | 172 +++++++++++++++++++++
 types/default-theme.d.ts                   |  14 +-
 10 files changed, 343 insertions(+), 7 deletions(-)
 create mode 100644 __tests__/e2e/theme-labels/index.md
 create mode 100644 src/node/themeConfig.ts

diff --git a/__tests__/e2e/.vitepress/config.ts b/__tests__/e2e/.vitepress/config.ts
index cafcfd50..d0fbea19 100644
--- a/__tests__/e2e/.vitepress/config.ts
+++ b/__tests__/e2e/.vitepress/config.ts
@@ -86,6 +86,10 @@ const sidebar: DefaultTheme.Config['sidebar'] = {
         {
           text: '& &#60;Test Page &> <code>code</code>',
           link: '/text-literals/'
+        },
+        {
+          text: 'Markdown `<Label &>`',
+          link: '/theme-labels/'
         }
       ]
     },
diff --git a/__tests__/e2e/multi-sidebar/index.test.ts b/__tests__/e2e/multi-sidebar/index.test.ts
index cd654301..d7dab05e 100644
--- a/__tests__/e2e/multi-sidebar/index.test.ts
+++ b/__tests__/e2e/multi-sidebar/index.test.ts
@@ -18,6 +18,20 @@ describe('test multi sidebar sort root', () => {
       'Markdown Extensions',
       'Team & Sponsors'
     ])
+
+    expect(await sidebarLocator.nth(1).innerHTML()).toBe(
+      '&amp; &lt;Text Literals &amp;&gt; <code>code</code>'
+    )
+  })
+
+  test('renders inline markdown in sidebar labels', async () => {
+    const markdownLabel = page.locator(
+      '.VPSidebarItem.level-1 a[href$="/theme-labels/"] .text'
+    )
+
+    expect(await markdownLabel.innerHTML()).toBe(
+      'Markdown <code>&lt;Label &amp;&gt;</code>'
+    )
   })
 })
 
diff --git a/__tests__/e2e/theme-labels/index.md b/__tests__/e2e/theme-labels/index.md
new file mode 100644
index 00000000..bfdccc55
--- /dev/null
+++ b/__tests__/e2e/theme-labels/index.md
@@ -0,0 +1 @@
+# Theme Labels
diff --git a/__tests__/unit/node/config.test.ts b/__tests__/unit/node/config.test.ts
index df4af72c..c582c8fb 100644
--- a/__tests__/unit/node/config.test.ts
+++ b/__tests__/unit/node/config.test.ts
@@ -1,7 +1,99 @@
 import type { MarkdownItAsync } from 'markdown-it-async'
-import { mergeConfig, type UserConfig } from 'node/config'
+import { mergeConfig, resolveSiteData, type UserConfig } from 'node/config'
 
 describe('node/config', () => {
+  test('renders inline markdown in default theme text fields', async () => {
+    const site = await resolveSiteData(process.cwd(), {
+      themeConfig: {
+        nav: [
+          { text: 'Vue `<script setup>`', link: '/guide' },
+          {
+            text: '**Reference**',
+            items: [
+              { text: 'API `<T>`', link: '/api' },
+              {
+                text: 'Nested `<Menu>`',
+                items: [{ text: '`Child`', link: '/child' }]
+              }
+            ]
+          }
+        ],
+        sidebar: [
+          {
+            text: 'Guide `<script setup>`',
+            docFooterText: 'Footer `<Foo>`',
+            items: [
+              { text: '**Intro**', link: '/intro' },
+              { text: '<code>Raw HTML</code>', link: '/html' }
+            ]
+          }
+        ],
+        docFooter: {
+          prev: 'Previous `<Page>`',
+          next: false
+        }
+      }
+    })
+
+    expect(site.themeConfig.nav[0].text).toBe(
+      'Vue <code>&lt;script setup&gt;</code>'
+    )
+    expect(site.themeConfig.nav[1].text).toBe('<strong>Reference</strong>')
+    expect(site.themeConfig.nav[1].items[0].text).toBe(
+      'API <code>&lt;T&gt;</code>'
+    )
+    expect(site.themeConfig.nav[1].items[1].text).toBe(
+      'Nested <code>&lt;Menu&gt;</code>'
+    )
+    expect(site.themeConfig.nav[1].items[1].items[0].text).toBe(
+      '<code>Child</code>'
+    )
+    expect(site.themeConfig.sidebar[0].text).toBe(
+      'Guide <code>&lt;script setup&gt;</code>'
+    )
+    expect(site.themeConfig.sidebar[0].docFooterText).toBe(
+      'Footer <code>&lt;Foo&gt;</code>'
+    )
+    expect(site.themeConfig.sidebar[0].items[0].text).toBe(
+      '<strong>Intro</strong>'
+    )
+    expect(site.themeConfig.sidebar[0].items[1].text).toBe(
+      '<code>Raw HTML</code>'
+    )
+    expect(site.themeConfig.docFooter.prev).toBe(
+      'Previous <code>&lt;Page&gt;</code>'
+    )
+    expect(site.themeConfig.docFooter.next).toBe(false)
+  })
+
+  test('renders inline markdown in locale and additional default theme configs', async () => {
+    const site = await resolveSiteData(process.cwd(), {
+      locales: {
+        zh: {
+          label: 'Chinese',
+          themeConfig: {
+            sidebar: [{ text: 'Locale `<script setup>`' }]
+          }
+        }
+      },
+      additionalConfig: {
+        '/guide/': {
+          themeConfig: {
+            nav: [{ text: 'Guide `<Item>`', link: '/guide/' }]
+          }
+        }
+      }
+    })
+
+    expect(site.locales.zh.themeConfig?.sidebar?.[0].text).toBe(
+      'Locale <code>&lt;script setup&gt;</code>'
+    )
+    expect(
+      typeof site.additionalConfig !== 'function' &&
+        site.additionalConfig?.['/guide/'].themeConfig?.nav?.[0].text
+    ).toBe('Guide <code>&lt;Item&gt;</code>')
+  })
+
   test('merges markdown hooks from extended configs', async () => {
     const calls: string[] = []
     const md = {} as MarkdownItAsync
diff --git a/docs/en/reference/default-theme-config.md b/docs/en/reference/default-theme-config.md
index cef4c48a..72b64102 100644
--- a/docs/en/reference/default-theme-config.md
+++ b/docs/en/reference/default-theme-config.md
@@ -88,6 +88,8 @@ export default {
 
 The configuration for the nav menu item. More details in [Default Theme: Nav](./default-theme-nav#navigation-links).
 
+The `text` fields support inline Markdown and HTML.
+
 ```ts
 export default {
   themeConfig: {
@@ -136,6 +138,8 @@ interface NavItemWithChildren {
 
 The configuration for the sidebar menu item. More details in [Default Theme: Sidebar](./default-theme-sidebar).
 
+The `text` and `docFooterText` fields support inline Markdown and HTML.
+
 ```ts
 export default {
   themeConfig: {
@@ -162,7 +166,7 @@ export interface SidebarMulti {
 
 export type SidebarItem = {
   /**
-   * The text label of the item.
+   * The text label of the item. Supports inline Markdown and HTML.
    */
   text?: string
 
@@ -192,6 +196,7 @@ export type SidebarItem = {
 
   /**
    * Customize text that appears on the footer of previous/next page.
+   * Supports inline Markdown and HTML.
    */
   docFooterText?: string
 
@@ -410,6 +415,8 @@ Learn more in [Default Theme: Carbon Ads](./default-theme-carbon-ads)
 
 Can be used to customize text appearing above previous and next links. Helpful if not writing docs in English. Also can be used to disable prev/next links globally. If you want to selectively enable/disable prev/next links, you can use [frontmatter](./default-theme-prev-next-links).
 
+The `prev` and `next` string values support inline Markdown and HTML.
+
 ```ts
 export default {
   themeConfig: {
diff --git a/docs/en/reference/default-theme-nav.md b/docs/en/reference/default-theme-nav.md
index 01ff2090..21b56871 100644
--- a/docs/en/reference/default-theme-nav.md
+++ b/docs/en/reference/default-theme-nav.md
@@ -57,7 +57,15 @@ export default {
 }
 ```
 
-The `text` is the actual text displayed in nav, and the `link` is the link that will be navigated to when the text is clicked. For the link, set path to the actual file without `.md` prefix, and always start with `/`.
+The `text` is the actual text displayed in nav, and supports inline Markdown and HTML. The `link` is the link that will be navigated to when the text is clicked. For the link, set path to the actual file without `.md` prefix, and always start with `/`.
+
+```js
+export default {
+  themeConfig: {
+    nav: [{ text: 'Vue `<script setup>`', link: '/guide' }]
+  }
+}
+```
 
 The `link` can also be a function that accepts [`PageData`](./runtime-api#usedata) as the argument and returns the path.
 
diff --git a/docs/en/reference/default-theme-sidebar.md b/docs/en/reference/default-theme-sidebar.md
index 559cd61d..b929c291 100644
--- a/docs/en/reference/default-theme-sidebar.md
+++ b/docs/en/reference/default-theme-sidebar.md
@@ -27,6 +27,21 @@ export default {
 
 The simplest form of the sidebar menu is passing in a single array of links. The first level item defines the "section" for the sidebar. It should contain `text`, which is the title of the section, and `items` which are the actual navigation links.
 
+The `text` fields in sidebar items support inline Markdown and HTML:
+
+```js
+export default {
+  themeConfig: {
+    sidebar: [
+      {
+        text: 'Vue `<script setup>`',
+        items: [{ text: 'API `<T>`', link: '/api' }]
+      }
+    ]
+  }
+}
+```
+
 ```js
 export default {
   themeConfig: {
diff --git a/src/node/config.ts b/src/node/config.ts
index 982016a6..74e70a89 100644
--- a/src/node/config.ts
+++ b/src/node/config.ts
@@ -25,6 +25,11 @@ import {
   type SiteData
 } from './shared'
 import type { RawConfigExports, SiteConfig, UserConfig } from './siteConfig'
+import {
+  resolveAdditionalDefaultThemeConfigs,
+  resolveDefaultThemeConfig,
+  resolveLocaleDefaultThemeConfigs
+} from './themeConfig'
 import { glob } from './utils/glob'
 
 export { resolvePages } from './plugins/dynamicRoutesPlugin'
@@ -358,6 +363,12 @@ export async function resolveSiteData(
 ): Promise<SiteData> {
   userConfig = userConfig || (await resolveUserConfig(root, command, mode))[0]
 
+  const themeConfig = resolveDefaultThemeConfig(userConfig.themeConfig || {})
+  const locales = resolveLocaleDefaultThemeConfigs(userConfig.locales) || {}
+  const additionalConfig = resolveAdditionalDefaultThemeConfigs(
+    userConfig.additionalConfig
+  )
+
   return {
     lang: userConfig.lang || 'en-US',
     dir: userConfig.dir || 'ltr',
@@ -370,11 +381,11 @@ export async function resolveSiteData(
       prefetchLinks: userConfig.router?.prefetchLinks ?? true
     },
     appearance: userConfig.appearance ?? true,
-    themeConfig: userConfig.themeConfig || {},
-    locales: userConfig.locales || {},
+    themeConfig,
+    locales,
     cleanUrls: !!userConfig.cleanUrls,
     contentProps: userConfig.contentProps,
-    additionalConfig: userConfig.additionalConfig
+    additionalConfig
   }
 }
 
diff --git a/src/node/themeConfig.ts b/src/node/themeConfig.ts
new file mode 100644
index 00000000..6214814d
--- /dev/null
+++ b/src/node/themeConfig.ts
@@ -0,0 +1,172 @@
+import MarkdownIt from 'markdown-it'
+import type { UserConfig } from './siteConfig'
+import { isObject } from './shared'
+
+type AdditionalConfig = NonNullable<UserConfig['additionalConfig']>
+type AdditionalConfigLoader = Extract<
+  AdditionalConfig,
+  (filePath: string) => unknown
+>
+
+const inlineMarkdown = new MarkdownIt({ html: true, linkify: true })
+
+export function resolveDefaultThemeConfig<T>(themeConfig: T): T {
+  if (!isObject(themeConfig)) return themeConfig
+
+  const resolved = { ...themeConfig } as Record<string, any>
+
+  if (Array.isArray(resolved.nav)) {
+    resolved.nav = resolveNavItems(resolved.nav)
+  }
+
+  if (resolved.sidebar) {
+    resolved.sidebar = resolveSidebar(resolved.sidebar)
+  }
+
+  if (isObject(resolved.docFooter)) {
+    resolved.docFooter = resolveDocFooter(resolved.docFooter)
+  }
+
+  return resolved as T
+}
+
+export function resolveLocaleDefaultThemeConfigs<T>(
+  locales: T | undefined
+): T | undefined {
+  if (!isObject(locales)) return locales
+
+  return Object.fromEntries(
+    Object.entries(locales).map(([key, locale]) => {
+      if (!isObject(locale) || !isObject(locale.themeConfig)) {
+        return [key, locale]
+      }
+
+      return [
+        key,
+        {
+          ...locale,
+          themeConfig: resolveDefaultThemeConfig(locale.themeConfig)
+        }
+      ]
+    })
+  ) as T
+}
+
+export function resolveAdditionalDefaultThemeConfigs<
+  T extends AdditionalConfig
+>(additionalConfig: T | undefined): T | undefined {
+  if (!additionalConfig) return additionalConfig
+
+  if (typeof additionalConfig === 'function') {
+    return ((filePath: string) => {
+      const configs = (additionalConfig as AdditionalConfigLoader)(filePath)
+      return configs?.map(resolveAdditionalConfig)
+    }) as T
+  }
+
+  return Object.fromEntries(
+    Object.entries(additionalConfig).map(([key, config]) => [
+      key,
+      resolveAdditionalConfig(config)
+    ])
+  ) as T
+}
+
+function resolveAdditionalConfig<T>(config: T): T {
+  if (!isObject(config) || !isObject(config.themeConfig)) {
+    return config
+  }
+
+  return {
+    ...config,
+    themeConfig: resolveDefaultThemeConfig(config.themeConfig)
+  }
+}
+
+function resolveNavItems<T>(items: T[]): T[] {
+  return items.map(resolveNavItem)
+}
+
+function resolveNavItem<T>(item: T): T {
+  if (!isObject(item)) return item
+
+  const resolved = resolveText(item)
+
+  if (Array.isArray(item.items)) {
+    resolved.items = resolveNavItems(item.items)
+  }
+
+  return resolved as T
+}
+
+function resolveSidebar<T>(sidebar: T): T {
+  if (Array.isArray(sidebar)) {
+    return resolveSidebarItems(sidebar) as T
+  }
+
+  if (!isObject(sidebar)) return sidebar
+
+  return Object.fromEntries(
+    Object.entries(sidebar).map(([key, value]) => {
+      if (Array.isArray(value)) {
+        return [key, resolveSidebarItems(value)]
+      }
+
+      if (isObject(value) && Array.isArray(value.items)) {
+        return [key, { ...value, items: resolveSidebarItems(value.items) }]
+      }
+
+      return [key, value]
+    })
+  ) as T
+}
+
+function resolveSidebarItems<T>(items: T[]): T[] {
+  return items.map(resolveSidebarItem)
+}
+
+function resolveSidebarItem<T>(item: T): T {
+  if (!isObject(item)) return item
+
+  const resolved = resolveText(item)
+
+  if (typeof item.docFooterText === 'string') {
+    resolved.docFooterText = renderInlineMarkdown(item.docFooterText)
+  }
+
+  if (Array.isArray(item.items)) {
+    resolved.items = resolveSidebarItems(item.items)
+  }
+
+  return resolved as T
+}
+
+function resolveDocFooter<T>(docFooter: T): T {
+  if (!isObject(docFooter)) return docFooter
+
+  const resolved = { ...docFooter } as Record<string, any>
+
+  if (typeof docFooter.prev === 'string') {
+    resolved.prev = renderInlineMarkdown(docFooter.prev)
+  }
+
+  if (typeof docFooter.next === 'string') {
+    resolved.next = renderInlineMarkdown(docFooter.next)
+  }
+
+  return resolved as T
+}
+
+function resolveText<T>(item: T): Record<string, any> {
+  const resolved = { ...item } as Record<string, any>
+
+  if (typeof (item as Record<string, any>).text === 'string') {
+    resolved.text = renderInlineMarkdown((item as Record<string, any>).text)
+  }
+
+  return resolved
+}
+
+function renderInlineMarkdown(text: string): string {
+  return inlineMarkdown.renderInline(text)
+}
diff --git a/types/default-theme.d.ts b/types/default-theme.d.ts
index 1fb1d7e4..9a904aa8 100644
--- a/types/default-theme.d.ts
+++ b/types/default-theme.d.ts
@@ -167,6 +167,9 @@ export namespace DefaultTheme {
   }
 
   export interface NavItemWithLink {
+    /**
+     * The text label of the item. Supports inline Markdown and HTML.
+     */
     text: string
     link: string | ((payload: PageData) => string)
     items?: never
@@ -182,11 +185,17 @@ export namespace DefaultTheme {
   }
 
   export interface NavItemChildren {
+    /**
+     * The text label of the item. Supports inline Markdown and HTML.
+     */
     text?: string
     items: NavItemWithLink[]
   }
 
   export interface NavItemWithChildren {
+    /**
+     * The text label of the item. Supports inline Markdown and HTML.
+     */
     text?: string
     items: (NavItemComponent | NavItemChildren | NavItemWithLink)[]
 
@@ -232,7 +241,7 @@ export namespace DefaultTheme {
 
   export type SidebarItem = {
     /**
-     * The text label of the item.
+     * The text label of the item. Supports inline Markdown and HTML.
      */
     text?: string
 
@@ -262,6 +271,7 @@ export namespace DefaultTheme {
 
     /**
      * Customize text that appears on the footer of previous/next page.
+     * Supports inline Markdown and HTML.
      */
     docFooterText?: string
 
@@ -293,6 +303,7 @@ export namespace DefaultTheme {
   export interface DocFooter {
     /**
      * Custom label for previous page button. Can be set to `false` to disable.
+     * Supports inline Markdown and HTML.
      *
      * @default 'Previous page'
      */
@@ -300,6 +311,7 @@ export namespace DefaultTheme {
 
     /**
      * Custom label for next page button. Can be set to `false` to disable.
+     * Supports inline Markdown and HTML.
      *
      * @default 'Next page'
      */