diff --git a/docs/en/reference/default-theme-config.md b/docs/en/reference/default-theme-config.md index c8afc5544a4d..7c42ee8c00ad 100644 --- a/docs/en/reference/default-theme-config.md +++ b/docs/en/reference/default-theme-config.md @@ -451,6 +451,13 @@ Can be used to customize the aria-label of the language toggle button in 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` diff --git a/docs/en/reference/default-theme-nav.md b/docs/en/reference/default-theme-nav.md index b55a63cb1b5e..ff579021d84f 100644 --- a/docs/en/reference/default-theme-nav.md +++ b/docs/en/reference/default-theme-nav.md @@ -161,6 +161,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). diff --git a/docs/en/reference/default-theme-search.md b/docs/en/reference/default-theme-search.md index d647e32ed252..9bae9ce7903a 100644 --- a/docs/en/reference/default-theme-search.md +++ b/docs/en/reference/default-theme-search.md @@ -187,6 +187,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 ``. 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 their getting started guide. In your `.vitepress/config.ts` you'll need to provide at least the following to make it work: diff --git a/src/client/app/components/LocalSearchBoxItem.ts b/src/client/app/components/LocalSearchBoxItem.ts new file mode 100644 index 000000000000..f2a1c4c9ca9a --- /dev/null +++ b/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 }) + } +}) diff --git a/src/client/app/components/SidebarTextItem.ts b/src/client/app/components/SidebarTextItem.ts new file mode 100644 index 000000000000..d482367c5518 --- /dev/null +++ b/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 }) + } +}) diff --git a/src/client/app/composables/head.ts b/src/client/app/composables/head.ts index 13fb9bb0a256..7a18724dcb1c 100644 --- a/src/client/app/composables/head.ts +++ b/src/client/app/composables/head.ts @@ -56,9 +56,11 @@ export function useUpdateHead(route: Route, siteDataByRouteRef: Ref) { 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 diff --git a/src/client/app/index.ts b/src/client/app/index.ts index 1f1e8069597b..7524fa5ac329 100644 --- a/src/client/app/index.ts +++ b/src/client/app/index.ts @@ -17,6 +17,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) { @@ -78,6 +80,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, { diff --git a/src/client/theme-default/components/VPLocalSearchBox.vue b/src/client/theme-default/components/VPLocalSearchBox.vue index b348de54659f..54e4e12445b3 100644 --- a/src/client/theme-default/components/VPLocalSearchBox.vue +++ b/src/client/theme-default/components/VPLocalSearchBox.vue @@ -526,11 +526,11 @@ function onMouseMove(e: MouseEvent) { :key="index" class="title" > - + - + diff --git a/src/client/theme-default/components/VPSidebarItem.vue b/src/client/theme-default/components/VPSidebarItem.vue index 022584e31d6e..112c2377c481 100644 --- a/src/client/theme-default/components/VPSidebarItem.vue +++ b/src/client/theme-default/components/VPSidebarItem.vue @@ -77,9 +77,9 @@ function onCaretClick() { :rel="item.rel" :target="item.target" > - + - +