diff --git a/docs/en/reference/default-theme-config.md b/docs/en/reference/default-theme-config.md index 33760375..409aa03f 100644 --- a/docs/en/reference/default-theme-config.md +++ b/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` diff --git a/docs/en/reference/default-theme-nav.md b/docs/en/reference/default-theme-nav.md index 02caac41..dabae948 100644 --- a/docs/en/reference/default-theme-nav.md +++ b/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). diff --git a/docs/en/reference/default-theme-search.md b/docs/en/reference/default-theme-search.md index e497d84c..ff57155a 100644 --- a/docs/en/reference/default-theme-search.md +++ b/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 ``. 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: 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 c6238f43..85ba3a6f 100644 --- a/src/client/app/composables/head.ts +++ b/src/client/app/composables/head.ts @@ -57,9 +57,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 a15e0684..aeb6f590 100644 --- a/src/client/app/index.ts +++ b/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, { diff --git a/src/client/theme-default/components/VPLocalSearchBox.vue b/src/client/theme-default/components/VPLocalSearchBox.vue index af727577..c0953915 100644 --- a/src/client/theme-default/components/VPLocalSearchBox.vue +++ b/src/client/theme-default/components/VPLocalSearchBox.vue @@ -573,11 +573,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 28ce0628..0d6a4f6c 100644 --- a/src/client/theme-default/components/VPSidebarItem.vue +++ b/src/client/theme-default/components/VPSidebarItem.vue @@ -64,9 +64,9 @@ function onItemClick() { :rel="item.rel" :target="item.target" > - + - +