breadcrumb

[pclokcer]

Is your feature request related to a problem? Please describe.

nope

Describe the solution you'd like

I want to breadcrumb like this.

Describe alternatives you've considered

No response

Additional context

No response

Validations

• Follow our Code of Conduct
• Read the docs.
• Read the Contributing Guidelines.
• Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.

[brc-dd]

You can use one of our layouts slots to add a breadcrumbs component there.

[pclokcer]

You can use one of our layouts slots to add a breadcrumbs component there.

this is temporary solve. I dont want to custom component

[ruslan-onishchenko]

+1

[peterbe]

You can use one of our layouts slots to add a breadcrumbs component there.

That would be cool! Do we have any examples of that?
In my case, I don't really have control over the .md files that I put into the source directory.
My site uses:

cp -r ../some-other-repo/docs .
npm run build:docs

[brc-dd]

@peterbe Do your markdown files have some data in frontmatter that can tell their breadcrumb path? Asking because the final part of breadcrumb can be inferred from title, but not the other parts. Otherwise you'll need to maintain a list of data yourself 👀

Regarding layout slots, they are added via theme - https://vitepress.dev/guide/extending-default-theme#layout-slots - you can use doc-top/doc-before probably.

[peterbe]

Do your markdown files have some data in frontmatter that can tell their breadcrumb path? Asking because the final part of breadcrumb can be inferred from title, but not the other parts. Otherwise you'll need to maintain a list of data yourself 👀

It does not know about where it lives. All an individual file knows is that it's parent directory is called my-cool-directory but it doesn't know that the title for that directory should be My Coolio Dir (for example).

I'm trying to learn about https://vitepress.dev/guide/data-loading#createcontentloader and how it could make it possible to retroactive attach these. Still new to this :)

[brc-dd]

If you can maintain an object like this:

const names = {
  'my-cool-directory': 'My Cool Dir',
  ...
}

You can use https://vitepress.dev/reference/site-config#transformpagedata to do something like this:

// .vitepress/config.ts

export default defineConfig({
  transformPageData(pageData) {
    pageData.frontmatter.breadcrumbs = [...pageData.relativePath.split('/').slice(0, -1).map(x => names[x]), pageData.title]
  }
})

And then use this data in your vue component:

https://stackblitz.com/edit/vite-rqxgjj

[yanranxiaoxi]

@pclokcer

Here's the Breadcrumb component I made on my website. (All license under MIT)

Add a .vitepress/theme/components/Breadcrumb.vue file that looks like this:

<script setup lang="ts">
import { DefaultTheme, onContentUpdated, useData, withBase } from 'vitepress';
import { useSidebar } from 'vitepress/theme';
import { Ref, ref } from 'vue';

const { frontmatter, page } = useData();
const { sidebar } = useSidebar();
const breadcrumbHtml: Ref<string> = ref('');
const gtSvg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256"><polygon points="79.093,0 48.907,30.187 146.72,128 48.907,225.813 79.093,256 207.093,128"/></svg>`;

if (frontmatter.value.breadcrumb === true || typeof frontmatter.value.breadcrumb === 'object') {
	function resolveFilePath(filePath: string): string {
		if (!filePath.startsWith('/')) {
			filePath = '/' + filePath;
		}
		if (filePath.endsWith('.md')) {
			filePath = filePath.slice(0, filePath.length - 3);
		}
		if (filePath.endsWith('/index')) {
			filePath = filePath.slice(0, filePath.length - 5);
		}
		return filePath;
	}

	let breadcrumbItems: Array<{ text?: string; link?: string }> = [];
	function resolveMatchedLink(filePath: string, items: Array<DefaultTheme.SidebarItem>): true | undefined {
		for (const item of items) {
			breadcrumbItems.push({ text: item.text, link: item.link });
			if (item.link === filePath) {
				return true;
			} else if (item.items && item.items.length >= 1) {
				if (resolveMatchedLink(filePath, item.items)) {
					return true;
				}
			}
			breadcrumbItems = breadcrumbItems.slice(0, breadcrumbItems.length - 1);
		}
		return;
	}

	const generateBreadcrumb = (): void => {
		const filePath = resolveFilePath(page.value.filePath);
		breadcrumbItems = [];
		if (typeof frontmatter.value.breadcrumb === 'object') {
			if (frontmatter.value.breadcrumb.homeLink) {
				breadcrumbItems.push({ text: frontmatter.value.breadcrumb.homeText || '🏠', link: frontmatter.value.breadcrumb.homeLink });
			}
		}
		resolveMatchedLink(filePath, sidebar.value);
		let breadcrumbHtmlStr = '';
		if (breadcrumbItems.length >= 2) {
			for (const [index, breadcrumbItem] of breadcrumbItems.entries()) {
				if (breadcrumbItem.link && index < breadcrumbItems.length - 1) {
					breadcrumbHtmlStr += `<div class="breadcrumb-item"><span><a href="${withBase(breadcrumbItem.link) + (breadcrumbItem.link.endsWith('/') ? '' : '.html')}">${breadcrumbItem.text}</a></span></div>`;
				} else if (index === breadcrumbItems.length - 1) {
					breadcrumbHtmlStr += '<div class="breadcrumb-item breadcrumb-item-current"><span>' + breadcrumbItem.text + '</span></div>';
				} else {
					breadcrumbHtmlStr += '<div class="breadcrumb-item"><span>' + breadcrumbItem.text + '</span></div>';
				}
				if (index < breadcrumbItems.length - 1) {
					breadcrumbHtmlStr += `<div class="breadcrumb-symbol">${gtSvg}</div>`;
				}
			}
		}
		breadcrumbHtml.value = breadcrumbHtmlStr;
	};
	generateBreadcrumb();

	onContentUpdated(generateBreadcrumb);
}
</script>

<template>
	<div class="breadcrumb" v-if="frontmatter.breadcrumb" v-html="breadcrumbHtml"></div>
</template>

<style>
.breadcrumb {
	margin-bottom: 20px;
	display: block;
}

.breadcrumb .breadcrumb-item {
	display: inline-block;
	align-content: center;
	font-size: small; /* 13px */
	padding-top: 3px;
	padding-bottom: 3px;
	padding-left: 12px;
	padding-right: 12px;
	border-radius: 20px;
}

.breadcrumb .breadcrumb-item:has(a):hover {
	background-color: var(--vp-custom-block-info-bg);
	color: var(--vp-c-brand-1);
}

.breadcrumb .breadcrumb-item span a {
	font-weight: 500;
	transition:
		color 0.25s,
		opacity 0.25s;
	touch-action: manipulation;
}

.breadcrumb .breadcrumb-item-current {
	background-color: var(--vp-custom-block-info-bg);
}

.breadcrumb .breadcrumb-item-current span {
	color: var(--vp-c-brand-1);
}

.breadcrumb .breadcrumb-symbol {
	display: inline-block;
	padding-left: 7px;
	padding-right: 7px;
	opacity: 0.5;
	height: 9px;
	width: 22px;
	fill: var(--vp-c-text-2);
}

@media (max-width: 640px) {
	.breadcrumb {
		display: none;
	}
}
</style>

Then add the following to the .vitepress/theme/index.ts:

import type { Theme } from 'vitepress';
import DefaultTheme from 'vitepress/theme';

import Breadcrumb from './components/Breadcrumb.vue';

export default {
	extends: DefaultTheme,
	Layout: DefaultTheme.Layout() {
		return h(DefaultTheme.Layout, null, {
			'doc-before': () => h(Breadcrumb),
		});
	},
} satisfies Theme;

Then you'll need to add frontmatter to each page where you want to add Breadcrumb:

breadcrumb: true

If you want to add a custom homepage:

breadcrumb:
	homeText: 🏠
	homeLink: /home

If you want to enable Breadcrumb by default, editor Breadcrumb.vue:

if (frontmatter.value.breadcrumb === true || typeof frontmatter.value.breadcrumb === 'object') {
	// some code...
}

This can be achieved by changing frontmatter.value.breadcrumb === true to frontmatter.value.breadcrumb !== false.

After perfecting everything in the future, I will make it as a Vitepress Plugin. But now you can use it by following the instructions above.