diff --git a/docs/en/reference/default-theme-config.md b/docs/en/reference/default-theme-config.md index 39c3fcf7..b64686f8 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 b55a63cb..ff579021 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 6bc2f446..2df1323b 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 00000000..f2a1c4c9 --- /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 00000000..d482367c --- /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 13fb9bb0..7a18724d 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 1f1e8069..7524fa5a 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 825a22b5..5323c471 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 d71d1062..8ec7f1ea 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" > - + - +