本文详细介绍了如何利用 marked.js 的 renderer 选项，自定义 Markdown 中图片元素的渲染行为。通过覆盖默认的 image 方法，您可以实现对非标准图片语法（如 Obsidian 风格的 ![[文件名]]）的解析，并为图片 URL 动态添加自定义前缀（例如 images/），从而生成符合特定需求的 HTML 标签，提升 Markdown 渲染的灵活性。
在使用 marked.js 将 Markdown 内容转换为 HTML 时，开发者经常会遇到需要自定义图片渲染逻辑的场景。这可能包括处理非标准的图片链接语法（例如 ![[文件名.jpg]] 这种在某些 Markdown 编辑器中常见的内部链接格式），或者为所有图片 URL 统一添加一个特定的前缀（如 images/），以确保图片资源能够正确加载。marked.js 提供了强大的 renderer 机制，允许我们完全控制各种 Markdown 元素的 HTML 输出。
marked.js 图片渲染的默认行为与挑战
marked.js 默认遵循 CommonMark 规范来解析图片链接，即  格式。对于 ![[文件名.jpg]] 这种非标准语法，marked.js 可能无法识别其为图片，或者即使识别，也无法直接满足自定义 URL 前缀的需求。例如，如果 Markdown 内容是 ![[20230613_110437.jpg]]，直接使用 marked.parse(content) 可能会原样输出该字符串，而不是生成 标签。同时，即使图片链接被正确解析，我们也需要一种方式来在其 src 属性前添加 images/ 这样的路径前缀。
利用 marked.Renderer 自定义图片渲染
marked.js 的 Renderer 类提供了一系列方法，对应不同的 Markdown 元素（如标题、段落、链接、图片等）。通过创建 Renderer 实例并覆盖其相应方法，我们可以完全控制这些元素的 HTML 输出。对于图片，我们需要覆盖 renderer.image 方法。
renderer.image 方法接收三个参数：
- href: 图片的 URL 或路径。
- title: 图片的标题（可选）。
- text: 图片的替代文本（alt text）。
通过自定义这个方法，我们可以根据 href 参数的值，构建出我们期望的 标签。
实现自定义图片路径与前缀
以下代码示例展示了如何配置 marked.js 的 renderer 来实现以下目标：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
- 确保 ![[文件名.jpg]] 这种格式的图片能够被解析并渲染为
标签。
- 为所有图片 URL 自动添加 images/ 前缀。
const marked = require('marked');
const path = require('path'); // 如果需要处理本地文件系统路径，可以使用 path 模块
// 创建一个新的 Renderer 实例
const customRenderer = new marked.Renderer();
// 覆盖默认的 image 渲染方法
customRenderer.image = function(href, title, text) {
// 假设 marked.js 已经从 ![[文件名.jpg]] 中提取出 "文件名.jpg" 作为 href
// 如果 href 包含完整的路径或者需要更复杂的解析，这里可以进行字符串处理
let imageUrl = href;
// 检查是否为外部链接，如果是则不添加前缀
// 否则，添加 'images/' 前缀
if (!href.startsWith('http://') && !href.startsWith('https://') && !href.startsWith('//')) {
// 方式一：直接添加前缀（适用于相对路径）
imageUrl = `images/${href}`;
// 方式二：使用 path 模块处理本地文件系统路径（如果你的应用场景是处理本地文件）
// 注意：__dirname 是 Node.js 环境下的当前文件目录
// 如果你的图片目录不是在当前脚本同级的 'images' 文件夹下，你需要调整路径
// imageUrl = path.join('images', href); // 仅适用于构建相对路径，例如 'images/20230613_110437.jpg'
// 或者如果你想生成一个绝对文件系统路径（不常见于Web src），则需要更多上下文
// imageUrl = path.join(__dirname, 'images', href);
}
// 构建并返回自定义的 <img alt="使用 marked.js 自定义图片渲染与路径前缀" > 标签
// 注意：src 和 alt 属性是必须的，title 属性是可选的
return `<img src="${imageUrl}" alt="${text}" ${title ? `title="${title}"` : ''} />`;
};
// 示例 Markdown 内容
const markdownContent = `
这是一个示例文本。
![[20230613_110437.jpg]]
这是另一个图片：
一个外部链接图片：
`;
// 使用自定义的 renderer 来解析 Markdown
const htmlOutput = marked.parse(markdownContent, { renderer: customRenderer });
console.log(htmlOutput);运行上述代码，您将得到类似以下的 HTML 输出：
<p>这是一个示例文本。</p> <p><img src="images/20230613_110437.jpg" alt="" /></p> <p>这是另一个图片： <img src="images/another_image.png" alt="My Image" title="A beautiful picture" /></p> <p>一个外部链接图片： <img src="https://example.com/external.jpg" alt="External Image" /></p>
注意事项与最佳实践
-
![[文件名]] 语法的处理: 上述解决方案假设 marked.js 在解析 ![[文件名.jpg]] 时，能够将其中的 文件名.jpg 作为 href 参数传递给 renderer.image 方法。在某些 marked.js 版本或配置下，如果 ![[文件名]] 这种语法不被视为标准图片链接，renderer.image 可能根本不会被调用。在这种情况下，您可能需要：
- 预处理 Markdown 字符串: 在将 Markdown 传递给 marked.js 之前，使用正则表达式或其他方式将 ![[文件名]] 转换为标准的  格式。
- 使用 marked.js 扩展 (Extensions): marked.js 支持自定义扩展，可以更深入地修改其解析器行为，以识别和处理非标准语法。
- 确保 href 的正确性: 在 customRenderer.image 内部，务必检查 href 的值是否符合预期。如果 href 包含了 [[ 和 ]]，您需要在函数内部对其进行额外的字符串处理，以提取出实际的文件名。
-
路径处理:
- 相对路径: 对于简单的 images/ 前缀，直接使用模板字符串 images/${href} 是最简洁有效的方式。
- 绝对路径与 path 模块: 如果您的应用需要根据文件系统结构生成绝对路径，例如在 Node.js 环境中构建一个本地文件服务器，那么 path.join(__dirname, 'images', href) 这种方式会更加健壮，因为它能正确处理不同操作系统下的路径分隔符。但请注意，__dirname 是 Node.js 特有的全局变量。
- 外部链接: 在添加前缀之前，务必判断 href 是否已经是一个完整的外部 URL（以 http:// 或 https:// 开头），避免重复添加前缀导致链接失效。
替代文本与标题: 确保 alt 属性始终存在，这对于可访问性（Accessibility）至关重要。title 属性可以提供额外的工具提示信息。
总结
通过 marked.js 提供的 renderer 机制，我们可以灵活地定制 Markdown 元素的 HTML 输出。针对图片渲染，覆盖 renderer.image 方法能够有效解决非标准图片语法解析和自定义 URL 前缀的需求。理解 marked.js 的解析流程以及 renderer 方法的参数，是实现高效且符合特定业务逻辑的 Markdown 渲染的关键。在实际应用中，根据具体场景选择合适的路径处理方式，并考虑对非标准语法的健壮性处理，将使您的 Markdown 渲染更加强大和可靠。
