feat(theme): render labels as inline markdown

Author: dev-itsheng

__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/'
         }
       ]
     },

__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>'
+    )
   })
 })
 

__tests__/e2e/theme-labels/index.md

@@ -0,0 +1 @@
+# Theme Labels

__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

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: {

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.
 

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: {

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
   }
 }