diff --git a/docs/en/reference/default-theme-config.md b/docs/en/reference/default-theme-config.md index cc4ffd0ed..e173d1b05 100644 --- a/docs/en/reference/default-theme-config.md +++ b/docs/en/reference/default-theme-config.md @@ -477,6 +477,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 01ff20903..c02286352 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 3c3fc41bc..662a04da2 100644 --- a/docs/en/reference/default-theme-search.md +++ b/docs/en/reference/default-theme-search.md @@ -189,6 +189,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 000000000..f2a1c4c9c --- /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 000000000..d482367c5 --- /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 13fb9bb0a..7a18724dc 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 178c98b1f..6d94c11c3 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 709ca1375..1486658b7 100644 --- a/src/client/theme-default/components/VPLocalSearchBox.vue +++ b/src/client/theme-default/components/VPLocalSearchBox.vue @@ -572,11 +572,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 d71d10621..8ec7f1ead 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" > - + - +