yuany3721/vuepress-theme-plume
1
0
Fork 0
forked from gitea-yuany3721/vuepress-theme-plume
Code Pull Requests Activity

docs: improve docs

Browse Source
This commit is contained in:
pengzhanbo 2024-08-19 01:33:36 +08:00
parent 27fdc6943b
commit e3b1c3cc53
23 changed files with 455 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/.vuepress/notes.ts
View File

@ -1,6 +1,6 @@
import { definePlumeNotesConfig } from 'vuepress-theme-plume'
import { defineNotesConfig } from 'vuepress-theme-plume'
export const zhNotes = definePlumeNotesConfig({
export const zhNotes = defineNotesConfig({
dir: 'notes',
link: '/',
notes: [
@ -61,12 +61,14 @@ export const zhNotes = definePlumeNotesConfig({
icon: 'lucide:box',
collapsed: false,
prefix: '功能',
items: ['图标', '代码复制', '内容搜索', '评论', '加密', '组件', '文章水印', '友情链接页', 'seo', 'sitemap', {
text: '非内置功能',
icon: 'system-uicons:box-add',
collapsed: true,
items: ['repoCard', 'npmBadge'],
}],
items: ['图标', '代码复制', '内容搜索', '评论', '加密', '文章水印', '友情链接页', 'seo', 'sitemap'],
},
{
text: '组件',
prefix: '组件',
icon: 'uiw:component',
collapsed: false,
items: ['徽章', '图标', '隐秘文本', '卡片', '链接卡片', '图片卡片', '卡片容器', '首页布局容器', 'repoCard', 'npmBadge'],
},
{
text: '自定义',
@ -155,7 +157,7 @@ export const zhNotes = definePlumeNotesConfig({
],
})
export const enNotes = definePlumeNotesConfig({
export const enNotes = defineNotesConfig({
dir: 'en/notes',
link: '/',
notes: [],

12
docs/1.示例/markdown扩展.md
View File

@ -27,20 +27,28 @@ tags:
内部和外部链接都会被特殊处理。
主题默认对每个 md 文件自动生成一个新的 链接，并保存在对应的 md 文件的 frontmatter 的 `permalink` 中。
你可以随时修改它们。
你可以随时修改它们。你也可以通过 `theme.autoFrontmatter` 选项来禁用这个功能，这时会恢复为 VuePress 的默认行为。
### 内部链接
建议使用 生成的 `permalink` 作为内部链接的目标。
有三种方式来使用内部链接：
- 使用 生成的 `permalink` 作为内部链接的目标。
- 使用 md 文件的相对路径作为内部链接的目标。
- 使用 md 文件的绝对路径作为内部链接的目标， 绝对路径 `/` 表示从 `${sourceDir}` 目录开始。
```md
[Markdown](/guide/markdown/)
[Markdown](./markdown基础.md)
```
渲染为：
[Markdown](/guide/markdown/)
[Markdown](./markdown基础.md)
#### 外部链接
外部链接带有 `target="_blank" rel="noreferrer"` ：

2
docs/notes/plugins/netlify-functions/介绍.md
View File

@ -58,4 +58,4 @@ permalink: /plugins/plugin-netlify-functions/introduction/
并且将 所有 functions 添加在 vuepress 的构建包中。
如何使用插件，请查看 [使用文档](/plugins/plugin-netlify-functions/usage/)
如何使用插件，请查看 [使用文档](./使用.md)

2
docs/notes/theme/config/frontmatter/home.md
View File

@ -66,4 +66,4 @@ interface PlumeHomeConfigBase {
}
```
更多详细配置请参考 [自定义首页](/guide/custom-home/)
更多详细配置请参考 [自定义首页](../../guide/自定义首页.md)

2
docs/notes/theme/config/plugins/markdownPower.md
View File

@ -40,4 +40,4 @@ export default defineUserConfig({
## 配置
查看 [文档](/plugins/plugin-md-power/)
查看 [文档](../../../plugins/md-power.md)

4
docs/notes/theme/config/主题配置.md
View File

@ -26,7 +26,7 @@ permalink: /config/basic/
对主题内部使用的插件进行自定义配置。
主题使用的插件默认已进行了配置，大多数情况下您不需要进行修改，如果需要使用到细致的定制化，请查阅
[此文档](/config/plugins/)
[此文档](./plugins/README.md)
::: warning
该字段不支持在 [主题配置文件 `plume.config.js`](./配置说明.md#主题配置文件) 中进行配置。
@ -189,7 +189,7 @@ interface BlogOptions {
- 默认值： `{}`
- 详情： 多语言配置
多语言配置，参考 [此文档](/config/locales/)
多语言配置，参考 [此文档](./多语言配置.md)
多语言配置支持以下 [Locale](#locale-配置) 所有配置选项

12
docs/notes/theme/guide/markdown/扩展.md
View File

@ -28,20 +28,28 @@ tags:
内部和外部链接都会被特殊处理。
主题默认对每个 md 文件自动生成一个新的 链接，并保存在对应的 md 文件的 frontmatter 的 `permalink` 中。
你可以随时修改它们。
你可以随时修改它们。你也可以通过 `theme.autoFrontmatter` 选项来禁用这个功能，这时会恢复为 VuePress 的默认行为。
### 内部链接
建议使用 生成的 `permalink` 作为内部链接的目标。
有三种方式来使用内部链接：
- 使用 生成的 `permalink` 作为内部链接的目标。
- 使用 md 文件的相对路径作为内部链接的目标。
- 使用 md 文件的绝对路径作为内部链接的目标， 绝对路径 `/` 表示从 `${sourceDir}` 目录开始。
```md
[Markdown](/guide/markdown/)
[Markdown](./基础.md)
```
渲染为：
[Markdown](/guide/markdown/)
[Markdown](./基础.md)
### 外部链接
外部链接带有 `target="_blank" rel="noreferrer"` ：

2
docs/notes/theme/guide/markdown/进阶.md
View File

@ -580,7 +580,7 @@ export default defineUserConfig({
@[caniuse](feature)
```
为了方便使用，主题提供了工具支持：[caniuse 特性搜索](/tools/caniuse/)，你可以直接使用该工具
为了方便使用，主题提供了工具支持：[caniuse 特性搜索](../../../tools/caniuse.md)，你可以直接使用该工具
帮助生成 markdown 代码。
### 语法

8
docs/notes/theme/guide/代码/介绍.md
View File

@ -86,11 +86,11 @@ export default defineUserConfig({
## 更多支持
得益于 [Shiki](https://shiki.style/) 的强大能力，Theme Plume 还为 代码块
提供了 更多的 [特性支持](/guide/code/features/)，它们让 代码块具备更强的表达能力。
提供了 更多的 [特性支持](./特性支持.md)，它们让 代码块具备更强的表达能力。
同时，为了方便 更好的 完成 代码演示，Theme Plume 还提供了嵌入 [CodePen](/guide/code/code-pen/)，
[Js Fiddle](/guide/code/jsfiddle/)，[Code Sandbox](/guide/code/code-sandbox/)，
[Replit](/guide/code/replit/) 的语法支持，你可以很方便的嵌入代码演示。
同时，为了方便 更好的 完成 代码演示，Theme Plume 还提供了嵌入 [CodePen](../代码演示/codepen.md)，
[Js Fiddle](../代码演示/jsFiddle.md)，[Code Sandbox](../代码演示/codeSandbox.md)，
[Replit](../代码演示/replit.md) 的语法支持，你可以很方便的嵌入代码演示。
## 示例

2
docs/notes/theme/guide/功能/友情链接页.md
View File

@ -44,4 +44,4 @@ list:
### 配置
查看 [文档](/config/frontmatter/friends/) 更多配置信息。
查看 [文档](../../config/frontmatter/friend.md) 更多配置信息。

13
docs/notes/theme/guide/功能/组件.md
View File

@ -326,16 +326,3 @@ export default defineUserConfig({
<LinkCard title="链接卡片" href="/" />
<LinkCard icon="twemoji:astonished-face" title="链接卡片" href="/" />
</CardGrid>
## 首页布局容器
自定义首页时，使用 `<HomeBox>`提供给 区域 的 包装容器。
### Props
| 名称 | 类型 | 默认值 | 说明 |
| --------------------- | ------------------ | --------- | ---------------- |
| type | string | `''` | 区域类型 |
| full | boolean | `false` | 是否全屏 |
| background-image | string | `''` | 区域背景图片 |
| background-attachment | `'fixed'\|'local'` | `'local'` | 区域背景定位方式 |

2
docs/notes/theme/guide/知识笔记.md
View File

@ -78,4 +78,4 @@ export default defineUserConfig({
:::
完整配置查看 [notes配置](/config/notes/)
完整配置查看 [notes配置](../config/notes配置.md)

2
docs/notes/theme/guide/功能/npmBadge.md → docs/notes/theme/guide/组件/npmBadge.md
View File

@ -3,7 +3,7 @@ title: Npm 徽章
author: pengzhanbo
icon: akar-icons:npm-fill
createTime: 2024/07/26 22:07:23
permalink: /guide/npm-badge/
permalink: /guide/components/npm-badge/
---
<script setup>

2
docs/notes/theme/guide/功能/repoCard.md → docs/notes/theme/guide/组件/repoCard.md
View File

@ -3,7 +3,7 @@ title: Repo 卡片
author: pengzhanbo
icon: octicon:repo-16
createTime: 2024/07/26 21:11:56
permalink: /guide/github-repo-card/
permalink: /guide/components/github-repo-card/
---
<script setup>

57
docs/notes/theme/guide/组件/卡片.md Normal file
View File

@ -0,0 +1,57 @@
---
title: 卡片
author: pengzhanbo
icon: solar:card-broken
createTime: 2024/08/18 23:09:07
permalink: /guide/components/cark/
---
## 概述
使用 `<Card>` 组件在页面中显示卡片。
也可以使用 markdown [卡片容器](/guide/markdown/advance/#卡片) 语法，替代 `<Card>` 组件。
## Props
| 名称 | 类型 | 默认值 | 说明 |
| ----- | --------------------------- | ------ | ---------------------------------------------------------------- |
| title | `string` | `''` | 标题 |
| icon | `string \| { svg: string }` | `''` | 显示在标题左侧的图标，支持 iconify 所有图标，也可以使用 图片链接 |
## 插槽
| 名称 | 说明 |
| ------- | ---------- |
| default | 卡片内容 |
| title | 自定义标题 |
## 示例
**输入：**
```md :no-line-numbers
<Card title="卡片标题" icon="twemoji:astonished-face">
这里是卡片内容。
</Card>
<Card>
<template #title>
<p style="color: red">卡片标题</p>
</template>
这里是卡片内容。
</Card>
```
**输出：**
<Card title="卡片标题" icon="twemoji:astonished-face">
这里是卡片内容。
</Card>
<Card>
<template #title>
<p style="color: red;margin:0">卡片标题</p>
</template>
这里是卡片内容。
</Card>

64
docs/notes/theme/guide/组件/卡片容器.md Normal file
View File

@ -0,0 +1,64 @@
---
title: 卡片容器
author: pengzhanbo
icon: vaadin:grid-h
createTime: 2024/08/18 23:38:33
permalink: /guide/components/card-grid/
---
## 概述
当你需要将多个卡片排列，可以使用 `<CardGrid>` 组件。在空间足够时，多个卡片会自动排列。
## Props
| 名称 | 类型 | 默认值 | 说明 |
| :--- | :----------------------------------------------- | :----- | :------------- |
| cols | `number \| Record<'sm' \| 'md' \| 'lg', number>` | `2` | 卡片排列列数。 |
组件默认会根据屏幕宽度自动调整列数。在空间足够时，默认显示双列，小屏幕下显示单列。
你可以通过 `cols` 配置列数。当传入 `number` 时，所有尺寸均显示为 `number` 个卡片。
传入 `{ sm: number, md: number, lg: number }` 时，根据屏幕宽度自动调整列数。
- `sm` : `< 768px`
- `md` : `>= 768px < 960px`
- `lg` : `>= 960px`
建议传入的 `number` 不超过 `3`。
## 示例
**输入：**
```md :no-line-numbers
<CardGrid>
<Card title="卡片标题" icon="twemoji:astonished-face">
这里是卡片内容。
</Card>
<Card title="卡片标题" icon="twemoji:astonished-face">
这里是卡片内容。
</Card>
</CardGrid>
<CardGrid>
<LinkCard title="卡片标题" href="/" />
<LinkCard icon="twemoji:astonished-face" title="卡片标题" href="/" />
</CardGrid>
```
**输出：**
<CardGrid>
<Card title="卡片标题" icon="twemoji:astonished-face">
这里是卡片内容。
</Card>
<Card title="卡片标题" icon="twemoji:astonished-face">
这里是卡片内容。
</Card>
</CardGrid>
<CardGrid>
<LinkCard title="链接卡片" href="/" />
<LinkCard icon="twemoji:astonished-face" title="链接卡片" href="/" />
</CardGrid>

37
docs/notes/theme/guide/组件/图标.md Normal file
View File

@ -0,0 +1,37 @@
---
title: 图标
author: pengzhanbo
icon: grommet-icons:emoji
createTime: 2024/08/18 22:58:39
permalink: /guide/components/icon/
---
## 概述
支持 iconify 所有图标，通过 icon name 加载图标。
可在 [iconify search](https://icon-sets.iconify.design/) 搜索图标使用。
## Props
| 名称 | 类型 | 默认值 | 说明 |
| ----- | ------ | ---------------- | -------- |
| name | string | `''` | 图标名 |
| color | string | `'currentcolor'` | 图标颜色 |
| size | string | `'1em'` | 图标大小 |
## 示例
**输入：**
```md :no-line-numbers
- home - <Icon name="material-symbols:home" color="currentColor" size="1em" />
- vscode - <Icon name="skill-icons:vscode-dark" size="2em" />
- twitter - <Icon name="skill-icons:twitter" size="2em" />
```
**输出：**
- home - <Icon name="material-symbols:home" color="currentColor" size="1em" />
- vscode - <Icon name="skill-icons:vscode-dark" size="2em" />
- twitter - <Icon name="skill-icons:twitter" size="2em" />

99
docs/notes/theme/guide/组件/图片卡片.md Normal file
View File

@ -0,0 +1,99 @@
---
title: 图片卡片
author: pengzhanbo
icon: fa:photo
createTime: 2024/08/18 23:35:51
permalink: /guide/components/image-card/
---
## 概述
使用 `<ImageCard>` 组件在页面中显示图片卡片。
图片卡片 有别于 markdown 的 普通插入图片方式，它展示与图片相关的更多信息，包括标题、描述、作者、链接等。
适用于如 摄影作品、设计作品、宣传海报 等场景。
## Props
| 名称 | 类型 | 默认值 | 说明 |
| ----------- | -------------------------- | ------ | --------------------------------------- |
| image | `string` | `''` | 必填，图片链接 |
| title | `string` | `''` | 可选，标题 (展示其它信息需要依赖此属性) |
| description | `string` | `''` | 可选，描述 |
| author | `string` | `''` | 可选，作者 |
| href | `string` | `''` | 可选，链接 |
| date | `string \| Date \| number` | `''` | 可选，日期 |
## 示例
**输入：**
```md :no-line-numbers
<ImageCard
image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
description="今天照片中的灯塔位于葡萄牙南部海岸阿尔加维的卡沃埃罗。阿尔凡齐纳灯塔建于1919年，照耀着大海，帮助船只在该地区周围危险的水域航行。这座灯塔是著名的旅游胜地，同时也是该地区与海洋紧密联系的象征。如果你有幸住在灯塔附近，那么本周末就是拜访灯塔的最佳时机。"
href="/"
author="Andreas Kunz"
date="2024/08/16"
/>
```
**输出：**
<ImageCard
image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
description="今天照片中的灯塔位于葡萄牙南部海岸阿尔加维的卡沃埃罗。阿尔凡齐纳灯塔建于1919年，照耀着大海，帮助船只在该地区周围危险的水域航行。这座灯塔是著名的旅游胜地，同时也是该地区与海洋紧密联系的象征。如果你有幸住在灯塔附近，那么本周末就是拜访灯塔的最佳时机。"
href="/"
author="Andreas Kunz"
date="2024/08/16"
/>
还可以放到 `<CardGrid>` 组件中。
**输入：**
```md :no-line-numbers
<CardGrid>
<ImageCard
image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
description="..."
href="/"
author="Andreas Kunz"
date="2024/08/16"
/>
<ImageCard
image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
description="..."
href="/"
author="Andreas Kunz"
date="2024/08/16"
/>
</CardGrid>
```
**输出：**
<CardGrid>
<ImageCard
image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
description="今天照片中的灯塔位于葡萄牙南部海岸阿尔加维的卡沃埃罗。阿尔凡齐纳灯塔建于1919年，照耀着大海，帮助船只在该地区周围危险的水域航行。这座灯塔是著名的旅游胜地，同时也是该地区与海洋紧密联系的象征。如果你有幸住在灯塔附近，那么本周末就是拜访灯塔的最佳时机。"
href="/"
author="Andreas Kunz"
date="2024/08/16"
/>
<ImageCard
image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
description="今天照片中的灯塔位于葡萄牙南部海岸阿尔加维的卡沃埃罗。阿尔凡齐纳灯塔建于1919年，照耀着大海，帮助船只在该地区周围危险的水域航行。这座灯塔是著名的旅游胜地，同时也是该地区与海洋紧密联系的象征。如果你有幸住在灯塔附近，那么本周末就是拜访灯塔的最佳时机。"
href="/"
author="Andreas Kunz"
date="2024/08/16"
/>
</CardGrid>
[查看 照片类作品示例](../../../../1.示例/照片类作品示例.md)

38
docs/notes/theme/guide/组件/徽章.md Normal file
View File

@ -0,0 +1,38 @@
---
title: 徽章
author: pengzhanbo
icon: iconamoon:badge-light
createTime: 2024/08/18 22:45:50
permalink: /guide/components/badge/
---
## 概述 <Badge type="tip" text="badge" />
使用 `<Badge>` 组件来显示 行内信息，如状态或标签。
将你想显示的内容传递给 `<Badge>` 组件的 `text` 属性。
## Props
| 名称 | 类型 | 默认值 | 说明 |
| ---- | ------------------------------------------ | ------- | ---- |
| type | `'info' \| 'tip' \| 'warning' \| 'danger'` | `'tip'` | 类型 |
| text | `string` | `''` | 文本 |
## 示例
**输入：**
```md :no-line-numbers
- VuePress - <Badge type="info" text="v2" />
- VuePress - <Badge type="tip" text="v2" />
- VuePress - <Badge type="warning" text="v2" />
- VuePress - <Badge type="danger" text="v2" />
```
**输出：**
- VuePress - <Badge type="info" text="v2" />
- VuePress - <Badge type="tip" text="v2" />
- VuePress - <Badge type="warning" text="v2" />
- VuePress - <Badge type="danger" text="v2" />

41
docs/notes/theme/guide/组件/链接卡片.md Normal file
View File

@ -0,0 +1,41 @@
---
title: 链接卡片
author: pengzhanbo
icon: solar:card-send-linear
createTime: 2024/08/18 23:14:00
permalink: /guide/components/link-card/
---
## 概述
使用 `<LinkCard>` 组件在页面中显示链接卡片。
## Props
| 名称 | 类型 | 默认值 | 说明 |
| ----------- | --------------------------- | ------ | ---------------------------------------------------------------- |
| title | `string` | `''` | 标题 |
| icon | `string \| { svg: string }` | `''` | 显示在标题左侧的图标，支持 iconify 所有图标，也可以使用 图片链接 |
| href | `string` | `''` | 链接 |
| description | `string` | `''` | 详情 |
## 插槽
| 名称 | 说明 |
| ------- | ------------ |
| default | 卡片详情内容 |
| title | 自定义标题 |
## 示例
**输入：**
```md :no-line-numbers
<LinkCard title="卡片标题" href="/" description="这里是卡片内容" />
<LinkCard icon="twemoji:astonished-face" title="卡片标题" href="/" />
```
**输出：**
<LinkCard title="卡片标题" href="/" description="这里是卡片内容" />
<LinkCard icon="twemoji:astonished-face" title="卡片标题" href="/" />

52
docs/notes/theme/guide/组件/隐秘文本.md Normal file
View File

@ -0,0 +1,52 @@
---
title: “隐秘”文本
author: pengzhanbo
icon: lets-icons:hide-eye
createTime: 2024/08/18 23:02:39
permalink: /guide/components/plot/
---
## 概述
使用 `<Plot>` 组件显示 [“隐秘”文本](/guide/markdown/advance/#隐秘-文本) ，能够更灵活的控制行为。
该组件默认不启用，你需要在 theme 配置中启用。
::: code-tabs
@tab .vuepress/config.ts
```ts :no-line-numbers
export default defineUserConfig({
theme: plumeTheme({
plugins: {
markdownPower: {
plot: true,
},
}
})
})
```
:::
## Props
| 名称 | 类型 | 默认值 | 说明 |
| ------- | ------------------------------------------- | --------- | -------------------------- |
| trigger | `'hover' \| 'click'` | `'hover'` | 鼠标悬停触发，或者点击触发 |
| mask | `string \| { light: string, dark: string }` | `#000` | 遮罩颜色 |
| color | `string \| { light: string, dark: string }` | `#fff` | 文本颜色 |
## 示例
**输入：**
```md :no-line-numbers
- 鼠标悬停 - <Plot>悬停时可见</Plot>
- 点击 - <Plot trigger="click">点击时可见</Plot>
```
**输出：**
- 鼠标悬停 - <Plot>悬停时可见</Plot>
- 点击 - <Plot trigger="click">点击时可见</Plot>

20
docs/notes/theme/guide/组件/首页布局容器.md Normal file
View File

@ -0,0 +1,20 @@
---
title: 首页布局容器
author: pengzhanbo
icon: tabler:container
createTime: 2024/08/18 23:49:40
permalink: /guide/components/home-box/
---
## 首页布局容器
自定义首页时，使用 `<HomeBox>` 提供给 区域 的 包装容器。
## Props
| 名称 | 类型 | 默认值 | 说明 |
| --------------------- | ------------------ | --------- | ---------------- |
| type | string | `''` | 区域类型 |
| full | boolean | `false` | 是否全屏 |
| background-image | string | `''` | 区域背景图片 |
| background-attachment | `'fixed'\|'local'` | `'local'` | 区域背景定位方式 |

4
docs/notes/theme/guide/自定义首页.md
View File

@ -144,7 +144,7 @@ config:
适用于 文档 类型站点，放置于 首位。
**工具支持： [首页背景色板配置工具](/tools/home-hero-tint-plate/)**
**工具支持： [首页背景色板配置工具](../../tools/home-hero-tint-plate.md)**
```ts
interface PlumeThemeHomeHero extends PlumeHomeConfigBase {
@ -246,7 +246,7 @@ config:
- 还可以配置为 `{ light, dark }`，在深色模式和浅色模式下使用不同的颜色值。
::: info
为了便于用户配置 美观的个性化的背景，主题还提供了 [首页背景色板配置工具](/tools/home-hero-tint-plate/)
为了便于用户配置 美观的个性化的背景，主题还提供了 [首页背景色板配置工具](../../tools/custom-theme.md)
进行可视化操作，生成配置内容，你可以直接复制它们用于自己的项目中。
:::