vitepress-plugin-breadcrumbs

Динамические «хлебные крошки» в стиле VitePress, построенные по положению текущей страницы в сайдбаре. Не делает предположений о структуре контента — подходит для любого VitePress-проекта.

Установка

npm install @ampernic/vitepress-plugin-breadcrumbs

Концепция

Полная цепочка крошек собирается так:

prefix  →  home  →  группы-предки из сайдбара  →  текущая страница

1. Каждый элемент цепочки несёт ссылку.
2. Текущей становится последняя крошка цепочки, чья ссылка совпадает с текущим маршрутом (поэтому индекс/лендинг документа показывает собственную крошку как текущую); иначе текущая страница добавляется отдельным элементом.
3. Идущие подряд крошки с одинаковой ссылкой схлопываются (дедуп).
4. hideSingle затем скрывает одиночную крошку (например, на «голом» лендинге).

Сайдбар-путь ищется в themeConfig.sidebar (поддерживаются массив, SidebarMulti и группы { base, items }). Если страница в сайдбаре не найдена и fallback: 'path', крошки выводятся из сегментов URL.

Использование

Добавьте компонент в слот лейаута (обычно doc-before, над заголовком страницы):

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import { h } from 'vue'
import Breadcrumbs from '@ampernic/vitepress-plugin-breadcrumbs/components/Breadcrumbs.vue'

export default {
  extends: DefaultTheme,
  Layout: () =>
    h(DefaultTheme.Layout, null, {
      'doc-before': () => h(Breadcrumbs),
    }),
}

Конфигурация

Глобально через themeConfig.breadcrumbs либо попропсово (пропсы важнее конфига, конфиг важнее значений по умолчанию). Конфиг можно типизировать через defineBreadcrumbsConfig:

// .vitepress/config.ts
import { defineBreadcrumbsConfig } from '@ampernic/vitepress-plugin-breadcrumbs'

export default {
  themeConfig: {
    breadcrumbs: defineBreadcrumbsConfig({
      home: 'auto',
      separator: '›',
      hideSingle: true,
      fallback: 'path',
    }),
  },
}

Опция	По умолчанию	Описание
home	false	Крошка-корень документа (ведёт на лендинг/индекс документа). false — нет; { text, link? } — статическая (ссылка по умолчанию = вычисленный лендинг); 'auto' — ссылка на лендинг, текст = homeText ?? заголовок сайта ?? slug базы; (ctx) => ({ text, link? }) | false — резолвер из BreadcrumbHomeCtx. На самой индексной странице рендерится как текущая (без ссылки) крошка.
homeText	заголовок сайта	Текст для home: 'auto'
prefix	false	Крошки-предки перед home (например, кросс-секционный корень сайта и/или лендинг дистрибутива). BreadcrumbHome[] или (ctx) => BreadcrumbHome[]. Крошка prefix, чья ссылка совпала с текущей страницей, становится текущей; подряд идущие дубли по ссылке схлопываются.
showOnHome	false	Рендерить и на страницах layout: home / когда нет контекста документа — чтобы prefix показывал крошки на корне сайта и лендингах
separator	'/'	Разделитель между крошками
showCurrentPage	true	Добавлять текущую страницу последней (без ссылки) крошкой
hideSingle	true	Ничего не рендерить, если крошек ≤ 1
fallback	'none'	'path' — выводить крошки из URL, если страницы нет в сайдбаре; 'none' — не рендерить
class	—	Доп. класс на корневой <nav>
ariaLabel	'Breadcrumb'	ARIA-метка для landmark

Отключить на конкретной странице через frontmatter:

---
breadcrumbs: false
---

Контекст резолвера

Функции home/prefix получают BreadcrumbHomeCtx:

Поле	Описание
path	Сырой путь маршрута
segs	Сегменты пути без базы
base	База сайта ('/', '/alt-server/', …)
distro	Slug базы ('alt-server'); '' если база '/'
version	Первый сегмент, если он похож на версию (1.2, 1.2.3, p11)
sidebarBase	Вычисленная база сайдбара ('/11.1/' или '')
landing	Ссылка на лендинг/индекс документа (база сайта + база сайдбара)
siteTitle	Заголовок сайта из themeConfig
pageTitle	Заголовок текущей страницы

Пример — многоуровневая цепочка (корень сайта → лендинг дистрибутива → индекс документа → путь по сайдбару → текущая страница):

import type { BreadcrumbHomeCtx } from '@ampernic/vitepress-plugin-breadcrumbs'

breadcrumbs: defineBreadcrumbsConfig({
  showOnHome: true,
  hideSingle: false,
  home: (c: BreadcrumbHomeCtx) =>
    c.distro
      ? { text: c.version ? `${c.distro} ${c.version}` : c.distro, link: c.landing }
      : false,
  prefix: (c: BreadcrumbHomeCtx) => {
    const arr = [{ text: 'Главная', link: '/' }]
    if (c.distro && c.version) arr.push({ text: c.distro, link: `/${c.distro}/` })
    return arr
  },
})

Стилизация

Стили scoped, используют CSS-переменные VitePress. Доступны стабильные классы для переопределения: .vp-breadcrumbs, .vp-breadcrumbs-list, .vp-breadcrumbs-item, .vp-breadcrumbs-link, .vp-breadcrumbs-current, .vp-breadcrumbs-sep.

Лицензия

GPL-3.0-or-later