docs: update doc

docs/.vuepress/notes.ts

@@ -33,6 +33,12 @@ export const zhNotes = definePlumeNotesConfig({
               dir: '图表',
               items: ['chart', 'echarts', 'mermaid', 'flowchart'],
             },
+            {
+              text: '资源嵌入',
+              icon: 'dashicons:embed-video',
+              dir: '嵌入',
+              items: ['pdf', 'bilibili', 'youtube'],
+            },
           ],
         },
         {

docs/.vuepress/theme.ts

@@ -72,6 +72,7 @@ export const theme: Theme = themePlume({
       bilibili: true,
       youtube: true,
       icons: true,
+      codepen: true,
     },
     comment: {
       provider: 'Giscus',

docs/notes/theme/guide/markdown/进阶.md

@@ -6,6 +6,108 @@ createTime: 2024/03/05 16:27:59
 permalink: /guide/markdown/advance/
 ---
 
+## iconify 图标
+
+在 Markdown 文件中使用 [iconify](https://iconify.design/) 的图标。 主题虽然提供了
+[`<Iconify />`](/guide/features/component/#iconify) 组件来支持在 markdown 中使用图标，
+但是它需要从远程加载图标，可能速度比较慢。
+
+为此，主题提供了另一种可选的方式，以更简单的方式，在 Markdown 中使用图标，并且将 图标资源编译到
+本地静态资源中。
+
+### 配置
+
+该功能默认不启用，你需要在 `theme` 配置中启用。
+
+::: code-tabs
+@tab .vuepress/config.ts
+
+```ts
+export default defineUserConfig({
+  theme: plumeTheme({
+    plugins: {
+      markdownPower: {
+        icons: true,
+      },
+    }
+  })
+})
+```
+
+:::
+
+同时，该功能还需要你额外安装 `@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]:
+```
+
+输出：
+
+github: :[tdesign:logo-github-filled]:
+修改颜色：:[tdesign:logo-github-filled /#f00]:
+修改大小：:[tdesign:logo-github-filled 36px]:
+修改大小颜色：:[tdesign:logo-github-filled 36px/#f00]:
+
 ## 选项组
 
 让你的 Markdown 文件支持选项卡。
@@ -196,6 +298,25 @@ corepack use pnpm@8
 
 ## 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 时，能更直观的表述 该特性的支持程度。
@@ -203,30 +324,19 @@ corepack use pnpm@8
 在你的 文章 markdown文件中，使用以下格式：
 
 ``` md
-::: caniuse <feature> {browser_versions}
+@[caniuse](feature)
-:::
 ```
 
-**示例： 获取 css 伪类选择器 `:dir()` 在各个浏览器的支持情况图标：**
-
-``` md
-::: caniuse css-matches-pseudo
-:::
-```
-
-效果：
-
-::: caniuse css-matches-pseudo
-:::
-
 ### 语法
 
 ``` md
-::: caniuse <feature> {browser_versions}
+@[caniuse](feature)
-:::
+@[caniuse{browser_versions}](feature)
+@[caniuse embed_type](feature)
+@[caniuse embed_type{browser_versions}](feature)
 ```
 
-- `<feature>`
+- `feature`
 
    必填。 正确取值请参考 [https://caniuse.bitsofco.de/](https://caniuse.bitsofco.de/)
 
@@ -242,6 +352,130 @@ corepack use pnpm@8
   - `0` 表示当前浏览器版本的支持情况
   - 大于`0` 表示高于当前浏览器版本的支持情况
 
+- `embed_type`
+
+  可选。 资源嵌入的类型。
+
+  类型： `'embed' | 'image'`
+
+  默认值为：`'embed'`
+
+### 示例
+
+**获取 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,-1,1,2,3}](css-matches-pseudo)
+```
+
+效果：
+
+@[caniuse{-2,-1,1,2,3}](css-matches-pseudo)
+
+## CodePen
+
+主题支持在 Markdown 文件中嵌入 [CodePen](https://codepen.io/)。
+
+### 配置
+
+此功能默认不启用，你可以在配置文件中启用它。
+
+::: code-tabs
+@tab .vuepress/config.ts
+
+```ts
+export default defineUserConfig({
+  theme: plumeTheme({
+    plugins: {
+      markdownPower: {
+        codepen: true, // [!code highlight]
+      },
+    }
+  })
+})
+```
+
+:::
+
+### 语法
+
+简单语法：
+
+```md
+@[codepen](user/slash)
+```
+
+更多选项支持：
+
+```md
+@[codepen preview editable tab="css,result" theme="dark" height="500px" width="100%"](user/slash)
+```
+
+- `preview`: 是否渲染为预览模式
+- `editable`: 是否可编辑
+- `tab`: 默认显示的标签， 默认为 `result`，多个使用 `,` 分隔
+- `theme`: 主题， 可选值 `dark` 和 `light`
+- `height`: 容器高度， 默认为 `400px`
+- `width`: 容器宽度， 默认为 `100%`
+- `user`: CodePen 用户名
+- `slash`: CodePen 代码文件名
+
+### 示例
+
+输入：
+
+```md
+@[codepen](leimapapa/RwOZQOW)
+```
+
+输出：
+
+@[codepen](leimapapa/RwOZQOW)
+
+**预览模式：**
+
+输入：
+
+```md
+@[codepen preview](leimapapa/RwOZQOW)
+```
+
+输出：
+
+@[codepen preview](leimapapa/RwOZQOW)
+
+**编辑模式：**
+
+输入：
+
+```md
+@[codepen editable tab="html,result"](leimapapa/RwOZQOW)
+```
+
+输出：
+
+@[codepen editable tab="html,result"](leimapapa/RwOZQOW)
+
 ## 导入文件
 
 主题支持在 Markdown 文件中导入文件切片。

docs/notes/theme/guide/嵌入/bilibili.md

@@ -0,0 +1,95 @@
+---
+title: Bilibili 视频
+author: pengzhanbo
+icon: ri:bilibili-fill
+createTime: 2024/03/28 12:26:47
+permalink: /guide/embed/video/bilibili/
+---
+
+## 概述
+
+有时候，你想在你的文档中嵌入视频，以提高内容的表达能力。
+
+主题提供了 嵌入 Bilibili 视频 的功能。
+
+该功能由 [vuepress-plugin-md-power](/) 提供支持。
+
+## 配置
+
+该功能默认不启用。你需要在主题配置中开启。
+
+::: code-tabs
+@tab .vuepress/config.ts
+
+```ts
+export default defineUserConfig({
+  theme: plumeTheme({
+    plugins: {
+      markdownPower: {
+        bilibili: true,
+      },
+    }
+  })
+})
+```
+
+:::
+
+## 语法
+
+简单的语法：
+
+```md
+@[bilibili](bvid)
+```
+
+带 分P 的视频，在 `bilibili` 后跟随 `p1`、`p2`、`p3` 等选项
+
+```md
+@[bilibili p1](aid cid)
+```
+
+更多选项：
+
+```md
+@[bilibili p1 autoplay time="0" width="100%" height="400px" ratio="16:9"](bvid aid cid)
+```
+
+**选项说明：**
+
+- bvid: 视频 BV ID
+- aid: 视频 AID
+- cid: 视频 CID
+- autoplay: 是否自动播放
+- time: 视频开始播放时间点，单位为秒， 也可以使用 `mm:ss` 或 `hh:mm:ss` 格式
+- width: 视频宽度
+- height: 视频高度
+- ratio: 视频比例，默认 `16:9`
+
+对于分P的视频，可以省略传入 `bvid`，但需要传入 `aid` 和 `cid`
+
+## 示例
+
+### 宽频视频
+
+输入：
+
+```md
+@[bilibili](BV1EZ42187Hg)
+```
+
+输出：
+
+@[bilibili](BV1EZ42187Hg)
+
+### 竖屏视频
+
+输入：
+
+```md
+@[bilibili width="320px" ratio="9:16"](BV1zr42187eg)
+```
+
+输出：
+
+@[bilibili width="320px" ratio="9:16"](BV1zr42187eg)

docs/notes/theme/guide/嵌入/pdf.md

@@ -0,0 +1,122 @@
+---
+title: PDF 阅读
+author: pengzhanbo
+icon: teenyicons:pdf-outline
+createTime: 2024/03/28 13:30:53
+permalink: /guide/embed/pdf/
+---
+
+## 概述
+
+主题支持在 markdown 中嵌入 PDF 文件，它能够在页面中直接阅读 PDF 。
+
+该功能由 [vuepress-plugin-md-power](/) 提供支持。
+
+## 配置
+
+该功能默认不启用。你需要在主题配置中开启。
+
+::: code-tabs
+@tab .vuepress/config.ts
+
+```ts
+export default defineUserConfig({
+  theme: plumeTheme({
+    plugins: {
+      markdownPower: {
+        pdf: true,
+      },
+    }
+  })
+})
+```
+
+:::
+
+## 语法
+
+最简单的语法如下：
+
+```md
+@[pdf](url)
+```
+
+当需要打开特定页面时，在 `pdf` 后面跟随一个 页数。
+
+```md
+@[pdf 2](url)
+```
+
+还可以添加更多的 选项到 `@[pdf ]` 中，更灵活的控制行为。
+
+```md
+@[pdf 2 no-toolbar width="100%" height="400px" ratio="16:9" zoom="100"](url)
+```
+
+- `no-toolbar` - 不显示工具栏
+- `width` - 宽度，默认为 100%
+- `height` - 高度，默认为 `auto`
+- `ratio` - 宽高比, 默认为 `16:9`, 仅当未指定高度时生效
+- `zoom` - 缩放比例, 百分比。
+
+## 示例
+
+### 默认
+
+输入：
+
+```md
+@[pdf](https://plume.pengzhanbo.cn/files/sample.pdf)
+```
+
+输出：
+
+@[pdf](/files/sample.pdf)
+
+### 设置页码为 2
+
+输入：
+
+```md
+@[pdf 2](https://plume.pengzhanbo.cn/files/sample.pdf)
+```
+
+输出：
+
+@[pdf 2 zoom="95"](/files/sample.pdf)
+
+### 不显示工具栏
+
+输入：
+
+```md
+@[pdf no-toolbar](https://plume.pengzhanbo.cn/files/sample.pdf)
+```
+
+输出：
+
+@[pdf no-toolbar](/files/sample.pdf)
+
+### 缩放比 90%
+
+输入：
+
+```md
+@[pdf zoom="90"](https://plume.pengzhanbo.cn/files/sample.pdf)
+```
+
+输出：
+
+@[pdf zoom="90"](/files/sample.pdf)
+
+### 宽高比 21:29
+
+输入：
+
+```md
+@[pdf zoom="95" ratio="21:29"](https://plume.pengzhanbo.cn/files/sample.pdf)
+```
+
+输出：
+
+@[pdf zoom="95" ratio="21:29"](/files/sample.pdf)

docs/notes/theme/guide/嵌入/youtube.md

@@ -0,0 +1,75 @@
+---
+title: Youtube 视频
+author: pengzhanbo
+icon: mdi:youtube
+createTime: 2024/03/28 14:30:33
+permalink: /guide/embed/video/youtube/
+---
+
+## 概述
+
+有时候，你想在你的文档中嵌入视频，以提高内容的表达能力。
+
+主题提供了 嵌入 Youtube 视频 的功能。
+
+该功能由 [vuepress-plugin-md-power](/) 提供支持。
+
+## 配置
+
+该功能默认不启用。你需要在主题配置中开启。
+
+::: code-tabs
+@tab .vuepress/config.ts
+
+```ts
+export default defineUserConfig({
+  theme: plumeTheme({
+    plugins: {
+      markdownPower: {
+        youtube: true,
+      },
+    }
+  })
+})
+```
+
+:::
+
+## 语法
+
+简单的语法：
+
+```md
+@[youtube](id)
+```
+
+更多选项：
+
+```md
+@[youtube autoplay loop start="0" end="0" width="100%" height="400px" ratio="16:9"](id)
+```
+
+**选项说明：**
+
+- id: 视频 ID
+- autoplay: 是否自动播放
+- loop: 是否循环播放
+- start: 视频开始播放时间点，单位为秒， 也可以使用 `mm:ss` 或 `hh:mm:ss` 格式
+- end: 视频结束播放时间点，单位为秒， 也可以使用 `mm:ss` 或 `hh:mm:ss` 格式
+- width: 视频宽度
+- height: 视频高度
+- ratio: 视频比例，默认 `16:9`
+
+## 示例
+
+### 宽频视频
+
+输入：
+
+```md
+@[youtube](0JJPfz5dg20)
+```
+
+输出：
+
+@[youtube](0JJPfz5dg20)

plugins/plugin-md-power/README.md

@@ -0,0 +1,163 @@
+# vuepress-plugin-md-power
+
+为 vuepress 提供 丰富的 markdown 语法支持。
+
+## 功能
+
+- caniuse 支持，提供前端各种特性在各个浏览器版本中的支持情况查看器
+- 嵌入 PDF 支持
+- 嵌入 视频支持，当前支持嵌入 bilibili 和 youtube 的视频
+- 内联 iconify 图标支持
+
+## 安装
+
+```sh
+pnpm add vuepress-plugin-md-power
+```
+
+## 使用
+
+```ts
+import { defineUserConfig } from 'vuepress'
+import { md } from 'vuepress-plugin-md-power'
+
+export default defineUserConfig({
+  plugins: [
+    markdownPowerPlugin({
+      caniuse: true,
+      pdf: true,
+      bilibili: true,
+      youtube: true,
+      icons: true,
+    })
+  ]
+})
+```
+
+### caniuse
+
+插件默认不启用该功能，你需要手动设置 `caniuse` 为 `true`
+
+#### 语法
+
+```md
+@[caniuse](feature)
+@[caniuse image](feature)
+@[caniuse embed{versions}](feature)
+```
+
+你可以从 [caniuse](https://caniuse.bitsofco.de/) 获取 feature 的值。
+
+默认情况下，插件通过 `iframe` 嵌入 `caniuse` 的支持情况查看器。
+你也可以使用 `@[caniuse image](feature)` 直接嵌入图片。
+
+caniuse 默认查看最近的5个浏览器版本。你可以通过 `{versions}` 手动设置查看的浏览器版本。
+格式为 `{number,number,...}`。取值范围为 `-5 ~ 3` 。
+
+- 小于0 表示低于当前浏览器版本的支持情况
+- 0 表示当前浏览器版本的支持情况
+- 大于0 表示高于当前浏览器版本的支持情况
+
+如 `{-2,-1,1,2}` 表示查看低于当前 2 个版本 到 高于当前 2 个版本的支持情况。
+
+### pdf
+
+插件默认不启用该功能，你需要手动设置 `pdf` 为 `true`
+
+#### 语法
+
+```md
+@[pdf](url)
+@[pdf 1](url)
+@[pdf 1 no-toolbar width="100%" height="600px" zoom="1" ratio="16:9"](url)
+```
+
+`url` 只支持绝对路径以及完整的资源链接地址，请勿传入相对路径。
+
+你可以在 `pdf` 后紧跟空格，设置一个数字表示默认显示的  pdf 页码
+
+- `no-toolbar` 表示不显示工具栏
+- `width` 设置宽度
+- `height` 设置高度
+- `zoom` 设置缩放
+- `ratio` 设置宽高比， 仅当 `width` 有值， `height` 未设置时有效
+
+### icons
+
+插件默认不启用该功能，你需要手动设置 `icons` 为 `true`。
+
+你还需要手动安装 `@iconify/json` 依赖。
+
+```sh
+pnpm add @iconify/json
+```
+
+#### 语法
+
+```md
+:[collect:icon]:
+:[collect:icon size]:
+:[collect:icon /color]:
+:[collect:icon size/color]:
+```
+
+你可以从 [icon-sets.iconify](https://icon-sets.iconify.design/) 获取 图标集。
+
+显示 `logos` 图标集合下的 `vue` 图标
+
+```md
+:[logos:vue]:
+```
+
+图标默认大小为 `1em` ，你可以通过 `size` 设置图标大小
+
+```md
+:[logos:vue 1.2em]:
+```
+
+图标默认颜色为 `currentColor` 你可以通过 `/color` 设置图标颜色
+
+```md
+:[logos:vue /blue]:
+```
+
+也可以通过 `size/color` 设置图标大小和颜色
+
+```md
+:[logos:vue 1.2em/blue]:
+```
+
+### bilibili
+
+插件默认不启用该功能，你需要手动设置 `bilibili` 为 `true`
+
+#### 语法
+
+```md
+@[bilibili](bvid)
+@[bilibili autoplay time="0"](bvid)
+@[bilibili p1 autoplay time="0" ratio="16:9"](aid cid)
+```
+
+- 设置 `autoplay` 以自动播放视频。
+- 设置 `time` 以指定开始播放的时间点，单位为秒。还可以传入 `mm:ss` 或者 `hh:mm:ss`。
+- 如果为 分p（非合集），还可以设置 `p\d` （第\d 个分p），此时可以只传入 `aid` 和 `cid`。
+- 设置 `ratio` 以指定视频的宽高比。
+
+### youtube
+
+插件默认不启用该功能，你需要手动设置 `youtube` 为 `true`
+
+#### 语法
+
+```md
+@[youtube](id)
+@[youtube autoplay loop ratio="16:9" star="0" end="0"](id)
+```
+
+- `id` 为 YouTube 视频 ID
+- `autoplay` 为是否自动播放
+- `loop` 为是否循环播放
+- `ratio` 为视频的宽高比
+- `star` 为开始时间，单位为秒，还可以传入 `mm:ss` 或者 `hh:mm:ss`。
+- `end` 为结束时间，单位为秒，还可以传入 `mm:ss` 或者 `hh:mm:ss`。

plugins/plugin-md-power/src/node/features/pdf.ts

@@ -4,7 +4,7 @@
  * @[pdf 1 no-toolbar width="100%" height="600px" zoom="1" ratio="1:1"](/xxx)
  */
 import { path } from 'vuepress/utils'
-import type { PluginWithOptions, Token } from 'markdown-it'
+import type { PluginWithOptions } from 'markdown-it'
 import type { RuleBlock } from 'markdown-it/lib/parser_block.js'
 import type { PDFTokenMeta } from '../../shared/pdf.js'
 import { resolveAttrs } from '../utils/resolveAttrs.js'

plugins/plugin-md-power/src/node/plugin.ts

@@ -6,6 +6,7 @@ import { pdfPlugin } from './features/pdf.js'
 import { createIconCSSWriter, iconsPlugin } from './features/icons/index.js'
 import { bilibiliPlugin } from './features/video/bilibili.js'
 import { youtubePlugin } from './features/video/youtube.js'
+import { codepenPlugin } from './features/codepen.js'
 
 const __dirname = getDirname(import.meta.url)
 
@@ -52,6 +53,11 @@ export function markdownPowerPlugin(options: MarkdownPowerPluginOptions = {}): P
           // @[youtube](id)
           md.use(youtubePlugin)
         }
+
+        if (options.codepen) {
+          // @[codepen](user/slash)
+          md.use(codepenPlugin)
+        }
       },
     }
   }

plugins/plugin-md-power/src/shared/index.ts

@@ -1,3 +1,6 @@
 export * from './caniuse.js'
 export * from './pdf.js'
+export * from './icons.js'
+export * from './video.js'
+export * from './codepen.js'
 export * from './plugin.js'

plugins/plugin-md-power/src/shared/plugin.ts

@@ -3,9 +3,16 @@ import type { PDFOptions } from './pdf.js'
 import type { IconsOptions } from './icons.js'
 
 export interface MarkdownPowerPluginOptions {
-  caniuse?: boolean | CanIUseOptions
+
   pdf?: boolean | PDFOptions
   icons?: boolean | IconsOptions
+
+  // video
   bilibili?: boolean
   youtube?: boolean
+
+  // code
+  codepen?: boolean
+
+  caniuse?: boolean | CanIUseOptions
 }