diff --git a/docs/.vuepress/notes.ts b/docs/.vuepress/notes.ts index 4dc04907..cfc2f91c 100644 --- a/docs/.vuepress/notes.ts +++ b/docs/.vuepress/notes.ts @@ -62,7 +62,7 @@ export const zhNotes = definePlumeNotesConfig({ text: '自定义', icon: 'material-symbols:dashboard-customize-outline-rounded', collapsed: false, - items: ['自定义首页', '自定义样式'], + items: ['自定义首页', '自定义样式', '布局插槽', '组件覆写'], }, { text: 'API', @@ -97,7 +97,7 @@ export const zhNotes = definePlumeNotesConfig({ text: '内置插件', dir: 'plugins', collapsed: false, - items: ['', '代码高亮', '搜索', '阅读统计', 'markdown增强', 'markdownPower', '百度统计'], + items: ['', '代码高亮', '搜索', '阅读统计', 'markdown增强', 'markdownPower', '百度统计', '水印'], }, ], }, diff --git a/docs/notes/theme/config/frontmatter/basic.md b/docs/notes/theme/config/frontmatter/basic.md index 1779995a..96052ff0 100644 --- a/docs/notes/theme/config/frontmatter/basic.md +++ b/docs/notes/theme/config/frontmatter/basic.md @@ -22,60 +22,114 @@ permalink: /config/frontmatter/basic/ ## 配置 +### pageLayout + +- 类型： `false | 'home' | 'doc' | 'custom' | 'page' | 'friends' | string` +- 默认值： `doc` +- 详情： + + 页面布局方式。 + + - `'home'`: 主页布局 + - `'doc'`: 文章页布局，包括左侧侧边栏、文章内容、右侧侧边栏、导航栏、评论等 + - `'page'`: 仅包含导航栏 和 MD 文件内容，可以使用此布局方式自定义页面内容 + - `'friends'`: 友链页布局 + - `'custom'`: 仅包含 MD 文件内容，可以使用此布局方式完全自定义页面内容 + - `false`: 等同于 `custom` + - `string`: 可以传入一个全局组件组件名，该组件将被应用为布局组件 + +### pageClass + +- 类型： `string` +- 默认值： `''` +- 详情： + + 自定义页面额外的 类名。 + ### title -文章标题。 +- 类型： `string` +- 默认值： `''` +- 详情： -主题会在文件创建时，自动填充 当前文件名作为 文章标题。 + 文章标题。 + + 主题会在文件创建时，自动填充 当前文件名作为 文章标题。 ### author -文章作者。 +- 类型： `string` +- 默认值： `''` +- 详情： -主题会在文件创建时，自动填充 `avatar.name || packageJson.author` 作为 文章作者。 + 文章作者。 + + 主题会在文件创建时，自动填充 `avatar.name || packageJson.author` 作为 文章作者。 ### createTime -文章创建时间。 +- 类型： `string` +- 默认值： `''` +- 详情： -主题会在文件创建时，自动填充 当前时间作为 文章创建时间。 + 文章创建时间。 + + 主题会在文件创建时，自动填充 当前时间作为 文章创建时间。 ### permalink -文章永久链接。 +- 类型： `string` +- 默认值： `''` +- 详情： -主题会在文件创建时: + 文章永久链接。 -- 博客类型的文章，自动填充 `/article/` + `nanoid 生成的 6 位随机字符串` 作为 文章永久链接 -- notes 目录下的文章，会根据 notes 的配置，自动填充 文章永久链接 + 主题会在文件创建时: -### externalLink + - 博客类型的文章，自动填充 `/article/` + `nanoid 生成的 6 位随机字符串` 作为 文章永久链接 + - notes 目录下的文章，会根据 notes 的配置，自动填充 文章永久链接 + +### externalLinkIcon - 类型： `boolean` - 默认值： `true` +- 详情： -当前文章内的 外部链接是否显示 外部链接图标。 + 当前文章内的 外部链接是否显示 外部链接图标。 ### backToTop - 类型： `boolean` - 默认值： `true` +- 详情： -当前文章是否 显示 回到顶部 的按钮。 + 当前文章是否 显示 回到顶部 的按钮。 ### comments - 类型： `boolean` - 默认值： `true` +- 详情： -当前文章是否 可评论。 仅在启用了评论功能的情况下生效。 + 当前文章是否 可评论。 仅在启用了评论功能的情况下生效。 ### aside +- 类型： `boolean | 'left'` +- 默认值： `true` +- 详情： + + 当前文章是否 显示 右侧边栏。 + + 当设置为 `'left'` 时，右侧边栏将显示在左侧。 + +### navbar + - 类型： `boolean` - 默认值： `true` +- 详情： -当前文章是否 显示 右侧边栏。 + 当前文章是否 显示 导航栏。 ### outline @@ -95,69 +149,65 @@ permalink: /config/frontmatter/basic/ - 类型： `string | { text: string, link: string, icon?: string }` - 默认值： `''` +- 详情： -自定义当前文章的上一篇文章。 + 自定义当前文章的上一篇文章。 -- 博客类型的文章，主题根据时间排序，自动填充上一篇文章的标题和链接。 -- notes 类型的文章，主题根据 note sidebar 配置，自动填充上一篇文章的标题和链接。 + - 博客类型的文章，主题根据时间排序，自动填充上一篇文章的标题和链接。 + - notes 类型的文章，主题根据 note sidebar 配置，自动填充上一篇文章的标题和链接。 ### next - 类型： `string | { text: string, link: string, icon?: string }` - 默认值： `''` +- 详情： -自定义当前文章的下一篇文章。 + 自定义当前文章的下一篇文章。 -- 博客类型的文章，主题根据时间排序，自动填充下一篇文章的标题和链接。 -- notes 类型的文章，主题根据 note sidebar 配置，自动填充下一篇文章的标题和链接。 + - 博客类型的文章，主题根据时间排序，自动填充下一篇文章的标题和链接。 + - notes 类型的文章，主题根据 note sidebar 配置，自动填充下一篇文章的标题和链接。 ### readingTime - 类型： `boolean` - 默认值： `true` +- 详情： -当前文章是否 显示 阅读时长。 + 当前文章是否 显示 阅读时长。 ### lastUpdated - 类型： `boolean` - 默认值： `true` +- 详情： -当前文章是否 显示 最后更新时间。 最后更新时间 根据 git 提交时间自动填充。 + 当前文章是否 显示 最后更新时间。 最后更新时间 根据 git 提交时间自动填充。 ### contributors - 类型： `boolean` - 默认值： `true` +- 详情： -当前文章是否 显示 贡献者。 贡献者 根据 git 提交者自动填充。 + 当前文章是否 显示 贡献者。 贡献者 根据 git 提交者自动填充。 ### editLink - 类型： `boolean` - 默认值： `true` +- 详情： -当前文章是否 显示 文章编辑 按钮。 + 当前文章是否 显示 文章编辑 按钮。 ### watermark -- 类型： `boolean | WatermarkConfig` +- 类型： `boolean | WatermarkOptions` - 默认值： `undefined` 主题不启用水印，或不启用全局水印时，默认值为 `false`，启用全局水印则为 `true`。 +- 详情： + 配置当前文章 水印。 -配置当前文章 水印。 + 当类型为 boolean 时，表示是否启用水印。 -```ts -interface WatermarkConfig { - content?: string // 水印文字内容，可传入 html 内容 - textColor?: string // 水印文本颜色 - image?: string // 水印图片路径，优先于 content - opacity?: number // 水印透明度 - rotate?: number // 水印旋转角度 - width?: number // 水印宽度 - height?: number // 水印高度 - gapX?: number // 水印横向间距 - gapY?: number // 水印纵向间距 - fullPage?: boolean // 是否全屏 - onlyPrint?: boolean // 是否仅在打印时显示 -} -``` + 当类型为 WatermarkOptions 时，表示当前页面水印配置。 + + 可以参考 [watermark-js-plus](https://zhensherlock.github.io/watermark-js-plus/zh/config/) 。 diff --git a/docs/notes/theme/config/frontmatter/friend.md b/docs/notes/theme/config/frontmatter/friend.md index 900192ce..755d516c 100644 --- a/docs/notes/theme/config/frontmatter/friend.md +++ b/docs/notes/theme/config/frontmatter/friend.md @@ -13,7 +13,7 @@ permalink: /config/frontmatter/friends/ ```md --- -friends: true +pageLayout: friends title: 友情链接 list: - @@ -26,12 +26,20 @@ list: ## 配置 -### friends +### friends - 类型： `boolean` - 默认值： `false` +- 详情： -当前页面是否为友情链接页。 + 当前页面是否为友情链接页。 + +### pageLayout + +- 类型：`'friends'` +- 详情： + + 声明当前页面为 友情链接页。 ### title diff --git a/docs/notes/theme/config/frontmatter/home.md b/docs/notes/theme/config/frontmatter/home.md index c43062e5..d2447537 100644 --- a/docs/notes/theme/config/frontmatter/home.md +++ b/docs/notes/theme/config/frontmatter/home.md @@ -22,11 +22,21 @@ config: ## 配置 -### home +### home - 类型： `boolean` +- 详情： -声明是否为 首页 + 声明是否为 首页。 + + 已弃用，请使用 `pageLayout: 'home'` 代替。 + +### pageLayout + +- 类型：`'home'` +- 详情： + + 声明当前页面为 首页。 ### config diff --git a/docs/notes/theme/config/plugins/代码高亮.md b/docs/notes/theme/config/plugins/代码高亮.md index e16cc4fe..3a0e22d3 100644 --- a/docs/notes/theme/config/plugins/代码高亮.md +++ b/docs/notes/theme/config/plugins/代码高亮.md @@ -25,7 +25,7 @@ Shiki 支持多种编程语言。 - [代码对比差异](/guide/markdown/extensions/#代码块中的颜色差异) - [代码高亮“错误”和“警告”](/guide/markdown/extensions/#高亮-错误-和-警告) - [代码词高亮](/guide/markdown/extensions/#代码块中-词高亮) -- [twoslash](/guide/markdown/experiment/#twoslash) ，在代码块内提供内联类型提示。 +- [twoslash](/guide/markdown/experiment/#twoslash) ，在代码块内提供内联类型提示。 默认配置： diff --git a/docs/notes/theme/config/plugins/搜索.md b/docs/notes/theme/config/plugins/搜索.md index 2e446a47..e2da8505 100644 --- a/docs/notes/theme/config/plugins/搜索.md +++ b/docs/notes/theme/config/plugins/搜索.md @@ -73,7 +73,7 @@ interface SearchBoxLocale { 使用 [Algolia DocSearch](https://docsearch.algolia.com/) 提供支持的网站内容搜索插件 -关联插件：[@vuepress/plugin-docsearch](https://ecosystem.vuejs.press/zh/plugins/docsearch.html) +关联插件：[@vuepress/plugin-docsearch](https://ecosystem.vuejs.press/zh/plugins/search/docsearch.html) 查看 [Algolia DocSearch 参考](/guide/features/content-search/#algolia-docsearch) 获取更多信息。 diff --git a/docs/notes/theme/config/plugins/水印.md b/docs/notes/theme/config/plugins/水印.md new file mode 100644 index 00000000..83931748 --- /dev/null +++ b/docs/notes/theme/config/plugins/水印.md @@ -0,0 +1,80 @@ +--- +title: 水印 +author: Plume Theme +createTime: 2024/06/17 15:37:18 +permalink: /config/watermark/ +--- + +## 概述 + +主题内置的 水印插件，为 全站，或者 单个页面 添加水印。 + +关联插件：[@vuepress/plugin-watermark](https://ecosystem.vuejs.press/zh/plugins/features/watermark.html) + +## 配置项 + +### enabled + +- 类型： `boolean | ((page: Page) => boolean)` + +- 默认值： `false` + +- 详情： + + 指定哪些页面需要添加水印。 + + 拥有 `true` 值的页面将会被添加水印。 + +### watermarkOptions + +- 类型： `WatermarkOptions` + +- 默认值： `undefined` + +- 详情： 配置项请参考 [watermark-js-plus](https://zhensherlock.github.io/watermark-js-plus/zh/config/)。 + +#### watermarkOptions.parent + +- 类型： `string` + +- 默认值： `body` + +- 详情：添加水印的父元素选择器。 + + 默认插入到 body 中，可以指定插入到页面的某个元素中。 + +### delay + +- 类型： `number` + +- 默认值： `500` + +- 详情：添加水印的延时。以毫秒为单位。 + + 延迟时间取决于页面过渡动画时间，可以根据实际情况调整。 + + 如果水印的父元素在切换页面时被重新渲染，那么延迟时间应该比页面过渡时间长一些。 + +## Frontmatter + +### watermark + +- 类型: `boolean | WatermarkOptions` + +- 详情： + + 当类型为 `boolean` 时，表示是否启用水印。 + + 当类型为 `WatermarkOptions` 时，表示当前页面水印配置。 + + 可以参考 [watermark-js-plus](https://zhensherlock.github.io/watermark-js-plus/zh/config/) 。 + +```md +--- +watermark: + width: 200 + height: 200 + content: Your content + opacity: 0.5 +--- +``` diff --git a/docs/notes/theme/config/plugins/阅读统计.md b/docs/notes/theme/config/plugins/阅读统计.md index 9c513054..a6fa23d4 100644 --- a/docs/notes/theme/config/plugins/阅读统计.md +++ b/docs/notes/theme/config/plugins/阅读统计.md @@ -1,6 +1,6 @@ --- title: 阅读统计 -author: pengzhan +author: pengzhanbo createTime: 2024/03/06 15:23:39 permalink: /config/plugins/reading-time/ --- @@ -9,7 +9,7 @@ permalink: /config/plugins/reading-time/ 为每个页面生成字数统计与预计阅读时间。 -关联插件： [@vuepress/plugin-reading-time](https://ecosystem.vuejs.press/zh/plugins/reading-time.html) +关联插件： [@vuepress/plugin-reading-time](https://ecosystem.vuejs.press/zh/plugins/search/docsearch.html) 默认配置： diff --git a/docs/notes/theme/config/主题配置.md b/docs/notes/theme/config/主题配置.md index e461269c..ef07513e 100644 --- a/docs/notes/theme/config/主题配置.md +++ b/docs/notes/theme/config/主题配置.md @@ -142,25 +142,29 @@ interface BlogOptions { - 默认值： `'Appearance'` - 详情： 导航栏中的主题切换按钮的文本。 -### avatar +### avatar -- 类型： `PlumeThemeAvatar` +弃用，请使用 [profile](#profile)。 + +### profile + +- 类型： `PlumeThemeProfile` - 默认值： `{}` - 详情：配置站点博主的个人信息 - - `avatar.url`: 头像地址，用于右侧博主信息展示 - - `avatar.name`: 名称， 用于右侧博主信息展示 - - `avatar.description`: 个人描述，用于右侧博主信息展示 - - `avatar.circle`: 是否为圆形头像 - - `avatar.location`: 用户地理位置 - - `avatar.organization`: 用户所在组织/公司 + - `profile.avatar`: 头像地址，用于右侧博主信息展示 + - `profile.name`: 名称， 用于右侧博主信息展示 + - `profile.description`: 个人描述，用于右侧博主信息展示 + - `profile.circle`: 是否为圆形头像 + - `profile.location`: 用户地理位置 + - `profile.organization`: 用户所在组织/公司 示例： ``` ts export default { theme: themePlume({ - avatar: { - url: '/avatar.jpg', + profile: { + avatar: '/avatar.jpg', name: '张三', description: '此处无银三百两，隔壁王二不曾偷', circle: true, @@ -400,12 +404,6 @@ type NavItem = string | { 移动设备下的导航栏中大纲标题的文字 -### repo - -- 类型： `string` -- 默认值： `''` -- 详情： 仓库配置 - ### editLink - 类型： `boolean` @@ -509,78 +507,3 @@ interface NotFound { linkText?: string } ``` - -### watermark - -- 类型： `boolean | WatermarkOptions` -- 默认值： `false` -- 详情： 文章水印配置 - -```ts -interface WatermarkOptions { - /** - * 是否全局启用, 在不全局启用时，可以通过 `frontmatter.watermark` 为当前页面启用 - * @default false - */ - global?: boolean - /** - * 非全局启用时，可以通过该字段根据文件路径或页面链接 进行匹配， 来启用水印。 - * 以 `^` 的将被认为为类似于正则表达式进行匹配。 - */ - matches?: string | string[] - /** - * 水印之间的水平间隔 - * @default 0 - */ - gapX?: number - /** - * 水印之间的垂直间隔 - * @default 0 - */ - gapY?: number - - /** - * 图片水印的内容，如果与 content 同时传入，优先使用图片水印 - */ - image?: PlumeThemeImage - /** - * 水印宽度 - * @default 100 - */ - width?: number - /** - * 水印高度 - * @default 100 - */ - height?: number - /** - * 水印旋转角度 - * @default -22 - */ - rotate?: number - /** - * 水印的内容，如果与 image 同时传入，优先使用图片水印 - */ - content?: string - /** - * 水印是否全屏显示 - */ - fullPage?: boolean - /** - * 水印透明度 - * @default 0.1 - */ - opacity?: number - - /** - * 水印的文本颜色 - */ - textColor?: string | { dark: string, light: string } - - /** - * 是否只在打印时显示 - * @default false - */ - onlyPrint?: boolean -} -``` diff --git a/docs/notes/theme/guide/api-客户端.md b/docs/notes/theme/guide/api-客户端.md index 5710bcec..7c62ba35 100644 --- a/docs/notes/theme/guide/api-客户端.md +++ b/docs/notes/theme/guide/api-客户端.md @@ -9,32 +9,119 @@ permalink: /guide/api/client/ ## 使用 ```ts -import { useDarkMode } from 'vuepress-theme-plume/client' +import { Layout } from 'vuepress-theme-plume/client' ``` -## `useDarkMode()` +## 布局组件 -- 类型： `() => Ref` - -Composable `useDarkMode()` 用于获取当前的 `dark` 状态。 +- ``： 页面布局组件 +- `` ： 404 页面布局组件 ```ts -import { useDarkMode } from 'vuepress-theme-plume/client' - -const isDark = useDarkMode() +import { Layout, NotFound } from 'vuepress-theme-plume/client' ``` -## `` +## 通用组件 -- 类型：`Component` +- `` ： 链接组件 +- ``: 按钮组件 +- ``: 图标组件 +- ``: 徽标组件 +- ``: 图片组件 +- ``: 首页布局组件 -自定义首页时，提供给 区域 的 包装容器。 +更多其他组件请查看 [源代码](https://github.com/pengzhanbo/vuepress-theme-plume/tree/main/theme/src/client/components) -### Props +```ts +import VPLink from 'vuepress-theme-plume/components/VPLink.vue' +import VPButton from 'vuepress-theme-plume/components/VPButton.vue' +``` -| 名称 | 类型 | 默认值 | 说明 | -| --------------------- | ------------------ | --------- | ---------------- | -| type | string | `''` | 区域类型 | -| full | boolean | `false` | 是否全屏 | -| background-image | string | `''` | 区域背景图片 | -| background-attachment | `'fixed'\|'local'` | `'local'` | 区域背景定位方式 | +## 组合式 API + +### `useDarkMode()` + +- 类型： `() => Ref` +- 详情： + + 获取 是否是深色模式的响应式数据。 + +```ts +import { useDarkMode } from 'vuepress-theme-plume/composables' + +const isDark = useDarkMode() + +// 切换为深色模式 +isDark.value = true +// 切换为浅色模式 +isDark.value = false +``` + +### `useData()` + +- 类型： `() => Data` +- 详情： + + 获取 主题 的各项响应式数据。 + +```ts +interface Data { + // 主题配置 + theme: ThemeLocaleDataRef + // 当前页面数据 + page: PageDataRef + // 当前 页面 frontmatter + frontmatter: PageFrontmatterRef> + // 当前语言 + lang: Ref + // 站点数据 + site: SiteLocaleDataRef + // 是否是深色模式 + isDark: Ref +} +``` + +```ts +import { useData } from 'vuepress-theme-plume/composables' + +const { site, page, frontmatter, isDark, lang } = useData() + +// 当前页面标题 +console.log(frontmatter.value.title) +``` + +### `useLocalePostList()` + +- 类型： `() => Ref` +- 详情： + + 获取 文章列表的响应式数据。 + +```ts +interface PostItem { + path: string + title: string + excerpt: string + tags: string[] + sticky: boolean + categoryList: CategoryItem[] + createTime: string + lang: string + encrypt?: boolean +} + +interface CategoryItem { + type: string | number + name: string +} +``` + +```ts +import { useLocalePostList } from 'vuepress-theme-plume/composables' + +const postList = useLocalePostList() +``` + +### 更多 + +其它 组合式 API 请查看 [源代码](https://github.com/pengzhanbo/vuepress-theme-plume/tree/main/theme/src/client/composables) 。 diff --git a/docs/notes/theme/guide/功能/组件.md b/docs/notes/theme/guide/功能/组件.md index 459e1df0..05d10baa 100644 --- a/docs/notes/theme/guide/功能/组件.md +++ b/docs/notes/theme/guide/功能/组件.md @@ -3,6 +3,7 @@ title: 组件 author: pengzhanbo icon: radix-icons:component-2 createTime: 2024/03/06 09:42:42 +outline: 2 permalink: /guide/features/component/ --- @@ -16,12 +17,10 @@ permalink: /guide/features/component/ ### Props -- `type` - - 类型： `'info' | 'tip' | 'warning' | 'danger'` - - 默认值：`'tip'` -- `text` - - 类型：`string` - - 默认值：`''` +| 名称 | 类型 | 默认值 | 说明 | +| ---- | ------------------------------------------ | ------- | ---- | +| type | `'info' \| 'tip' \| 'warning' \| 'danger'` | `'tip'` | 类型 | +| text | `string` | `''` | 文本 | **输入：** @@ -47,15 +46,11 @@ permalink: /guide/features/component/ ### Props -- `name` - - 类型：`string` - - 默认值：`''` -- `color` - - 类型：`string` - - 默认值：`'currentColor'` -- `size` - - 类型：`string` - - 默认值：`'1em'` +| 名称 | 类型 | 默认值 | 说明 | +| ----- | ------ | ---------------- | ---------- | +| name | string | `''` | icon name | +| color | string | `'currentcolor'` | icon color | +| size | string | `'1em'` | icon size | **输入：** @@ -96,20 +91,11 @@ export default defineUserConfig({ ### Props -- `trigger` - - 类型：`'hover' | 'click'` - - 默认值：`'hover'` - - 描述：鼠标悬停触发，或者点击触发 - -- `mask` - - 类型：`string | { light: string, dark: string }` - - 默认值：`#000` - - 描述：遮罩颜色 - -- `color` - - 类型：`string | { light: string, dark: string }` - - 默认值：`#fff` - - 描述：文本颜色 +| 名称 | 类型 | 默认值 | 说明 | +| ------- | ------------------------------------------- | --------- | -------------------------- | +| trigger | `'hover' \| 'click'` | `'hover'` | 鼠标悬停触发，或者点击触发 | +| mask | `string \| { light: string, dark: string }` | `#000` | 遮罩颜色 | +| color | `string \| { light: string, dark: string }` | `#fff` | 文本颜色 | 输入： @@ -122,3 +108,18 @@ export default defineUserConfig({ - 鼠标悬停 - 悬停时可见 - 点击 - 点击时可见 + +## `` + +- 类型：`Component` + +自定义首页时，提供给 区域 的 包装容器。 + +### Props + +| 名称 | 类型 | 默认值 | 说明 | +| --------------------- | ------------------ | --------- | ---------------- | +| type | string | `''` | 区域类型 | +| full | boolean | `false` | 是否全屏 | +| background-image | string | `''` | 区域背景图片 | +| background-attachment | `'fixed'\|'local'` | `'local'` | 区域背景定位方式 | diff --git a/docs/notes/theme/guide/博客.md b/docs/notes/theme/guide/博客.md index 474872a9..c529b4a0 100644 --- a/docs/notes/theme/guide/博客.md +++ b/docs/notes/theme/guide/博客.md @@ -6,6 +6,10 @@ createTime: 2024/03/04 19:16:40 permalink: /guide/blog/ --- + + ## 概述 主题默认启用 博客功能，通常您无需进行额外的配置。 @@ -23,15 +27,18 @@ permalink: /guide/blog/ ## 博主信息 -主题允许你展示博主的基本信息。 +主题支持展示博主的基本信息。 -::: center -![avatar](/images/blogger-avatar.png){style="max-width:250px;"} -::: +
+ +
### 配置 -你可以通过 `avatar` 属性来设置博主头像等相关信息。 +你可以通过 `profile` 属性来设置博主头像等相关信息。 ::: code-tabs @tab .vuepress/config.ts @@ -39,10 +46,10 @@ permalink: /guide/blog/ ```ts export default defineUserConfig({ theme: plumeTheme({ - avatar: { - url: '/blogger.png', - name: 'Your name', - description: 'Your description', + profile: { + name: '你的名字', + description: '描述文字', + avatar: '/blogger.png', circle: true, // 是否为圆形头像 } }) diff --git a/docs/notes/theme/guide/安装与使用.md b/docs/notes/theme/guide/安装与使用.md index 7c412da4..030fc3d9 100644 --- a/docs/notes/theme/guide/安装与使用.md +++ b/docs/notes/theme/guide/安装与使用.md @@ -95,7 +95,7 @@ npm i -D vuepress-theme-plume @vuepress/bundler-vite@next ::: :::warning -主题当前版本 已适配至 `vuepress@2.0.0-rc.9`，你应该安装这个版本的 VuePress。 +主题当前版本 已适配至 `vuepress@2.0.0-rc.13`，你应该安装这个版本的 VuePress。 高于或低于这个版本，可能会存在潜在的兼容性问题。 ::: diff --git a/docs/notes/theme/guide/布局插槽.md b/docs/notes/theme/guide/布局插槽.md new file mode 100644 index 00000000..10add777 --- /dev/null +++ b/docs/notes/theme/guide/布局插槽.md @@ -0,0 +1,127 @@ +--- +title: 布局插槽 +icon: ph:layout-duotone +author: Plume Theme +createTime: 2024/06/17 16:19:43 +permalink: /guide/layout-slots/ +--- + +## 概述 + +主题通过 `` 提供了 丰富的 布局插槽，可以通过这些插槽，在 页面 的不同位置注入内容。 +以便用户可以个性化的使用主题。 + +## 使用 + +首先，需要创建一个 客户端配置文件： `.vuepress/client.ts`: + +```ts +import { defineClientConfig } from 'vuepress/client' +import Layout from './layouts/Layout.vue' + +export default defineClientConfig({ + layouts: { + Layout, + }, +}) +``` + +然后，创建一个 `.vuepress/layouts/Layout.vue`，作为布局插槽的默认组件，在该组件中引入 当前主题的 `` 组件。 + +```vue + + + + + +``` + +也可以使用 渲染函数 实现注入内容，在 `.vuepress/client.ts` 中： + +```ts +import { defineClientConfig } from 'vuepress/client' +import { h } from 'vue' +import { Layout } from 'vuepress-theme-plume/client' +import CustomContent from './components/CustomContent.vue' + +export default defineClientConfig({ + layouts: { + Layout: () => h(Layout, null, { + 'page-bottom': () => h(CustomContent), + }), + }, +}) +``` + +## 插槽 + +主题支持以下插槽： + +- 当 `pageLayout: doc` 时： + + - `doc-top` + - `doc-bottom` + - `doc-footer-before` + - `doc-before` + - `doc-after` + - `sidebar-nav-before` + - `sidebar-nav-after` + - `aside-top` + - `aside-bottom` + - `aside-outline-before` + - `aside-outline-after` + +- 当 `pageLayout: page` 时： + + - `page-top` + - `page-bottom` + +- 在 博客页 中 （包括 文章列表页、标签页、归档页 均适用）： + + - `blog-top` + - `blog-bottom` + - `blog-aside-top` + - `blog-aside-bottom` + - `blog-extract-before` + - `blog-extract-after` + +- 在 博客文章列表页 中： + + - `blog-post-list-before` + - `blog-post-list-after` + - `blog-post-list-pagination-after` + +- 在 博客标签页 中： + + - `blog-tags-before` + - `blog-tags-after` + +- 在 博客归档页 中： + + - `blog-archives-before` + - `blog-archives-after` + +- 总是启用： + + - `layout-top` + - `layout-bottom` + - `nav-bar-title-before` + - `nav-bar-title-after` + - `nav-bar-content-before` + - `nav-bar-content-after` + - `nav-screen-content-before` + - `nav-screen-content-after` diff --git a/docs/notes/theme/guide/组件覆写.md b/docs/notes/theme/guide/组件覆写.md new file mode 100644 index 00000000..a32da440 --- /dev/null +++ b/docs/notes/theme/guide/组件覆写.md @@ -0,0 +1,43 @@ +--- +title: 组件覆写 +icon: carbon:cics-sit-overrides +author: Plume Theme +createTime: 2024/06/17 16:20:15 +permalink: /guide/component-overrides/ +--- + +## 概述 + +布局插槽十分实用，但有时候你可能会觉得它不够灵活。主题同样提供了单个组件覆写的能力。 + +::: warning +在使用此功能前，你应该首先熟悉本主题的源代码，了解 主题内置的各个组件，以便 安全的 覆写他们。 + +主题的组件源代码托管在 [GitHub](https://github.com/pengzhanbo/vuepress-theme-plume/tree/main/theme/src/client/components)，遵循 MIT 协议。 +::: + +## 使用 + +主题将所有 非全局的组件 都注册了一个带 `@theme` 前缀的 [alias](https://v2.vuepress.vuejs.org/zh/reference/plugin-api.html#alias) 。 +例如，`VPFooter.vue` 的别名是 `@theme/VPFooter.vue` 。 + +如果你想要覆写 `VPFooter.vue` 组件，只需要在配置文件 `.vuepress/config.ts` 中覆盖这个别名即可： + +```ts +import { plumeTheme } from 'vuepress-theme-plume' +import { getDirname, path } from 'vuepress/utils' +import { defineUserConfig } from 'vuepress' + +const __dirname = getDirname(import.meta.url) + +export default defineUserConfig({ + theme: plumeTheme(), + + alias: { + '@theme/VPFooter.vue': path.resolve( + __dirname, + './components/MyFooter.vue', + ), + }, +}) +``` diff --git a/docs/notes/theme/guide/自定义首页.md b/docs/notes/theme/guide/自定义首页.md index 4a6dda50..68746677 100644 --- a/docs/notes/theme/guide/自定义首页.md +++ b/docs/notes/theme/guide/自定义首页.md @@ -250,6 +250,21 @@ config: 进行可视化操作，生成配置内容，你可以直接复制它们用于自己的项目中。 ::: +主题还支持自定义 `name`, `tagline`， `text` 的颜色。 + +通过 `CSS Vars` 进行配置。 + +```css +/* 默认设置，可以在 `index.css` 中覆盖 */ +:root { + /* home hero name 背景色，通过背景色裁剪的方式定义文本颜色， + 因此，可以设置渐变背景的方式使文本根据表现力 */ + --vp-bg-home-hero-name: linear-gradient(315deg, var(--vp-c-purple-1) 15%, var(--vp-c-brand-2) 65%, var(--vp-c-brand-2) 100%); + --vp-c-home-hero-tagline: var(--vp-c-text-2); + --vp-c-home-hero-text: var(--vp-c-text-3); +} +``` + ### features - 类型： `PlumeThemeHomeFeatures`