Merge 2ddd194f11 into 3e681e2ffd

docs/en/reference/default-theme-config.md

@@ -501,6 +501,13 @@ Can be used to customize the aria-label of the `⋯` menu button in the navbar.
 
 Can be used to customize the label of the skip to content link. This link is shown when the user is navigating the site using a keyboard.
 
+## skipTitleUpdate
+
+- Type: `boolean`
+- Default: `false`
+
+Can be used to skip the default title update logic so it can be implemented on your own.
+
 ## externalLinkIcon
 
 - Type: `boolean`

docs/en/reference/default-theme-nav.md

@@ -167,6 +167,27 @@ export default {
 
 Refer [`socialLinks`](./default-theme-config#sociallinks).
 
+## Custom Text Item Component
+
+If you want to use the default theme but modify only the text of the items, you can override the `SidebarTextItem` inside the `enhanceApp` function. For example:
+
+```js
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme';
+import CustomSidebarTextItem from './components/CustomSidebarTextItem.vue';
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    app.component('SidebarTextItem', CustomSidebarTextItem);
+  }
+};
+```
+
+### Creating a Custom `SidebarTextItem`
+
+To create your own `SidebarTextItem`, define a Vue component that accepts a `content` prop and renders it inside a chosen HTML tag. This allows you to fully customize how the text appears while maintaining compatibility with the default theme.
+
 ## Custom Components
 
 You can include custom components in the navigation bar by using the `component` option. The `component` key should be the Vue component name, and must be registered globally using [Theme.enhanceApp](../guide/custom-theme#theme-interface).

docs/en/reference/default-theme-search.md

@@ -194,6 +194,27 @@ export default defineConfig({
 })
 ```
 
+### Custom Local Search Box Item Component
+
+If you want to customize the search result items in the local search page, you can override the `LocalSearchBoxItem` component similarly:
+
+```js
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme';
+import CustomLocalSearchBoxItem from './components/CustomLocalSearchBoxItem.vue';
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    app.component('LocalSearchBoxItem', CustomLocalSearchBoxItem);
+  }
+};
+```
+
+#### Creating a Custom `LocalSearchBoxItem`
+
+To create your own `LocalSearchBoxItem`, define a Vue component that accepts a `content` prop and renders it inside a chosen HTML tag, such as a `<span>`. This allows you to control how search results are displayed while keeping the default functionality.
+
 ## Algolia Search
 
 VitePress supports searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Refer to their getting started guide. In your `.vitepress/config.ts` you'll need to provide at least the following to make it work:

src/client/app/components/LocalSearchBoxItem.ts

@@ -0,0 +1,13 @@
+import { defineComponent, h } from 'vue'
+
+export const LocalSearchBoxItem = defineComponent({
+  props: {
+    content: {
+      type: String,
+      required: true
+    }
+  },
+  render() {
+    return h('span', { innerHTML: this.content })
+  }
+})

src/client/app/components/SidebarTextItem.ts

@@ -0,0 +1,17 @@
+import { defineComponent, h } from 'vue'
+
+export const SidebarTextItem = defineComponent({
+  props: {
+    content: {
+      type: String,
+      required: true
+    },
+    is: {
+      type: [Object, String],
+      default: 'p'
+    }
+  },
+  render() {
+    return h(this.is, { innerHTML: this.content })
+  }
+})

src/client/app/composables/head.ts

@@ -57,9 +57,11 @@ export function useUpdateHead(route: Route, siteDataByRouteRef: Ref<SiteData>) {
     const frontmatterHead = (pageData && pageData.frontmatter.head) || []
 
     // update title and description
-    const title = createTitle(siteData, pageData)
-    if (title !== document.title) {
-      document.title = title
+    if (!siteData.themeConfig.skipTitleUpdate) {
+      const title = createTitle(siteData, pageData)
+      if (title !== document.title) {
+        document.title = title
+      }
     }
 
     const description = pageDescription || siteData.description

src/client/app/index.ts

@@ -18,6 +18,8 @@ import { usePrefetch } from './composables/preFetch'
 import { dataSymbol, initData, siteDataRef, useData } from './data'
 import { RouterSymbol, createRouter, scrollTo, type Router } from './router'
 import { inBrowser, pathToFile } from './utils'
+import { SidebarTextItem } from './components/SidebarTextItem'
+import { LocalSearchBoxItem } from './components/LocalSearchBoxItem'
 
 function resolveThemeExtends(theme: typeof RawTheme): typeof RawTheme {
   if (theme.extends) {
@@ -83,6 +85,8 @@ export async function createApp() {
   // install global components
   app.component('Content', Content)
   app.component('ClientOnly', ClientOnly)
+  app.component('SidebarTextItem', SidebarTextItem)
+  app.component('LocalSearchBoxItem', LocalSearchBoxItem)
 
   // expose $frontmatter & $params
   Object.defineProperties(app.config.globalProperties, {

src/client/theme-default/components/VPLocalSearchBox.vue

@@ -573,11 +573,11 @@ function onMouseMove(e: MouseEvent) {
                     :key="index"
                     class="title"
                   >
-                    <span class="text" v-html="t" />
+                    <LocalSearchBoxItem class="text" :content="t" />
                     <span class="vpi-chevron-right local-search-icon" />
                   </span>
                   <span class="title main">
-                    <span class="text" v-html="p.title" />
+                    <LocalSearchBoxItem class="text" :content="p.title" />
                   </span>
                 </div>
 

src/client/theme-default/components/VPSidebarItem.vue

@@ -64,9 +64,9 @@ function onItemClick() {
         :rel="item.rel"
         :target="item.target"
       >
-        <component :is="textTag" class="text" v-html="item.text" />
+        <SidebarTextItem :is="textTag" class="text" :content="item.text" />
       </VPLink>
-      <component v-else :is="textTag" class="text" v-html="item.text" />
+      <SidebarTextItem v-else :is="textTag" class="text" :content="item.text" />
 
       <button
         v-if="item.collapsed != null && item.items && item.items.length"

types/default-theme.d.ts

@@ -161,6 +161,11 @@ export namespace DefaultTheme {
      */
     skipToContentLabel?: string
 
+    /**
+     * @default false
+     */
+    skipTitleUpdate?: boolean
+
     search?:
       | { provider: 'local'; options?: LocalSearchOptions }
       | { provider: 'algolia'; options: AlgoliaSearchOptions }