add document for breadcrumbs plugin (#330)

LemonNekoGH · web-flow · commit 573383da698c · 2024-11-18T22:42:57.000+08:00
diff --git a/README.md b/README.md
@@ -86,6 +86,7 @@ To find out the integration name, there is a list of integrations below.
 - [UnoCSS (for Obsidian)](https://github.com/nolebase/obsidian-plugin-unocss)
 - [Auto Sidebar (for VitePress)](./packages/vitepress-plugin-sidebar/README.md)
 - [Bi-Directional Links (for `markdown-it`)](./packages/markdown-it-bi-directional-links/README.md)
+- [Breadcrumbs (for VitePress)](./packages/vitepress-plugin-breadcrumbs/README.md)
 - [Elements Transformation (for `markdown-it`)](./packages/markdown-it-element-transform/README.md)
 - [Lazy loading blurred thumbnails (for `markdown-it`)](./packages/markdown-it-unlazy-img/README.md)
 - [Enhanced Readabilities (for VitePress)](./packages/vitepress-plugin-enhanced-readabilities/README.md)
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -85,6 +85,7 @@ ni @nolebase/<integration-name> -D
 - [UnoCSS (Obsidian 插件)](https://github.com/nolebase/obsidian-plugin-unocss)
 - [自动生成侧边栏（VitePress 插件）](./packages/vitepress-plugin-sidebar/README.md)
 - [双向链接（`markdown-it` 插件）](./packages/markdown-it-bi-directional-links/README.md)
+- [面包屑导航（VitePress 插件）](./packages/vitepress-plugin-breadcrumbs/README.md)
 - [元素转换（`markdown-it` 插件）](./packages/markdown-it-element-transform/README.md)
 - [懒加载模糊预览图（`markdown-it` 插件）](./packages/markdown-it-unlazy-img/README.md)
 - [阅读增强（VitePress 插件）](./packages/vitepress-plugin-enhanced-readabilities/README.md)
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -54,6 +54,7 @@ export const sidebars: Record<string, DefaultTheme.Sidebar> = {
         text: 'VitePress Plugins',
         items: [
           { text: 'Auto Sidebar', link: '/pages/en/integrations/vitepress-plugin-sidebar/' },
+          { text: 'Breadcrumbs', link: '/pages/en/integrations/vitepress-plugin-breadcrumbs/' },
           { text: 'Enhanced Readabilities', link: '/pages/en/integrations/vitepress-plugin-enhanced-readabilities/' },
           { text: 'Index Page', link: '/pages/en/integrations/vitepress-plugin-index/' },
           {
@@ -185,6 +186,7 @@ export const sidebars: Record<string, DefaultTheme.Sidebar> = {
         text: 'VitePress 插件',
         items: [
           { text: '自动生成侧边栏', link: '/pages/zh-CN/integrations/vitepress-plugin-sidebar/' },
+          { text: '面包屑导航', link: '/pages/zh-CN/integrations/vitepress-plugin-breadcrumbs/' },
           { text: '阅读增强', link: '/pages/zh-CN/integrations/vitepress-plugin-enhanced-readabilities/' },
           { text: '索引页', link: '/pages/zh-CN/integrations/vitepress-plugin-index/' },
           {
diff --git a/docs/pages/en/index.md b/docs/pages/en/index.md
@@ -40,6 +40,7 @@ nolebase:
 <script setup>
 import sidebarPackageJSON from '~/packages/vitepress-plugin-sidebar/package.json'
 import biDirectionalLinksPackageJSON from '~/packages/markdown-it-bi-directional-links/package.json'
+import breadcrumbsPackageJSON from '~/packages/vitepress-plugin-breadcrumbs/package.json'
 import elementTransform from '~/packages/markdown-it-element-transform/package.json'
 import unlazyImg from '~/packages/markdown-it-unlazy-img/package.json'
 import enhancedReadabilities from '~/packages/vitepress-plugin-enhanced-readabilities/package.json'
@@ -82,6 +83,12 @@ Nólëbase Integrations project provides a variety of integrations, plugins, com
     </template>
   </IntegrationCard>
 
+  <IntegrationCard type="vitepress" title="Breadcrumbs" package="vitepress-plugin-breadcrumbs">
+    <template v-slot:badge>
+      <Badge type="tip" :text="`v${breadcrumbsPackageJSON.version}`" />
+    </template>
+  </IntegrationCard>
+
   <IntegrationCard type="vitepress" title="Enhanced Readabilities" package="vitepress-plugin-enhanced-readabilities">
     <template v-slot:badge>
       <Badge type="tip" :text="`v${enhancedReadabilities.version}`" />
diff --git a/docs/pages/en/integrations/index.md b/docs/pages/en/integrations/index.md
@@ -6,6 +6,7 @@ category: Index
 <script setup>
 import sidebarPackageJSON from '~/packages/vitepress-plugin-sidebar/package.json'
 import biDirectionalLinksPackageJSON from '~/packages/markdown-it-bi-directional-links/package.json'
+import breadcrumbsPackageJSON from '~/packages/vitepress-plugin-breadcrumbs/package.json'
 import elementTransform from '~/packages/markdown-it-element-transform/package.json'
 import unlazyImg from '~/packages/markdown-it-unlazy-img/package.json'
 import enhancedReadabilities from '~/packages/vitepress-plugin-enhanced-readabilities/package.json'
@@ -57,6 +58,14 @@ Nólëbase Integrations project provides a variety of integrations, plugins, com
 
 <br />
 
+<IntegrationCard type="vitepress" title="Breadcrumbs" package="vitepress-plugin-breadcrumbs">
+  <template v-slot:badge>
+    <Badge type="tip" :text="`v${breadcrumbsPackageJSON.version}`" />
+  </template>
+</IntegrationCard>
+
+<br />
+
 <IntegrationCard type="vitepress" title="Enhanced Readabilities" package="vitepress-plugin-enhanced-readabilities">
   <template v-slot:badge>
     <Badge type="tip" :text="`v${enhancedReadabilities.version}`" />
diff --git a/docs/pages/en/integrations/vitepress-plugin-breadcrumbs/index.md b/docs/pages/en/integrations/vitepress-plugin-breadcrumbs/index.md
@@ -0,0 +1,151 @@
+---
+title: Breadcrumbs
+category: Breadcrumbs
+---
+
+<script setup>
+import packageJSON from '~/packages/vitepress-plugin-breadcrumbs/package.json'
+</script>
+
+# Breadcrumbs <Badge type="tip" :text="`v${packageJSON.version}`" />
+
+## Installation
+
+Install `@nolebase/vitepress-plugin-breadcrumbs` to your project dependencies by running the following command:
+
+::: code-group
+
+```shell [@antfu/ni]
+ni @nolebase/vitepress-plugin-breadcrumbs
+```
+
+```shell [pnpm]
+pnpm add @nolebase/vitepress-plugin-breadcrumbs
+```
+
+```shell [npm]
+npm install @nolebase/vitepress-plugin-breadcrumbs
+```
+
+```shell [yarn]
+yarn add @nolebase/vitepress-plugin-breadcrumbs
+```
+
+```shell [bun]
+bun install @nolebase/vitepress-plugin-breadcrumbs
+```
+
+:::
+
+## Configuration
+
+### Integrate with VitePress
+
+In the VitePress configuration file (usually `docs/.vitepress/config.ts`, the file path and extension may be different), import `@nolebase/vitepress-plugin-breadcrumbs`, and put it into `transformPageData` function:
+
+<!--@include: @/pages/en/snippets/details-colored-diff.md-->
+
+<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
+
+```typescript twoslash
+import { defineConfig } from 'vitepress'
+import { generateBreadcrumbsData } from '@nolebase/vitepress-plugin-breadcrumbs' // [!code ++]
+
+export default defineConfig({
+  // Other configurations...
+  transformPageData(pageData, context) { // [!code ++]
+    generateBreadcrumbsData(pageData, context) // [!code ++]
+  }, // [!code ++]
+})
+
+```
+
+Then please add the Breadcrumbs plugin package name `@nolebase/vitepress-plugin-breadcrumbs` into the Vite options that required by VitePress to process this plugin:
+
+<!--@include: @/pages/en/snippets/details-colored-diff.md-->
+
+<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
+
+```typescript twoslash
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  vite: { // [!code ++]
+    optimizeDeps: { // [!code ++]
+      exclude: [ // [!code ++]
+        '@nolebase/vitepress-plugin-breadcrumbs/client' // [!code ++]
+      ] // [!code ++]
+    }, // [!code ++]
+    ssr: { // [!code ++]
+      noExternal: [ // [!code ++]
+        // If there are other packages that need to be processed by Vite, you can add them
+        '@nolebase/vitepress-plugin-breadcrumbs' // [!code ++]
+      ]// [!code ++]
+    } // [!code ++]
+  }, // [!code ++]
+  // Other configurations...
+})
+```
+
+### Add plugin into the Theme options of VitePress
+
+In VitePress's [**theme configuration file**](https://vitepress.dev/reference/default-theme-config#default-theme-config) (note that it's not a **configuration file**, it's usually located at `docs/.vitepress/theme/index.ts`, file paths and extensions may be vary), import `@nolebase/vitepress-plugin-breadcrumbs` package and add it to the `Layout` section as a slot:
+
+<!--@include: @/pages/en/snippets/details-colored-diff.md-->
+
+<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
+
+::: code-group
+
+```typescript twoslash [docs/.vitepress/theme/index.ts]
+import type { Theme as ThemeConfig } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import { h } from 'vue'
+
+import { NolebaseBreadcrumbs } from '@nolebase/vitepress-plugin-breadcrumbs/client' // [!code ++]
+
+export const Theme: ThemeConfig = {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // Add breadcrumb above document
+      'doc-before': () => h(NolebaseBreadcrumbs), // [!code ++]
+    })
+  }
+}
+
+export default Theme
+```
+
+:::
+
+## Use custom breadcrumbs component
+
+If you don't like the style or other something of default breadcrumb component, you can create your own component, this plugin will inject breadcrumb data into `frontmatter` of the page, so you can use breadcrumb data like this:
+
+```vue
+<script setup lang="ts">
+import { useData } from 'vitepress'
+
+const { frontmatter } = useData()
+
+console.log(frontmatter.breadcrumbs)
+// and do something other...
+</script>
+
+<template>
+  <div>
+    <!-- ui of your own component -->
+  </div>
+</template>
+```
+
+The `breadcrumbs` property is an array:
+
+```typescript
+type Breadcrumbs = {
+  title: string
+  link: string
+}[]
+```
+
+If there isn't a `index.md` in the directory, the `link` will be an empty string `""`
diff --git a/docs/pages/en/integrations/vitepress-plugin-sidebar/index.md b/docs/pages/en/integrations/vitepress-plugin-sidebar/index.md
@@ -37,7 +37,7 @@ yarn add @nolebase/vitepress-plugin-sidebar -D
 
 ### Integrate with VitePress
 
-In the VitePress configuration file (usually `docs/.vitepress/config.ts`, the file path and extension may be different), import `@nolebase/markdown-it-bi-directional-links` as a plugin, and use it as a `markdown-it` plugin in the `markdown` option:
+In the VitePress configuration file (usually `docs/.vitepress/config.ts`, the file path and extension may be different), import `@nolebase/vitepress-plugin-sidebar` as a plugin:
 
 <!--@include: @/pages/en/snippets/details-colored-diff.md-->
 
diff --git a/docs/pages/zh-CN/integrations/vitepress-plugin-breadcrumbs/index.md b/docs/pages/zh-CN/integrations/vitepress-plugin-breadcrumbs/index.md
@@ -0,0 +1,151 @@
+---
+title: 面包屑导航
+category: 面包屑导航
+---
+
+<script setup>
+import packageJSON from '~/packages/vitepress-plugin-breadcrumbs/package.json'
+</script>
+
+# 面包屑导航 <Badge type="tip" :text="`v${packageJSON.version}`" />
+
+## 安装
+
+你可以通过下面的指令将 `@nolebase/vitepress-plugin-breadcrumbs` 安装到你的项目依赖中：
+
+::: code-group
+
+```shell [@antfu/ni]
+ni @nolebase/vitepress-plugin-breadcrumbs
+```
+
+```shell [pnpm]
+pnpm add @nolebase/vitepress-plugin-breadcrumbs
+```
+
+```shell [npm]
+npm install @nolebase/vitepress-plugin-breadcrumbs
+```
+
+```shell [yarn]
+yarn add @nolebase/vitepress-plugin-breadcrumbs
+```
+
+```shell [bun]
+bun install @nolebase/vitepress-plugin-breadcrumbs
+```
+
+:::
+
+## 使用
+
+### 为 VitePress 配置
+
+在 VitePress 的配置文件中（通常为 `docs/.vitepress/config.ts`，文件路径和拓展名也许会有区别），将 `@nolebase/vitepress-plugin-breadcrumbs` 导入并且将它放置到 `transformPageData` 函数中：
+
+<!--@include: @/pages/zh-CN/snippets/details-colored-diff.md-->
+
+<!--@include: @/pages/zh-CN/snippets/configure-tsconfig.md-->
+
+```typescript twoslash
+import { defineConfig } from 'vitepress'
+import { generateBreadcrumbsData } from '@nolebase/vitepress-plugin-breadcrumbs' // [!code ++]
+
+export default defineConfig({
+  // 其它各种配置...
+  transformPageData(pageData, context) { // [!code ++]
+    generateBreadcrumbsData(pageData, context) // [!code ++]
+  }, // [!code ++]
+})
+
+```
+
+将面包屑导航到的插件包 `@nolebase/vitepress-plugin-breadcrumbs` 添加到需要 VitePress 底层的 Vite 帮忙处理的依赖：
+
+<!--@include: @/pages/zh-CN/snippets/details-colored-diff.md-->
+
+<!--@include: @/pages/zh-CN/snippets/configure-tsconfig.md-->
+
+```typescript twoslash
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  vite: { // [!code ++]
+    optimizeDeps: { // [!code ++]
+      exclude: [ // [!code ++]
+        '@nolebase/vitepress-plugin-breadcrumbs/client' // [!code ++]
+      ] // [!code ++]
+    }, // [!code ++]
+    ssr: { // [!code ++]
+      noExternal: [ // [!code ++]
+        // 如果还有别的依赖需要添加的话，并排填写和配置到这里即可
+        '@nolebase/vitepress-plugin-breadcrumbs' // [!code ++]
+      ]// [!code ++]
+    } // [!code ++]
+  }, // [!code ++]
+  // 其它的配置
+})
+```
+
+### 添加 VitePress 主题相关的配置
+
+在 VitePress 的[**主题配置文件**](https://vitepress.dev/reference/default-theme-config#default-theme-config)中（注意不是**配置文件**，通常为 `docs/.vitepress/theme/index.ts`，文件路径和拓展名也许会有区别），**将 `@nolebase/vitepress-plugin-breadcrumbs` 导入，并且将其添加到 `Layout` 的拓展中**：
+
+<!--@include: @/pages/zh-CN/snippets/details-colored-diff.md-->
+
+<!--@include: @/pages/zh-CN/snippets/configure-tsconfig.md-->
+
+::: code-group
+
+```typescript twoslash [docs/.vitepress/theme/index.ts]
+import type { Theme as ThemeConfig } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import { h } from 'vue'
+
+import { NolebaseBreadcrumbs } from '@nolebase/vitepress-plugin-breadcrumbs/client' // [!code ++]
+
+export const Theme: ThemeConfig = {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // 将面包屑导航组件添加到文档上方
+      'doc-before': () => h(NolebaseBreadcrumbs), // [!code ++]
+    })
+  }
+}
+
+export default Theme
+```
+
+:::
+
+## 使用自定义的面包屑导航插件
+
+如果你不喜欢默认的面包屑导航组件的样式或者别的东西，你可以创建一个自己的足迹，插件会将生成的面包屑数据注入到页面的 `frontmatter` 中去，所以你可以这样使用它：
+
+```vue
+<script setup lang="ts">
+import { useData } from 'vitepress'
+
+const { frontmatter } = useData()
+
+console.log(frontmatter.breadcrumbs)
+// 做一些其它的事情
+</script>
+
+<template>
+  <div>
+    <!-- 你自己的组件 UI -->
+  </div>
+</template>
+```
+
+`breadcrumbs` 属性是一个数组：
+
+```typescript
+type Breadcrumbs = {
+  title: string
+  link: string
+}[]
+```
+
+如果某个文件夹中不存在 `index.md` ，`link` 属性将会是空字符串 `""`
diff --git a/packages/vitepress-plugin-breadcrumbs/README.md b/packages/vitepress-plugin-breadcrumbs/README.md
diff --git a/packages/vitepress-plugin-breadcrumbs/package.json b/packages/vitepress-plugin-breadcrumbs/package.json
