--- title: "@mdit/plugin-embed" shortTitle: "plugin-embed" icon: code --- 在 Markdown 中嵌入外部内容的插件。 ## 使用 ::: code-tabs#language @tab TS ```ts import { embed } from "@mdit/plugin-embed"; import MarkdownIt from "markdown-it"; const md = new MarkdownIt().use(embed, { config: [ { name: "youtube", setup: (id: string) => ``, }, { name: "icon", allowInline: true, setup: (name: string) => ``, }, ], }); ``` @tab JS ```js import { embed } from "@mdit/plugin-embed"; import MarkdownIt from "markdown-it"; const md = new MarkdownIt().use(embed, { config: [ { name: "youtube", setup: (id) => ``, }, { name: "icon", allowInline: true, setup: (name) => ``, }, ], }); ``` ::: ## 语法 插件解析以下格式的嵌入语法: ```md {% name params %} ``` 其中: - `name` 是嵌入类型标识符 - `params` 是传递给设置函数的参数 ::: tip 转义 要按字面量显示嵌入语法,可以用反斜杠转义起始标记(`\{%`),或用 `%\}` 转义结束括号;整段嵌入只需转义起始标记即可: ```md \{% name params %} ``` 如果要在嵌入内容中写入标记,只转义内容里的标记,外层嵌入保持不转义: ```md {% name params-containing-\{%value%\} %} ``` ::: ## 选项 ::: fields @`config` type=`EmbedConfig[]` required 嵌入配置数组。 ```ts interface EmbedConfig { /** 嵌入令牌名称 */ name: string; /** * 生成嵌入 HTML 的设置函数 * * @param ref 参数 * @param isInline 如果 allowInline 为 true,则 isInline 表示当前匹配的内容原文是否是 inline * @returns */ setup: (ref: string, isInline: boolean) => string; /** * 是否允许在行内使用 * * @default false */ allowInline?: boolean; } ``` @@`config.name` type=string 在嵌入语法中使用的令牌名称。 @@`config.setup` type=`(ref: string, isInline: boolean) => string` 接受参数并返回要嵌入的 HTML 字符串的函数。 @@`config.allowInline` type=boolean default=`false` 是否允许在行内使用。设为 `false` 时仅在块级使用。 当 `allowInline` 设置为 `true` 时,嵌入既可以在块级使用(单独一行),也可以在行内使用(段落中)。 ::: ## 示例 基于上面的使用示例,支持以下嵌入: **输入:** ```md {% youtube dQw4w9WgXcQ %} ``` **输出:** ```html ``` **输入:** ```md 点击 {% icon home %} 按钮回到首页。 ``` **输出:** ```html 点击 按钮回到首页。 ``` ## 高级用法 ### 复杂参数处理 你可以在 `setup` 函数中处理复杂的参数: ```ts const md = new MarkdownIt().use(embed, { config: [ { name: "video", setup: (params: string, isInline: boolean) => { // 解析参数:src width height const [src, width = "560", height = "315"] = params.split(" "); return ``; }, }, ], }); ``` **输入:** ```md {% video https://example.com/video.mp4 800 600 %} ``` ### 多个嵌入类型 你可以配置多种不同的嵌入类型: ```ts const md = new MarkdownIt().use(embed, { config: [ // YouTube { name: "youtube", setup: (id) => ``, }, // Bilibili { name: "bilibili", setup: (bvid) => ``, }, // 自定义 HTML { name: "alert", setup: (message) => `
${message}
`, }, ], }); ``` **使用:** ```md {% youtube dQw4w9WgXcQ %} {% bilibili BV1xx411c7mu %} {% alert 这是一个重要提示! %} ``` ## 注意事项 1. **安全性**: 请确保在 `setup` 函数中正确处理用户输入,避免 XSS 攻击 2. **性能**: 对于大量嵌入内容,考虑使用懒加载 3. **兼容性**: 确保生成的 HTML 与你的目标环境兼容 ## 迁移指南 如果你正在从其他嵌入插件迁移,这里是一些常见的迁移示例: ### 从 markdown-it-video 迁移 ```ts // 之前 md.use(video); // 现在 md.use(embed, { config: [ { name: "video", setup: (src) => ``, }, ], }); ``` ### 从 markdown-it-youtube 迁移 ```ts // 之前 md.use(youtube); // 现在 md.use(embed, { config: [ { name: "youtube", setup: (id) => ``, }, ], }); ```