diff --git a/docs/.vuepress/notes.ts b/docs/.vuepress/notes.ts index 911d7245..9ff61d0c 100644 --- a/docs/.vuepress/notes.ts +++ b/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'], + }, ], }, { diff --git a/docs/.vuepress/public/files/sample.pdf b/docs/.vuepress/public/files/sample.pdf new file mode 100644 index 00000000..a46deca2 Binary files /dev/null and b/docs/.vuepress/public/files/sample.pdf differ diff --git a/docs/.vuepress/theme.ts b/docs/.vuepress/theme.ts index 66896825..9aed9138 100644 --- a/docs/.vuepress/theme.ts +++ b/docs/.vuepress/theme.ts @@ -72,6 +72,7 @@ export const theme: Theme = themePlume({ bilibili: true, youtube: true, icons: true, + codepen: true, }, comment: { provider: 'Giscus', diff --git a/docs/notes/theme/guide/markdown/进阶.md b/docs/notes/theme/guide/markdown/进阶.md index b49fac56..4ff9981d 100644 --- a/docs/notes/theme/guide/markdown/进阶.md +++ b/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/) 的图标。 主题虽然提供了 +[``](/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` 都有自己的 +图标。 + +你可以从 中获取 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 {browser_versions} -::: +@[caniuse](feature) ``` -**示例: 获取 css 伪类选择器 `:dir()` 在各个浏览器的支持情况图标:** - -``` md -::: caniuse css-matches-pseudo -::: -``` - -效果: - -::: caniuse css-matches-pseudo -::: - ### 语法 ``` md -::: caniuse {browser_versions} -::: +@[caniuse](feature) +@[caniuse{browser_versions}](feature) +@[caniuse embed_type](feature) +@[caniuse embed_type{browser_versions}](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 文件中导入文件切片。 diff --git a/docs/notes/theme/guide/嵌入/bilibili.md b/docs/notes/theme/guide/嵌入/bilibili.md new file mode 100644 index 00000000..aa5dd7d8 --- /dev/null +++ b/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) diff --git a/docs/notes/theme/guide/嵌入/pdf.md b/docs/notes/theme/guide/嵌入/pdf.md new file mode 100644 index 00000000..11d9881c --- /dev/null +++ b/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) diff --git a/docs/notes/theme/guide/嵌入/youtube.md b/docs/notes/theme/guide/嵌入/youtube.md new file mode 100644 index 00000000..e7c41205 --- /dev/null +++ b/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) diff --git a/plugins/plugin-md-power/README.md b/plugins/plugin-md-power/README.md new file mode 100644 index 00000000..4f562164 --- /dev/null +++ b/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`。 diff --git a/plugins/plugin-md-power/src/node/features/pdf.ts b/plugins/plugin-md-power/src/node/features/pdf.ts index a2a73c55..6a18b5a3 100644 --- a/plugins/plugin-md-power/src/node/features/pdf.ts +++ b/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' diff --git a/plugins/plugin-md-power/src/node/plugin.ts b/plugins/plugin-md-power/src/node/plugin.ts index d40cdb5a..517cb23c 100644 --- a/plugins/plugin-md-power/src/node/plugin.ts +++ b/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) + } }, } } diff --git a/plugins/plugin-md-power/src/shared/index.ts b/plugins/plugin-md-power/src/shared/index.ts index 18925820..7b449022 100644 --- a/plugins/plugin-md-power/src/shared/index.ts +++ b/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' diff --git a/plugins/plugin-md-power/src/shared/plugin.ts b/plugins/plugin-md-power/src/shared/plugin.ts index bfac1a53..17f8565d 100644 --- a/plugins/plugin-md-power/src/shared/plugin.ts +++ b/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 }