docs: improve docs (#240)
This commit is contained in:
pengzhanbo
GitHub
parent
1e076fea5a
commit
c177fd6917
@ -33,7 +33,15 @@ export const themeGuide = defineNoteConfig({
|
||||
items: [
|
||||
'基础',
|
||||
'扩展',
|
||||
'进阶',
|
||||
'图标',
|
||||
'卡片',
|
||||
'步骤',
|
||||
'文件树',
|
||||
'选项组',
|
||||
'隐秘文本',
|
||||
'示例容器',
|
||||
'caniuse',
|
||||
'导入文件',
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
112
docs/notes/theme/guide/markdown/caniuse.md
Normal file
112
docs/notes/theme/guide/markdown/caniuse.md
Normal file
@ -0,0 +1,112 @@
|
||||
---
|
||||
title: Can I Use
|
||||
createTime: 2024/09/30 14:50:55
|
||||
icon: streamline:desktop-help
|
||||
permalink: /guide/markdown/caniuse/
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
在编写文章时， 提供嵌入 [can-i-use](https://caniuse.com/) WEB feature 各平台支持说明 的功能。
|
||||
|
||||
方便在描述某个 WEB feature 时，能更直观的表述 该特性的支持程度。
|
||||
|
||||
## 配置
|
||||
|
||||
此功能默认不启用，你可以在配置文件中启用它。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/config.ts
|
||||
|
||||
```ts
|
||||
export default defineUserConfig({
|
||||
theme: plumeTheme({
|
||||
plugins: {
|
||||
markdownPower: {
|
||||
caniuse: true, // [!code highlight]
|
||||
},
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
在你的 文章 markdown文件中，使用以下格式：
|
||||
|
||||
``` md
|
||||
@[caniuse](feature)
|
||||
```
|
||||
|
||||
为了方便使用，主题提供了工具支持：[caniuse 特性搜索](../../../tools/caniuse.md)，你可以直接使用该工具
|
||||
帮助生成 markdown 代码。
|
||||
|
||||
## 语法
|
||||
|
||||
``` md
|
||||
@[caniuse](feature)
|
||||
@[caniuse{browser_versions}](feature)
|
||||
@[caniuse embed_type](feature)
|
||||
@[caniuse embed_type{browser_versions}](feature)
|
||||
```
|
||||
|
||||
- `feature`
|
||||
|
||||
必填。 正确取值请参考 [caniuse-embed.vercel.app](https://caniuse-embed.vercel.app/zh-CN)
|
||||
|
||||
- `{browser_versions}`
|
||||
|
||||
可选。当前特性在多个版本中的支持情况。
|
||||
|
||||
默认值为: `{-2,1}`
|
||||
|
||||
格式： `{past,future}` 取值范围为 `-5 ~ 3`
|
||||
|
||||
- 小于`0` 表示低于当前浏览器版本的支持情况
|
||||
- `0` 表示当前浏览器版本的支持情况
|
||||
- 大于`0` 表示高于当前浏览器版本的支持情况
|
||||
|
||||
- `embed_type`
|
||||
|
||||
可选。 资源嵌入的类型。
|
||||
|
||||
类型： `'embed' | 'image'`
|
||||
|
||||
默认值为：`'embed'`
|
||||
|
||||
:::caution
|
||||
不再推荐使用 image 类型，建议使用 embed 类型，主题更换了 embed 实现技术方案，
|
||||
现在的 embed 类型优势已远远超过 image 类型，加载速度更快，体积更小，交互体验更好。
|
||||
:::
|
||||
|
||||
## 示例
|
||||
|
||||
**获取 css 伪类选择器 `:dir()` 在各个浏览器的支持情况：**
|
||||
|
||||
```md
|
||||
@[caniuse](css-matches-pseudo)
|
||||
```
|
||||
|
||||
效果：
|
||||
|
||||
@[caniuse](css-matches-pseudo)
|
||||
|
||||
**以图片的形式，获取 css 伪类选择器 `:dir()` 在各个浏览器的支持情况：**
|
||||
|
||||
```md
|
||||
@[caniuse image](css-matches-pseudo)
|
||||
```
|
||||
|
||||
效果：
|
||||
|
||||
@[caniuse image](css-matches-pseudo)
|
||||
|
||||
**获取 css 伪类选择器 `:dir()` 特定范围浏览器的支持情况：**
|
||||
|
||||
```md
|
||||
@[caniuse{-2,3}](css-matches-pseudo)
|
||||
```
|
||||
|
||||
效果：
|
||||
|
||||
@[caniuse{-2,3}](css-matches-pseudo)
|
||||
91
docs/notes/theme/guide/markdown/卡片.md
Normal file
91
docs/notes/theme/guide/markdown/卡片.md
Normal file
@ -0,0 +1,91 @@
|
||||
---
|
||||
title: 卡片
|
||||
createTime: 2024/09/30 14:37:40
|
||||
icon: solar:card-broken
|
||||
permalink: /guide/markdown/card/
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
对于想要突出显示的内容，可以将其放在 卡片容器 `::: card` 中。
|
||||
|
||||
当需要在空间足够时并排显示多个卡片，可以使用 `card-grid` 容器，包裹 多个卡片。
|
||||
|
||||
## 语法
|
||||
|
||||
```md
|
||||
<!-- 单个卡片 -->
|
||||
::: card title="标题" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
|
||||
<!-- 多个卡片 -->
|
||||
:::: card-grid
|
||||
|
||||
::: card title="卡片标题 1" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
|
||||
::: card title="卡片标题 2" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
|
||||
::::
|
||||
```
|
||||
|
||||
卡片 支持 可选的 `title` 和 `icon`。 其中， icon 支持传入 图片链接，也可以传入 iconify 图标名。
|
||||
|
||||
## 示例
|
||||
|
||||
**输入：**
|
||||
|
||||
```md
|
||||
::: card title="卡片标题" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
|
||||
::: card title="卡片标题" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
|
||||
**输入：**
|
||||
|
||||
```md
|
||||
:::: card-grid
|
||||
::: card title="卡片标题 1" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
|
||||
::: card title="卡片标题 2" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
::::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
|
||||
:::: card-grid
|
||||
::: card title="卡片标题 1" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
|
||||
::: card title="卡片标题 2" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
::::
|
||||
|
||||
::: info
|
||||
如果你更喜欢通过组件的方式使用 卡片，你可以查看 [卡片组件](/guide/features/component/#card) 。
|
||||
:::
|
||||
90
docs/notes/theme/guide/markdown/图标.md
Normal file
90
docs/notes/theme/guide/markdown/图标.md
Normal file
@ -0,0 +1,90 @@
|
||||
---
|
||||
title: 图标
|
||||
createTime: 2024/09/30 14:49:39
|
||||
icon: grommet-icons:emoji
|
||||
permalink: /guide/markdown/iconify/
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
在 Markdown 文件中使用 [iconify](https://iconify.design/) 的图标。
|
||||
|
||||
主题一方面提供了[`<Icon />`](../功能/组件.md#图标) 组件来支持在 markdown 中使用图标；
|
||||
另一方面，主题还提供了图标的 markdown 语法，以更简单的方式，在 Markdown 中使用图标。
|
||||
|
||||
为了更好的使用该功能，主题推荐你安装 `@iconify/json` 依赖。主题会自动解析 `@iconify/json` 中的图标数据，
|
||||
将有使用的图标打包为本地资源，以获得更好的访问体验。
|
||||
|
||||
::: code-tabs
|
||||
@tab pnpm
|
||||
|
||||
```sh
|
||||
pnpm add @iconify/json
|
||||
```
|
||||
|
||||
@tab yarn
|
||||
|
||||
```sh
|
||||
yarn add @iconify/json
|
||||
```
|
||||
|
||||
@tab npm
|
||||
|
||||
```sh
|
||||
npm install @iconify/json
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## 语法
|
||||
|
||||
```md
|
||||
:[collect:name]:
|
||||
```
|
||||
|
||||
设置图标大小和颜色
|
||||
|
||||
```md
|
||||
:[collect:name size]:
|
||||
:[collect:name /color]:
|
||||
:[collect:name size/color]:
|
||||
```
|
||||
|
||||
`iconify` 拥有非常多的图标，这些图标被分组为不同的 `collect`，每个 `collect` 都有自己的
|
||||
图标。
|
||||
|
||||
你可以从 <https://icon-sets.iconify.design/> 中获取 collect 和 name。
|
||||
|
||||
## 示例
|
||||
|
||||
输入：
|
||||
|
||||
```md
|
||||
:[ion:logo-markdown]:
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
:[ion:logo-markdown]:
|
||||
|
||||
该语法为行内语法，因此，你可以在同一行中跟其他 markdown 语法 一起使用。
|
||||
|
||||
输入：
|
||||
|
||||
```md
|
||||
github: :[tdesign:logo-github-filled]:
|
||||
修改颜色：:[tdesign:logo-github-filled /#f00]:
|
||||
修改大小：:[tdesign:logo-github-filled 36px]:
|
||||
修改大小颜色：:[tdesign:logo-github-filled 36px/#f00]:
|
||||
|
||||
彩色图标 :[skill-icons:vscode-dark 36px]:
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
github: :[tdesign:logo-github-filled]:
|
||||
修改颜色：:[tdesign:logo-github-filled /#f00]:
|
||||
修改大小：:[tdesign:logo-github-filled 36px]:
|
||||
修改大小颜色：:[tdesign:logo-github-filled 36px/#f00]:
|
||||
|
||||
彩色图标 :[skill-icons:vscode-dark 36px]:
|
||||
180
docs/notes/theme/guide/markdown/导入文件.md
Normal file
180
docs/notes/theme/guide/markdown/导入文件.md
Normal file
@ -0,0 +1,180 @@
|
||||
---
|
||||
title: 导入文件
|
||||
createTime: 2024/09/30 14:53:04
|
||||
icon: fluent:table-simple-include-16-regular
|
||||
permalink: /guide/markdown/include/
|
||||
outline: 2
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
主题支持在 Markdown 文件中导入文件切片。
|
||||
|
||||
导入文件 默认不启用，你可以通过配置来启用它。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/config.ts
|
||||
|
||||
```ts
|
||||
export default defineUserConfig({
|
||||
theme: plumeTheme({
|
||||
plugins: {
|
||||
markdownEnhance: {
|
||||
include: true, // [!code highlight]
|
||||
},
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## 语法
|
||||
|
||||
使用 `<!-- @include: filename -->` 导入文件。
|
||||
|
||||
如果要部分导入文件，你可以指定导入的行数:
|
||||
|
||||
- `<!-- @include: filename{start-end} -->`
|
||||
- `<!-- @include: filename{start-} -->`
|
||||
- `<!-- @include: filename{-end} -->`
|
||||
|
||||
同时你也可以导入文件区域:
|
||||
|
||||
- `<!-- @include: filename#region -->`
|
||||
|
||||
::::tip 文件区域
|
||||
文件区域是 vscode 中的一个概念，区域内容被 `#region` 和 `#endregion` 注释包围。
|
||||
|
||||
<!-- @include: ../../snippet/include-1.snippet.md -->
|
||||
::::
|
||||
|
||||
## 配置
|
||||
|
||||
你还可以设置一个对象来自定义包含文件路径和包含行为。
|
||||
|
||||
```ts
|
||||
interface IncludeOptions {
|
||||
/**
|
||||
* 处理 include 文件路径
|
||||
*
|
||||
* @default (path) => path
|
||||
*/
|
||||
resolvePath?: (path: string, cwd: string | null) => string
|
||||
/**
|
||||
* 是否深度导入包含的 Markdown 文件
|
||||
*
|
||||
* @default false
|
||||
*/
|
||||
deep?: boolean
|
||||
/**
|
||||
* 是否使用 `<!-- @include: xxx -->` 代替 `@include: xxx` 导入文件
|
||||
*
|
||||
* @default true
|
||||
*/
|
||||
useComment?: boolean
|
||||
/**
|
||||
* 是否解析包含的 Markdown 文件的里的相对图像路径
|
||||
*
|
||||
* @default true
|
||||
*/
|
||||
resolveImagePath?: boolean
|
||||
/**
|
||||
* 是否解析包含的 Markdown 文件的里的文件相对路径
|
||||
*
|
||||
* @default true
|
||||
*/
|
||||
resolveLinkPath?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
例如: 你可以使用 @src 作为源文件夹的别名。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/config.ts
|
||||
|
||||
```ts{5-11}
|
||||
export default defineUserConfig({
|
||||
theme: plumeTheme({
|
||||
plugins: {
|
||||
markdownEnhance: {
|
||||
include: {
|
||||
resolvePath: (file) => {
|
||||
if (file.startsWith('@src'))
|
||||
return file.replace('@src', path.resolve(__dirname, '..'))
|
||||
|
||||
return file
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
此外，如果你想将 Markdown 文件直接放在实际文件旁边，但不希望它们呈现为页面，
|
||||
你可以在 VuePress 配置中设置 `pagePatterns` 选项。
|
||||
有关详细信息，请参阅 [pagePatterns](https://vuejs.press/zh/reference/config.html#pagepatterns)。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/config.ts
|
||||
|
||||
```ts
|
||||
export default defineUserConfig({
|
||||
// 现在任何带有 `.snippet.md` 扩展名的文件都不会呈现为页面
|
||||
pagePatterns: ['**/*.md', '!**/*.snippet.md', '!.vuepress', '!node_modules'], // [!code ++]
|
||||
theme: plumeTheme({
|
||||
plugins: {
|
||||
markdownEnhance: {
|
||||
include: true,
|
||||
},
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## 示例
|
||||
|
||||
在项目中有一个 `foo.snippet.md` 文件：
|
||||
:::: code-tabs
|
||||
@tab foo.snippet.md
|
||||
|
||||
```md
|
||||
### 三级标题
|
||||
|
||||
这是 foo.snippet.md 文件中的内容。
|
||||
|
||||
::: info
|
||||
提示容器包括的内容
|
||||
:::
|
||||
|
||||
<!-- region snippet -->
|
||||
这里是被 `<!-- region snippet -->` 包裹的内容。
|
||||
|
||||
通过 `<!-- @include: ./foo.snippet.md#snippet -->` 来引入。
|
||||
<!-- endregion snippet -->
|
||||
```
|
||||
|
||||
::::
|
||||
|
||||
使用 `<!-- @include: ./foo.snippet.md -->` 导入文件：
|
||||
|
||||
:::: demo-wrapper title="Include by file"
|
||||
<!-- @include: ../../snippet/include-2.snippet.md -->
|
||||
::::
|
||||
|
||||
使用 `<!-- @include: ./foo.snippet.md{5-7} -->` 导入文件内的 5 到 7 行：
|
||||
|
||||
:::: demo-wrapper title="Include by lines"
|
||||
<!-- @include: ../../snippet/include-2.snippet.md{5-7} -->
|
||||
::::
|
||||
|
||||
使用 `<!-- @include: ./foo.snippet.md#snippet -->` 导入 `snippet` 区域
|
||||
|
||||
:::: demo-wrapper title="Include by file region"
|
||||
<!-- @include: ../../snippet/include-2.snippet.md#snippet -->
|
||||
::::
|
||||
130
docs/notes/theme/guide/markdown/文件树.md
Normal file
130
docs/notes/theme/guide/markdown/文件树.md
Normal file
@ -0,0 +1,130 @@
|
||||
---
|
||||
title: 文件树
|
||||
createTime: 2024/09/30 14:41:57
|
||||
icon: mdi:file-tree
|
||||
permalink: /guide/markdown/file-tree/
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
在 Markdown 中，你可以使用 `file-tree` 容器 来显示带有文件图标和可折叠子目录的目录结构。
|
||||
|
||||
## 语法
|
||||
|
||||
在 `::: file-tree` 容器，使用内置的 **Markdown 无序列表语法** 指定文件和目录的组织结构。
|
||||
使用嵌套的列表项创建子目录；若希望某个目录不显示具体内容，只需在列表项末尾添加斜杠 `/` 即可。
|
||||
|
||||
以下语法可用于自定义文件树的外观：
|
||||
|
||||
- 通过加粗文件名或目录名来突出显示，例如 `**README.md**`
|
||||
- 通过在名称后添加更多文本来为文件或目录添加注释
|
||||
- 使用 `...` 或 `…` 作为名称来添加占位符文件和目录。
|
||||
- 在 `:::file-tree` 后添加 `icon="simple"` 或 添加 `icon="colored"` 可以切换为简单图标或彩色图标，默认为彩色图标。
|
||||
|
||||
**输入：**
|
||||
|
||||
```md
|
||||
::: file-tree
|
||||
|
||||
- docs
|
||||
- .vuepress
|
||||
- config.ts
|
||||
- page1.md
|
||||
- README.md
|
||||
- theme 一个 **主题** 目录
|
||||
- client
|
||||
- components
|
||||
- **Navbar.vue**
|
||||
- composables
|
||||
- useNavbar.ts
|
||||
- styles
|
||||
- navbar.css
|
||||
- config.ts
|
||||
- node/
|
||||
- package.json
|
||||
- pnpm-lock.yaml
|
||||
- .gitignore
|
||||
- README.md
|
||||
- …
|
||||
:::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
|
||||
::: file-tree
|
||||
|
||||
- docs
|
||||
- .vuepress
|
||||
- config.ts
|
||||
- page1.md
|
||||
- README.md
|
||||
- theme 一个 **主题** 目录
|
||||
- client
|
||||
- components
|
||||
- **Navbar.vue**
|
||||
- composables
|
||||
- useNavbar.ts
|
||||
- styles
|
||||
- navbar.css
|
||||
- config.ts
|
||||
- node/
|
||||
- package.json
|
||||
- pnpm-lock.yaml
|
||||
- .gitignore
|
||||
- README.md
|
||||
- …
|
||||
:::
|
||||
|
||||
## 使用简单图标
|
||||
|
||||
**输入：**
|
||||
|
||||
```md
|
||||
::: file-tree icon="simple"
|
||||
- docs
|
||||
- .vuepress
|
||||
- config.ts
|
||||
- page1.md
|
||||
- README.md
|
||||
- package.json
|
||||
:::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
|
||||
::: file-tree icon="simple"
|
||||
|
||||
- docs
|
||||
- .vuepress
|
||||
- config.ts
|
||||
- page1.md
|
||||
- README.md
|
||||
- package.json
|
||||
:::
|
||||
|
||||
## 配置
|
||||
|
||||
你可以在 `plugins.mdPower.fileTree` 选项中配置 文件树的图标默认类型：
|
||||
|
||||
```ts
|
||||
export default defineUserConfig({
|
||||
theme: plumeTheme({
|
||||
plugins: {
|
||||
markdownPower: {
|
||||
fileTree: {
|
||||
icon: 'simple', // 'simple' | 'colored'
|
||||
}
|
||||
},
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
::: tip 担心彩色图标会影响构建包体积？
|
||||
您无需担心，文件树的彩色图标 也是从 `iconify` 解析获取，推荐您在本地安装 `@iconify/json` 项目，
|
||||
主题会自动将 `@iconify/json` 中的图标数据解析为本地图标资源，即使您在不同的页面
|
||||
多次使用，这包括了 导航栏、侧边栏、图标组件等，相同图标仅会存在一份资源！
|
||||
|
||||
每个彩色图标的大小约在 `1kb ~ 2kb` 之间，即使您的文件树非常夸张的使用了 100+ 不同的图标，对最终的构建包体积影响
|
||||
也不会很大。
|
||||
:::
|
||||
77
docs/notes/theme/guide/markdown/步骤.md
Normal file
77
docs/notes/theme/guide/markdown/步骤.md
Normal file
@ -0,0 +1,77 @@
|
||||
---
|
||||
title: 步骤
|
||||
createTime: 2024/09/30 14:40:30
|
||||
icon: streamline:steps-number
|
||||
permalink: /guide/markdown/steps/
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
有时候，你需要将内容 划分为递进的步骤展示，你可以使用 `steps` 容器 实现。
|
||||
|
||||
## 语法
|
||||
|
||||
在 `steps` 容器内，使用 有序列表 （或无序列表） 来表示步骤。你可以在 容器内使用 任意 markdown 语法。
|
||||
|
||||
````md
|
||||
::: steps
|
||||
|
||||
1. 步骤 1
|
||||
|
||||
相关内容
|
||||
|
||||
2. 步骤 2
|
||||
|
||||
相关内容
|
||||
|
||||
:::
|
||||
````
|
||||
|
||||
## 示例
|
||||
|
||||
输入：
|
||||
|
||||
````md
|
||||
:::: steps
|
||||
1. 步骤 1
|
||||
|
||||
```ts
|
||||
console.log('Hello World!')
|
||||
```
|
||||
|
||||
2. 步骤 2
|
||||
|
||||
这里是步骤 2 的相关内容
|
||||
|
||||
3. 步骤 3
|
||||
|
||||
::: tip
|
||||
提示容器
|
||||
:::
|
||||
|
||||
4. 结束
|
||||
::::
|
||||
````
|
||||
|
||||
输出：
|
||||
|
||||
:::: steps
|
||||
|
||||
1. 步骤 1
|
||||
|
||||
```ts
|
||||
console.log('Hello World!')
|
||||
```
|
||||
|
||||
2. 步骤 2
|
||||
|
||||
这里是步骤 2 的相关内容
|
||||
|
||||
3. 步骤 3
|
||||
|
||||
::: tip
|
||||
提示容器
|
||||
:::
|
||||
|
||||
4. 结束
|
||||
::::
|
||||
95
docs/notes/theme/guide/markdown/示例容器.md
Normal file
95
docs/notes/theme/guide/markdown/示例容器.md
Normal file
@ -0,0 +1,95 @@
|
||||
---
|
||||
title: 示例容器
|
||||
createTime: 2024/09/30 14:47:12
|
||||
icon: icon-park-outline:eyes
|
||||
permalink: /guide/markdown/demo-wrapper/
|
||||
outline: 2
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
有时候，你可能需要在 内容中补充一些 示例，但期望能与 其它内容 分隔开来呈现。
|
||||
主题支持在 Markdown 文件中添加示例容器。
|
||||
|
||||
## 语法
|
||||
|
||||
````md
|
||||
::: demo-wrapper
|
||||
添加你的示例
|
||||
:::
|
||||
````
|
||||
|
||||
## 选项
|
||||
|
||||
- `title="xxx"`：标题
|
||||
- `no-padding`：不添加内边距
|
||||
- `img`: 仅包含图片时使用
|
||||
- `height="xxx"`: 高度
|
||||
|
||||
## 示例
|
||||
|
||||
仅包含图片:
|
||||
|
||||
```md
|
||||
::: demo-wrapper img no-padding
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
::: demo-wrapper img no-padding
|
||||
|
||||
:::
|
||||
|
||||
包含 markdown 语法：
|
||||
|
||||
```md
|
||||
::: demo-wrapper title="标题"
|
||||
### 三级标题
|
||||
|
||||
这是示例容器中的内容。
|
||||
:::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
::: demo-wrapper title="标题"
|
||||
|
||||
### 三级标题
|
||||
|
||||
这是示例容器中的内容。
|
||||
:::
|
||||
|
||||
包含 html /vue 代码：
|
||||
|
||||
```md
|
||||
::: demo-wrapper
|
||||
<h1 class="your-demo-title">这是标题</h1>
|
||||
<p class="your-demo-paragraph">这是段落</p>
|
||||
|
||||
<style>
|
||||
.your-demo-title {
|
||||
color: red;
|
||||
}
|
||||
.your-demo-paragraph {
|
||||
color: blue;
|
||||
}
|
||||
</style>
|
||||
:::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
::: demo-wrapper
|
||||
|
||||
<h1 class="your-demo-title">这是标题</h1>
|
||||
<p class="your-demo-paragraph">这是段落</p>
|
||||
|
||||
<style>
|
||||
.your-demo-title {
|
||||
color: red !important;
|
||||
}
|
||||
.your-demo-paragraph {
|
||||
color: blue !important;
|
||||
}
|
||||
</style>
|
||||
|
||||
:::
|
||||
@ -1,928 +0,0 @@
|
||||
---
|
||||
title: 更多
|
||||
author: pengzhanbo
|
||||
icon: ic:outline-auto-fix-high
|
||||
outline: 2
|
||||
createTime: 2024/03/05 16:27:59
|
||||
permalink: /guide/markdown/advance/
|
||||
tags:
|
||||
- 指南
|
||||
- markdown
|
||||
---
|
||||
|
||||
## 卡片
|
||||
|
||||
对于想要突出显示的内容，可以将其放在 卡片容器 `::: card` 中。
|
||||
|
||||
如果需要在空间足够时并排显示多个卡片，可以使用 `card-grid` 容器，包裹 多个卡片。
|
||||
|
||||
### 语法
|
||||
|
||||
```md
|
||||
<!-- 单个卡片 -->
|
||||
::: card title="标题" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
|
||||
<!-- 多个卡片 -->
|
||||
:::: card-grid
|
||||
|
||||
::: card title="卡片标题 1" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
|
||||
::: card title="卡片标题 2" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
|
||||
::::
|
||||
```
|
||||
|
||||
卡片 支持 可选的 `title` 和 `icon`。 其中， icon 支持传入 图片链接，也可以传入 iconify 图标名。
|
||||
|
||||
### 示例
|
||||
|
||||
**输入：**
|
||||
|
||||
```md
|
||||
::: card title="卡片标题" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
|
||||
::: card title="卡片标题" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
|
||||
**输入：**
|
||||
|
||||
```md
|
||||
:::: card-grid
|
||||
::: card title="卡片标题 1" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
|
||||
::: card title="卡片标题 2" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
::::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
|
||||
:::: card-grid
|
||||
::: card title="卡片标题 1" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
|
||||
::: card title="卡片标题 2" icon="twemoji:astonished-face"
|
||||
|
||||
这里是卡片内容。
|
||||
:::
|
||||
::::
|
||||
|
||||
::: info
|
||||
如果你更喜欢通过组件的方式使用 卡片，你可以查看 [卡片组件](/guide/features/component/#card) 。
|
||||
:::
|
||||
|
||||
## 步骤
|
||||
|
||||
有时候，你需要将内容 划分为递进的步骤展示，你可以使用 `steps` 容器 实现。
|
||||
|
||||
### 语法
|
||||
|
||||
在 `steps` 容器内，使用 有序列表 （或无序列表） 来表示步骤。你可以在 容器内使用 任意 markdown 语法。
|
||||
|
||||
````md
|
||||
::: steps
|
||||
|
||||
1. 步骤 1
|
||||
|
||||
相关内容
|
||||
|
||||
2. 步骤 2
|
||||
|
||||
相关内容
|
||||
|
||||
:::
|
||||
````
|
||||
|
||||
### 示例
|
||||
|
||||
输入：
|
||||
|
||||
````md
|
||||
:::: steps
|
||||
1. 步骤 1
|
||||
|
||||
```ts
|
||||
console.log('Hello World!')
|
||||
```
|
||||
|
||||
2. 步骤 2
|
||||
|
||||
这里是步骤 2 的相关内容
|
||||
|
||||
3. 步骤 3
|
||||
|
||||
::: tip
|
||||
提示容器
|
||||
:::
|
||||
|
||||
4. 结束
|
||||
::::
|
||||
````
|
||||
|
||||
输出：
|
||||
|
||||
:::: steps
|
||||
|
||||
1. 步骤 1
|
||||
|
||||
```ts
|
||||
console.log('Hello World!')
|
||||
```
|
||||
|
||||
2. 步骤 2
|
||||
|
||||
这里是步骤 2 的相关内容
|
||||
|
||||
3. 步骤 3
|
||||
|
||||
::: tip
|
||||
提示容器
|
||||
:::
|
||||
|
||||
4. 结束
|
||||
::::
|
||||
|
||||
## 文件树
|
||||
|
||||
在 Markdown 中，你可以使用 `file-tree` 容器 来显示带有文件图标和可折叠子目录的目录结构。
|
||||
|
||||
在 `::: file-tree` 容器，使用内置的 **Markdown 无序列表语法** 指定文件和目录的组织结构。
|
||||
使用嵌套的列表项创建子目录；若希望某个目录不显示具体内容，只需在列表项末尾添加斜杠 `/` 即可。
|
||||
|
||||
以下语法可用于自定义文件树的外观：
|
||||
|
||||
- 通过加粗文件名或目录名来突出显示，例如 `**README.md**`
|
||||
- 通过在名称后添加更多文本来为文件或目录添加注释
|
||||
- 使用 `...` 或 `…` 作为名称来添加占位符文件和目录。
|
||||
- 在 `:::file-tree` 后添加 `:simple-icon` 或 添加 `:colored-icon` 可以切换为简单图标或彩色图标，默认为彩色图标。
|
||||
|
||||
**输入：**
|
||||
|
||||
```md
|
||||
::: file-tree
|
||||
|
||||
- docs
|
||||
- .vuepress
|
||||
- config.ts
|
||||
- page1.md
|
||||
- README.md
|
||||
- theme 一个 **主题** 目录
|
||||
- client
|
||||
- components
|
||||
- **Navbar.vue**
|
||||
- composables
|
||||
- useNavbar.ts
|
||||
- styles
|
||||
- navbar.css
|
||||
- config.ts
|
||||
- node/
|
||||
- package.json
|
||||
- pnpm-lock.yaml
|
||||
- .gitignore
|
||||
- README.md
|
||||
- …
|
||||
:::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
|
||||
::: file-tree
|
||||
|
||||
- docs
|
||||
- .vuepress
|
||||
- config.ts
|
||||
- page1.md
|
||||
- README.md
|
||||
- theme 一个 **主题** 目录
|
||||
- client
|
||||
- components
|
||||
- **Navbar.vue**
|
||||
- composables
|
||||
- useNavbar.ts
|
||||
- styles
|
||||
- navbar.css
|
||||
- config.ts
|
||||
- node/
|
||||
- package.json
|
||||
- pnpm-lock.yaml
|
||||
- .gitignore
|
||||
- README.md
|
||||
- …
|
||||
:::
|
||||
|
||||
### 使用简单图标
|
||||
|
||||
**输入：**
|
||||
|
||||
```md
|
||||
::: file-tree:simple-icon
|
||||
- docs
|
||||
- .vuepress
|
||||
- config.ts
|
||||
- page1.md
|
||||
- README.md
|
||||
- package.json
|
||||
:::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
|
||||
::: file-tree:simple-icon
|
||||
|
||||
- docs
|
||||
- .vuepress
|
||||
- config.ts
|
||||
- page1.md
|
||||
- README.md
|
||||
- package.json
|
||||
:::
|
||||
|
||||
### 配置
|
||||
|
||||
你可以在 `plugins.mdPower.fileTree` 选项中配置 文件树的图标默认类型：
|
||||
|
||||
```ts
|
||||
export default defineUserConfig({
|
||||
theme: plumeTheme({
|
||||
plugins: {
|
||||
markdownPower: {
|
||||
fileTree: {
|
||||
icon: 'simple', // 'simple' | 'colored'
|
||||
}
|
||||
},
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
::: tip 担心彩色图标会影响构建包体积？
|
||||
您无需担心，文件树的彩色图标 也是从 `iconify` 解析获取，推荐您在本地安装 `@iconify/json` 项目，
|
||||
主题会自动将 `@iconify/json` 中的图标数据解析为本地图标资源，即使您在不同的页面
|
||||
多次使用，这包括了 导航栏、侧边栏、图标组件等，相同图标仅会存在一份资源！
|
||||
|
||||
每个彩色图标的大小约在 `1kb ~ 2kb` 之间，即使您的文件树非常夸张的使用了 100+ 不同的图标，对最终的构建包体积影响
|
||||
也不会很大。
|
||||
:::
|
||||
|
||||
## 选项组
|
||||
|
||||
在 Markdown 中支持选项卡。
|
||||
|
||||
你需要将选项卡包装在 `tabs` 容器中。
|
||||
|
||||
你可以在 `tabs` 容器中添加一个 id 后缀，该后缀将用作选项卡 id。
|
||||
所有具有相同 id 的选项卡将共享相同的切换事件。
|
||||
|
||||
```md
|
||||
::: tabs#fruit
|
||||
|
||||
<!-- 这里，fruit 将用作 id，它是可选的 -->
|
||||
|
||||
<!-- 选项卡内容 -->
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
在这个容器内，你应该使用 `@tab` 标记来标记和分隔选项卡内容。
|
||||
|
||||
在 `@tab` 标记后，你可以添加文本 `:active` 默认激活选项卡，之后的文本将被解析为选项卡标题。
|
||||
|
||||
```md
|
||||
::: tabs
|
||||
|
||||
@tab 标题 1
|
||||
|
||||
<!-- tab 1 内容 -->
|
||||
|
||||
@tab 标题 2
|
||||
|
||||
<!-- tab 2 内容 -->
|
||||
|
||||
@tab:active 标题 3
|
||||
|
||||
<!-- tab 3 将会被默认激活 -->
|
||||
|
||||
<!-- tab 3 内容 -->
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
默认情况下，标题将用作选项卡的值，但你可以使用 id 后缀覆盖它。
|
||||
|
||||
```md
|
||||
::: tabs
|
||||
|
||||
@tab 标题 1
|
||||
|
||||
<!-- 此处，选项卡 1 的标题“标题 1”将用作值。 -->
|
||||
|
||||
<!-- tab 1 内容 -->
|
||||
|
||||
@tab 标题 2#值 2
|
||||
|
||||
<!-- 这里，tab 2 的标题将是 “标题 2”，但它会使用 “值 2” 作为选项卡的值-->
|
||||
|
||||
<!-- tab 2 内容 -->
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
你可以在每个选项卡中使用 Vue 语法和组件，并且你可以访问 value 和 isActive，
|
||||
表示选项卡的绑定值和选项卡是否处于激活状态。
|
||||
|
||||
**输入：**
|
||||
|
||||
````
|
||||
::: tabs
|
||||
@tab npm
|
||||
|
||||
npm 应该与 Node.js 被一同安装。
|
||||
|
||||
@tab pnpm
|
||||
|
||||
```sh
|
||||
corepack enable
|
||||
corepack use pnpm@8
|
||||
```
|
||||
|
||||
:::
|
||||
````
|
||||
|
||||
**输出：**
|
||||
|
||||
::: tabs
|
||||
@tab npm
|
||||
|
||||
npm 应该与 Node.js 被一同安装。
|
||||
|
||||
@tab pnpm
|
||||
|
||||
```sh
|
||||
corepack enable
|
||||
corepack use pnpm@8
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## “隐秘”文本
|
||||
|
||||
有时候，你不想直接把文本内容毫无保留的展示出来，想要保留一些 隐秘性，
|
||||
可能是为了引起读者的好奇心，也可能纯粹是故意增加点阅读障碍，让文章变得更加有趣。
|
||||
|
||||
为了满足这种小小的心思，主题提供了一个 **“隐秘”文本** 的有趣小功能。它看起来像这样：
|
||||
|
||||
:::demo-wrapper
|
||||
你知道吗， !!鲁迅!! 曾说过：“ !!我没说过这句话！!! ” 令我醍醐灌顶，深受启发，浑身迸发出无可匹敌的
|
||||
力量！于是，!!我在床上翻了个身!! ！
|
||||
:::
|
||||
|
||||
读者不能直接阅读到完整的内容，部分的内容被 “遮住”，需要鼠标悬停到内容上，才能看到被遮住的内容。
|
||||
|
||||
### 配置
|
||||
|
||||
该功能默认不启用，你需要在 `theme` 配置中启用。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/config.ts
|
||||
|
||||
```ts
|
||||
export default defineUserConfig({
|
||||
theme: plumeTheme({
|
||||
plugins: {
|
||||
markdownPower: {
|
||||
plot: true,
|
||||
},
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
`markdownPower.plot` 支持传入 `boolean | PlotOptions` 类型
|
||||
|
||||
```ts
|
||||
interface PlotOptions {
|
||||
/**
|
||||
* 是否启用 `!! !!` markdown （该标记为非标准标记，脱离插件将不生效）
|
||||
* 如果设置为 false， 则表示不启用该标记，只能使用 <Plot /> 组件
|
||||
* @default true
|
||||
*/
|
||||
tag?: boolean
|
||||
|
||||
/**
|
||||
* 遮罩层颜色
|
||||
*/
|
||||
mask?: string | { light: string, dark: string }
|
||||
|
||||
/**
|
||||
* 文本颜色
|
||||
*/
|
||||
color?: string | { light: string, dark: string }
|
||||
|
||||
/**
|
||||
* 触发方式
|
||||
*
|
||||
* @default 'hover'
|
||||
*/
|
||||
trigger?: 'hover' | 'click'
|
||||
}
|
||||
```
|
||||
|
||||
### 语法
|
||||
|
||||
```md
|
||||
!!需要隐秘的内容!!
|
||||
```
|
||||
|
||||
如果不想使用 非标准的 `!! !!` 标记语法，你可以将 `plot.tag` 设置为 `false` ，
|
||||
然后使用 [`<Plot />`](/guide/features/component/#plot) 组件替代。
|
||||
|
||||
### 示例
|
||||
|
||||
输入：
|
||||
|
||||
```md
|
||||
你知道吗， !!鲁迅!! 曾说过：“ !!我没说过这句话！!! ” 令我醍醐灌顶，深受启发，浑身迸发出无可匹敌的
|
||||
力量！于是，!!我在床上翻了个身!! ！
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
:::demo-wrapper
|
||||
你知道吗， !!鲁迅!! 曾说过：“ !!我没说过这句话！!! ” 令我醍醐灌顶，深受启发，浑身迸发出无可匹敌的
|
||||
力量！于是，!!我在床上翻了个身!! ！
|
||||
:::
|
||||
|
||||
## 示例容器
|
||||
|
||||
有时候，你可能需要在 内容中补充一些 示例，但期望能与 其它内容 分隔开来呈现。
|
||||
主题支持在 Markdown 文件中添加示例容器。
|
||||
|
||||
### 语法
|
||||
|
||||
````md
|
||||
::: demo-wrapper
|
||||
添加你的示例
|
||||
:::
|
||||
````
|
||||
|
||||
### 选项
|
||||
|
||||
- `title="xxx"`：标题
|
||||
- `no-padding`：不添加内边距
|
||||
- `img`: 仅包含图片时使用
|
||||
- `height="xxx"`: 高度
|
||||
|
||||
### 示例
|
||||
|
||||
仅包含图片:
|
||||
|
||||
```md
|
||||
::: demo-wrapper img no-padding
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
::: demo-wrapper img no-padding
|
||||
|
||||
:::
|
||||
|
||||
包含 markdown 语法：
|
||||
|
||||
```md
|
||||
::: demo-wrapper title="标题"
|
||||
### 三级标题
|
||||
|
||||
这是示例容器中的内容。
|
||||
:::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
::: demo-wrapper title="标题"
|
||||
|
||||
### 三级标题
|
||||
|
||||
这是示例容器中的内容。
|
||||
:::
|
||||
|
||||
包含 html /vue 代码：
|
||||
|
||||
```md
|
||||
::: demo-wrapper
|
||||
<h1 class="your-demo-title">这是标题</h1>
|
||||
<p class="your-demo-paragraph">这是段落</p>
|
||||
|
||||
<style>
|
||||
.your-demo-title {
|
||||
color: red;
|
||||
}
|
||||
.your-demo-paragraph {
|
||||
color: blue;
|
||||
}
|
||||
</style>
|
||||
:::
|
||||
```
|
||||
|
||||
**输出：**
|
||||
::: demo-wrapper
|
||||
|
||||
<h1 class="your-demo-title">这是标题</h1>
|
||||
<p class="your-demo-paragraph">这是段落</p>
|
||||
|
||||
<style>
|
||||
.your-demo-title {
|
||||
color: red !important;
|
||||
}
|
||||
.your-demo-paragraph {
|
||||
color: blue !important;
|
||||
}
|
||||
</style>
|
||||
|
||||
:::
|
||||
|
||||
## iconify 图标
|
||||
|
||||
在 Markdown 文件中使用 [iconify](https://iconify.design/) 的图标。
|
||||
|
||||
主题一方面提供了[`<Icon />`](../功能/组件.md#图标) 组件来支持在 markdown 中使用图标；
|
||||
另一方面，主题还提供了图标的 markdown 语法，以更简单的方式，在 Markdown 中使用图标。
|
||||
|
||||
为了更好的使用该功能，主题推荐你安装 `@iconify/json` 依赖。主题会自动解析 `@iconify/json` 中的图标数据，
|
||||
将有使用的图标打包为本地资源，以获得更好的访问体验。
|
||||
|
||||
::: code-tabs
|
||||
@tab pnpm
|
||||
|
||||
```sh
|
||||
pnpm add @iconify/json
|
||||
```
|
||||
|
||||
@tab yarn
|
||||
|
||||
```sh
|
||||
yarn add @iconify/json
|
||||
```
|
||||
|
||||
@tab npm
|
||||
|
||||
```sh
|
||||
npm install @iconify/json
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### 语法
|
||||
|
||||
```md
|
||||
:[collect:name]:
|
||||
```
|
||||
|
||||
设置图标大小和颜色
|
||||
|
||||
```md
|
||||
:[collect:name size]:
|
||||
:[collect:name /color]:
|
||||
:[collect:name size/color]:
|
||||
```
|
||||
|
||||
`iconify` 拥有非常多的图标，这些图标被分组为不同的 `collect`，每个 `collect` 都有自己的
|
||||
图标。
|
||||
|
||||
你可以从 <https://icon-sets.iconify.design/> 中获取 collect 和 name。
|
||||
|
||||
### 示例
|
||||
|
||||
输入：
|
||||
|
||||
```md
|
||||
:[ion:logo-markdown]:
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
:[ion:logo-markdown]:
|
||||
|
||||
该语法为行内语法，因此，你可以在同一行中跟其他 markdown 语法 一起使用。
|
||||
|
||||
输入：
|
||||
|
||||
```md
|
||||
github: :[tdesign:logo-github-filled]:
|
||||
修改颜色：:[tdesign:logo-github-filled /#f00]:
|
||||
修改大小：:[tdesign:logo-github-filled 36px]:
|
||||
修改大小颜色：:[tdesign:logo-github-filled 36px/#f00]:
|
||||
|
||||
彩色图标 :[skill-icons:vscode-dark 36px]:
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
github: :[tdesign:logo-github-filled]:
|
||||
修改颜色：:[tdesign:logo-github-filled /#f00]:
|
||||
修改大小：:[tdesign:logo-github-filled 36px]:
|
||||
修改大小颜色：:[tdesign:logo-github-filled 36px/#f00]:
|
||||
|
||||
彩色图标 :[skill-icons:vscode-dark 36px]:
|
||||
|
||||
## can I use
|
||||
|
||||
此功能默认不启用，你可以在配置文件中启用它。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/config.ts
|
||||
|
||||
```ts
|
||||
export default defineUserConfig({
|
||||
theme: plumeTheme({
|
||||
plugins: {
|
||||
markdownPower: {
|
||||
caniuse: true, // [!code highlight]
|
||||
},
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
在编写文章时， 提供嵌入 [can-i-use](https://caniuse.com/) WEB feature 各平台支持说明 的功能。
|
||||
|
||||
方便在描述某个 WEB feature 时，能更直观的表述 该特性的支持程度。
|
||||
|
||||
在你的 文章 markdown文件中，使用以下格式：
|
||||
|
||||
``` md
|
||||
@[caniuse](feature)
|
||||
```
|
||||
|
||||
为了方便使用，主题提供了工具支持：[caniuse 特性搜索](../../../tools/caniuse.md)，你可以直接使用该工具
|
||||
帮助生成 markdown 代码。
|
||||
|
||||
### 语法
|
||||
|
||||
``` md
|
||||
@[caniuse](feature)
|
||||
@[caniuse{browser_versions}](feature)
|
||||
@[caniuse embed_type](feature)
|
||||
@[caniuse embed_type{browser_versions}](feature)
|
||||
```
|
||||
|
||||
- `feature`
|
||||
|
||||
必填。 正确取值请参考 [caniuse-embed.vercel.app](https://caniuse-embed.vercel.app/zh-CN)
|
||||
|
||||
- `{browser_versions}`
|
||||
|
||||
可选。当前特性在多个版本中的支持情况。
|
||||
|
||||
默认值为: `{-2,1}`
|
||||
|
||||
格式： `{past,future}` 取值范围为 `-5 ~ 3`
|
||||
|
||||
- 小于`0` 表示低于当前浏览器版本的支持情况
|
||||
- `0` 表示当前浏览器版本的支持情况
|
||||
- 大于`0` 表示高于当前浏览器版本的支持情况
|
||||
|
||||
- `embed_type`
|
||||
|
||||
可选。 资源嵌入的类型。
|
||||
|
||||
类型： `'embed' | 'image'`
|
||||
|
||||
默认值为：`'embed'`
|
||||
|
||||
:::caution
|
||||
不再推荐使用 image 类型，建议使用 embed 类型，主题更换了 embed 实现技术方案，
|
||||
现在的 embed 类型优势已远远超过 image 类型，加载速度更快，体积更小，交互体验更好。
|
||||
:::
|
||||
|
||||
### 示例
|
||||
|
||||
**获取 css 伪类选择器 `:dir()` 在各个浏览器的支持情况：**
|
||||
|
||||
```md
|
||||
@[caniuse](css-matches-pseudo)
|
||||
```
|
||||
|
||||
效果：
|
||||
|
||||
@[caniuse](css-matches-pseudo)
|
||||
|
||||
**以图片的形式，获取 css 伪类选择器 `:dir()` 在各个浏览器的支持情况：**
|
||||
|
||||
```md
|
||||
@[caniuse image](css-matches-pseudo)
|
||||
```
|
||||
|
||||
效果：
|
||||
|
||||
@[caniuse image](css-matches-pseudo)
|
||||
|
||||
**获取 css 伪类选择器 `:dir()` 特定范围浏览器的支持情况：**
|
||||
|
||||
```md
|
||||
@[caniuse{-2,3}](css-matches-pseudo)
|
||||
```
|
||||
|
||||
效果：
|
||||
|
||||
@[caniuse{-2,3}](css-matches-pseudo)
|
||||
|
||||
## 导入文件
|
||||
|
||||
主题支持在 Markdown 文件中导入文件切片。
|
||||
|
||||
导入文件 默认不启用，你可以通过配置来启用它。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/config.ts
|
||||
|
||||
```ts
|
||||
export default defineUserConfig({
|
||||
theme: plumeTheme({
|
||||
plugins: {
|
||||
markdownEnhance: {
|
||||
include: true, // [!code highlight]
|
||||
},
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### 语法
|
||||
|
||||
使用 `<!-- @include: filename -->` 导入文件。
|
||||
|
||||
如果要部分导入文件，你可以指定导入的行数:
|
||||
|
||||
- `<!-- @include: filename{start-end} -->`
|
||||
- `<!-- @include: filename{start-} -->`
|
||||
- `<!-- @include: filename{-end} -->`
|
||||
|
||||
同时你也可以导入文件区域:
|
||||
|
||||
- `<!-- @include: filename#region -->`
|
||||
|
||||
::::tip 文件区域
|
||||
文件区域是 vscode 中的一个概念，区域内容被 `#region` 和 `#endregion` 注释包围。
|
||||
|
||||
<!-- @include: ../../snippet/include-1.snippet.md -->
|
||||
::::
|
||||
|
||||
### 高级
|
||||
|
||||
你还可以设置一个对象来自定义包含文件路径和包含行为。
|
||||
|
||||
```ts
|
||||
interface IncludeOptions {
|
||||
/**
|
||||
* 处理 include 文件路径
|
||||
*
|
||||
* @default (path) => path
|
||||
*/
|
||||
resolvePath?: (path: string, cwd: string | null) => string
|
||||
/**
|
||||
* 是否深度导入包含的 Markdown 文件
|
||||
*
|
||||
* @default false
|
||||
*/
|
||||
deep?: boolean
|
||||
/**
|
||||
* 是否使用 `<!-- @include: xxx -->` 代替 `@include: xxx` 导入文件
|
||||
*
|
||||
* @default true
|
||||
*/
|
||||
useComment?: boolean
|
||||
/**
|
||||
* 是否解析包含的 Markdown 文件的里的相对图像路径
|
||||
*
|
||||
* @default true
|
||||
*/
|
||||
resolveImagePath?: boolean
|
||||
/**
|
||||
* 是否解析包含的 Markdown 文件的里的文件相对路径
|
||||
*
|
||||
* @default true
|
||||
*/
|
||||
resolveLinkPath?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
例如: 你可以使用 @src 作为源文件夹的别名。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/config.ts
|
||||
|
||||
```ts{5-11}
|
||||
export default defineUserConfig({
|
||||
theme: plumeTheme({
|
||||
plugins: {
|
||||
markdownEnhance: {
|
||||
include: {
|
||||
resolvePath: (file) => {
|
||||
if (file.startsWith('@src'))
|
||||
return file.replace('@src', path.resolve(__dirname, '..'))
|
||||
|
||||
return file
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
此外，如果你想将 Markdown 文件直接放在实际文件旁边，但不希望它们呈现为页面，
|
||||
你可以在 VuePress 配置中设置 `pagePatterns` 选项。
|
||||
有关详细信息，请参阅 [pagePatterns](https://vuejs.press/zh/reference/config.html#pagepatterns)。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/config.ts
|
||||
|
||||
```ts
|
||||
export default defineUserConfig({
|
||||
// 现在任何带有 `.snippet.md` 扩展名的文件都不会呈现为页面
|
||||
pagePatterns: ['**/*.md', '!**/*.snippet.md', '!.vuepress', '!node_modules'], // [!code ++]
|
||||
theme: plumeTheme({
|
||||
plugins: {
|
||||
markdownEnhance: {
|
||||
include: true,
|
||||
},
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### 示例
|
||||
|
||||
在项目中有一个 `foo.snippet.md` 文件：
|
||||
:::: code-tabs
|
||||
@tab foo.snippet.md
|
||||
|
||||
```md
|
||||
### 三级标题
|
||||
|
||||
这是 foo.snippet.md 文件中的内容。
|
||||
|
||||
::: info
|
||||
提示容器包括的内容
|
||||
:::
|
||||
|
||||
<!-- region snippet -->
|
||||
这里是被 `<!-- region snippet -->` 包裹的内容。
|
||||
|
||||
通过 `<!-- @include: ./foo.snippet.md#snippet -->` 来引入。
|
||||
<!-- endregion snippet -->
|
||||
```
|
||||
|
||||
::::
|
||||
|
||||
使用 `<!-- @include: ./foo.snippet.md -->` 导入文件：
|
||||
|
||||
:::: demo-wrapper title="Include by file"
|
||||
<!-- @include: ../../snippet/include-2.snippet.md -->
|
||||
::::
|
||||
|
||||
使用 `<!-- @include: ./foo.snippet.md{5-7} -->` 导入文件内的 5 到 7 行：
|
||||
|
||||
:::: demo-wrapper title="Include by lines"
|
||||
<!-- @include: ../../snippet/include-2.snippet.md{5-7} -->
|
||||
::::
|
||||
|
||||
使用 `<!-- @include: ./foo.snippet.md#snippet -->` 导入 `snippet` 区域
|
||||
|
||||
:::: demo-wrapper title="Include by file region"
|
||||
<!-- @include: ../../snippet/include-2.snippet.md#snippet -->
|
||||
::::
|
||||
110
docs/notes/theme/guide/markdown/选项组.md
Normal file
110
docs/notes/theme/guide/markdown/选项组.md
Normal file
@ -0,0 +1,110 @@
|
||||
---
|
||||
title: 选项组
|
||||
createTime: 2024/09/30 14:43:40
|
||||
icon: vaadin:tabs
|
||||
permalink: /guide/markdown/tabs/
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
在 Markdown 中支持选项卡。
|
||||
|
||||
## 语法
|
||||
|
||||
你需要将选项卡包装在 `tabs` 容器中。
|
||||
|
||||
你可以在 `tabs` 容器中添加一个 id 后缀，该后缀将用作选项卡 id。
|
||||
所有具有相同 id 的选项卡将共享相同的切换事件。
|
||||
|
||||
```md
|
||||
::: tabs#fruit
|
||||
|
||||
<!-- 这里，fruit 将用作 id，它是可选的 -->
|
||||
|
||||
<!-- 选项卡内容 -->
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
在这个容器内，你应该使用 `@tab` 标记来标记和分隔选项卡内容。
|
||||
|
||||
在 `@tab` 标记后，你可以添加文本 `:active` 默认激活选项卡，之后的文本将被解析为选项卡标题。
|
||||
|
||||
```md
|
||||
::: tabs
|
||||
|
||||
@tab 标题 1
|
||||
|
||||
<!-- tab 1 内容 -->
|
||||
|
||||
@tab 标题 2
|
||||
|
||||
<!-- tab 2 内容 -->
|
||||
|
||||
@tab:active 标题 3
|
||||
|
||||
<!-- tab 3 将会被默认激活 -->
|
||||
|
||||
<!-- tab 3 内容 -->
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
默认情况下，标题将用作选项卡的值，但你可以使用 id 后缀覆盖它。
|
||||
|
||||
```md
|
||||
::: tabs
|
||||
|
||||
@tab 标题 1
|
||||
|
||||
<!-- 此处，选项卡 1 的标题“标题 1”将用作值。 -->
|
||||
|
||||
<!-- tab 1 内容 -->
|
||||
|
||||
@tab 标题 2#值 2
|
||||
|
||||
<!-- 这里，tab 2 的标题将是 “标题 2”，但它会使用 “值 2” 作为选项卡的值-->
|
||||
|
||||
<!-- tab 2 内容 -->
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
你可以在每个选项卡中使用 Vue 语法和组件，并且你可以访问 value 和 isActive，
|
||||
表示选项卡的绑定值和选项卡是否处于激活状态。
|
||||
|
||||
## 示例
|
||||
|
||||
**输入：**
|
||||
|
||||
````
|
||||
::: tabs
|
||||
@tab npm
|
||||
|
||||
npm 应该与 Node.js 被一同安装。
|
||||
|
||||
@tab pnpm
|
||||
|
||||
```sh
|
||||
corepack enable
|
||||
corepack use pnpm@8
|
||||
```
|
||||
|
||||
:::
|
||||
````
|
||||
|
||||
**输出：**
|
||||
|
||||
::: tabs
|
||||
@tab npm
|
||||
|
||||
npm 应该与 Node.js 被一同安装。
|
||||
|
||||
@tab pnpm
|
||||
|
||||
```sh
|
||||
corepack enable
|
||||
corepack use pnpm@8
|
||||
```
|
||||
|
||||
:::
|
||||
96
docs/notes/theme/guide/markdown/隐秘文本.md
Normal file
96
docs/notes/theme/guide/markdown/隐秘文本.md
Normal file
@ -0,0 +1,96 @@
|
||||
---
|
||||
title: 隐秘文本
|
||||
createTime: 2024/09/30 14:45:35
|
||||
icon: weui:eyes-off-outlined
|
||||
permalink: /guide/markdown/plot/
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
有时候，你不想直接把文本内容毫无保留的展示出来，想要保留一些 隐秘性，
|
||||
可能是为了引起读者的好奇心，也可能纯粹是故意增加点阅读障碍，让文章变得更加有趣。
|
||||
|
||||
为了满足这种小小的心思，主题提供了一个 **“隐秘”文本** 的有趣小功能。它看起来像这样：
|
||||
|
||||
:::demo-wrapper
|
||||
你知道吗， !!鲁迅!! 曾说过：“ !!我没说过这句话！!! ” 令我醍醐灌顶，深受启发，浑身迸发出无可匹敌的
|
||||
力量！于是，!!我在床上翻了个身!! ！
|
||||
:::
|
||||
|
||||
读者不能直接阅读到完整的内容，部分的内容被 “遮住”，需要鼠标悬停到内容上，才能看到被遮住的内容。
|
||||
|
||||
## 配置
|
||||
|
||||
该功能默认不启用，你需要在 `theme` 配置中启用。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/config.ts
|
||||
|
||||
```ts
|
||||
export default defineUserConfig({
|
||||
theme: plumeTheme({
|
||||
plugins: {
|
||||
markdownPower: {
|
||||
plot: true,
|
||||
},
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
`markdownPower.plot` 支持传入 `boolean | PlotOptions` 类型
|
||||
|
||||
```ts
|
||||
interface PlotOptions {
|
||||
/**
|
||||
* 是否启用 `!! !!` markdown （该标记为非标准标记，脱离插件将不生效）
|
||||
* 如果设置为 false， 则表示不启用该标记，只能使用 <Plot /> 组件
|
||||
* @default true
|
||||
*/
|
||||
tag?: boolean
|
||||
|
||||
/**
|
||||
* 遮罩层颜色
|
||||
*/
|
||||
mask?: string | { light: string, dark: string }
|
||||
|
||||
/**
|
||||
* 文本颜色
|
||||
*/
|
||||
color?: string | { light: string, dark: string }
|
||||
|
||||
/**
|
||||
* 触发方式
|
||||
*
|
||||
* @default 'hover'
|
||||
*/
|
||||
trigger?: 'hover' | 'click'
|
||||
}
|
||||
```
|
||||
|
||||
## 语法
|
||||
|
||||
```md
|
||||
!!需要隐秘的内容!!
|
||||
```
|
||||
|
||||
如果不想使用 非标准的 `!! !!` 标记语法，你可以将 `plot.tag` 设置为 `false` ，
|
||||
然后使用 [`<Plot />`](/guide/features/component/#plot) 组件替代。
|
||||
|
||||
## 示例
|
||||
|
||||
输入：
|
||||
|
||||
```md
|
||||
你知道吗， !!鲁迅!! 曾说过：“ !!我没说过这句话！!! ” 令我醍醐灌顶，深受启发，浑身迸发出无可匹敌的
|
||||
力量！于是，!!我在床上翻了个身!! ！
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
:::demo-wrapper
|
||||
你知道吗， !!鲁迅!! 曾说过：“ !!我没说过这句话！!! ” 令我醍醐灌顶，深受启发，浑身迸发出无可匹敌的
|
||||
力量！于是，!!我在床上翻了个身!! ！
|
||||
:::
|
||||
@ -9,20 +9,29 @@ tags:
|
||||
- i18n
|
||||
---
|
||||
|
||||
在主题内实现 ==国际化== 只需要进行一些简单的配置。
|
||||
|
||||
举一个例子，创建一个 默认语言为 **中文**，并包含 **英语** 和 **法语** 的项目。
|
||||
|
||||
## 目录
|
||||
|
||||
要使用内置的 i18n (国际化) 功能，需要创建类似于下面的目录结构：
|
||||
首先，需要创建类似于下面的目录结构：
|
||||
|
||||
::: file-tree
|
||||
|
||||
- docs
|
||||
- en
|
||||
- foo.md
|
||||
- README.md \# 英文首页
|
||||
- fr
|
||||
- foo.md
|
||||
- README.md \# 法文首页
|
||||
- foo.md
|
||||
- README.md \# 中文首页
|
||||
:::
|
||||
|
||||
其中，`docs/en/` 用于保存 **英文** 文档，`docs/fr/` 保存 **法文** 文档，而 **中文** 则直接保存在 `docs/` 下。
|
||||
|
||||
::: important
|
||||
在不同的语言目录下，请尽量保持文件名和目录名的一致。这有助于在 切换语言时，主题能够正确的导航到 文章
|
||||
的不同的语言版本。
|
||||
@ -30,26 +39,29 @@ tags:
|
||||
|
||||
## vuepress 配置
|
||||
|
||||
在 `.vuepress/config.js` 中配置：
|
||||
接下来，在 `.vuepress/config.js` 中配置：
|
||||
|
||||
```js
|
||||
import { defineUserConfig } from 'vuepress'
|
||||
|
||||
export default defineUserConfig({
|
||||
// 声明默认的语言
|
||||
lang: 'en-US',
|
||||
lang: 'zh-CN',
|
||||
// 多语言下支持的各种语言 locales
|
||||
locales: {
|
||||
// 配置 不同 path 下的语言
|
||||
'/': { lang: 'en-US', title: 'Blog' }, // default
|
||||
'/zh/': { lang: 'zh-CN', title: '博客' }, // 简体中文
|
||||
'/': { lang: 'zh-CN', title: '博客' }, // 默认语言 为 简体中文
|
||||
'/en/': { lang: 'en-US', title: 'Blog' }, // 英文
|
||||
'/fr/': { lang: 'fr-FR', title: 'Le blog' }, // 法语
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
`locales` 中的 `key` 对应着 `docs` 目录下的语言路径，同时，`key` 也将作为 不同语言的页面访问链接的前缀。
|
||||
|
||||
## 主题配置
|
||||
|
||||
在本主题中，同样使用 `locales` 配置项进行多语言配置。
|
||||
在主题配置中，同样使用 `locales` 配置项进行多语言配置。
|
||||
|
||||
`locales` 支持 所有主题配置项。
|
||||
|
||||
@ -58,28 +70,40 @@ import { plumeTheme } from '@vuepress-plume/vuepress-theme-plume'
|
||||
import { defineUserConfig } from 'vuepress'
|
||||
|
||||
export default defineUserConfig({
|
||||
lang: 'en-US',
|
||||
lang: 'zh-CN',
|
||||
locales: {
|
||||
'/': { lang: 'en-US', title: 'Blog' }, // default
|
||||
'/zh/': { lang: 'zh-CN', title: '博客' }, // 简体中文
|
||||
'/': { lang: 'zh-CN', title: '博客' }, // 默认语言 为 简体中文
|
||||
'/en/': { lang: 'en-US', title: 'Blog' }, // 英文
|
||||
'/fr/': { lang: 'fr-FR', title: 'Le blog' }, // 法语
|
||||
},
|
||||
theme: plumeTheme({
|
||||
// 主题内的多语言配置
|
||||
locales: {
|
||||
'/': {
|
||||
selectLanguageName: 'English',
|
||||
navbar: [
|
||||
{ text: 'Home', link: '/' },
|
||||
{ text: 'Blog', link: '/blog/' },
|
||||
]
|
||||
},
|
||||
'/zh/': {
|
||||
// 当前语言显示在导航栏多语言下拉菜单的文本
|
||||
selectLanguageName: '简体中文',
|
||||
navbar: [
|
||||
{ text: '首页', link: '/zh/' },
|
||||
{ text: '博客', link: '/zh/blog/' },
|
||||
{ text: '首页', link: '/' },
|
||||
{ text: '博客', link: '/blog/' },
|
||||
]
|
||||
},
|
||||
'/en/': {
|
||||
selectLanguageName: 'English',
|
||||
navbar: [
|
||||
{ text: 'Home', link: '/en/' },
|
||||
{ text: 'Blog', link: '/en/blog/' },
|
||||
]
|
||||
},
|
||||
'/fr/': {
|
||||
selectLanguageName: 'Français',
|
||||
navbar: [
|
||||
{ text: 'Accueil', link: '/fr/' },
|
||||
{ text: 'Le Blog', link: '/fr/blog/' },
|
||||
]
|
||||
}
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
更多 `locales` 配置请查看 [主题配置 > Locales 配置](../config/主题配置.md#locale-配置)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user