Vitepress 中 Markdown 图片自定义渲染的注意事项

在 Vitepress 项目中，开发者经常需要对 Markdown 中的图片进行自定义渲染。一个常见的需求是获取图片的 alt 属性值并对其进行特殊处理。本文将深入探讨这一技术点，帮助开发者理解其中的原理和注意事项。

问题背景

当开发者尝试通过自定义渲染器获取图片的 alt 属性时，可能会遇到无法获取值的情况。这是因为 Markdown 解析器对不同类型的图片语法有不同的处理方式。

两种图片语法解析

1. 标准 Markdown 图片语法

对于标准的 Markdown 图片语法：

![图 14-1](/page_214_1.png)

解析器会生成一个 image token，其中 alt 文本存储在 token.content 属性中。

2. HTML 图片标签

对于直接使用 HTML 的图片标签：

<img src="/page_214_1.png" alt="图 14-1" style="zoom:25%;" />

解析器会将其视为 html_block token，而不是 image token，因此无法通过常规的图片渲染器获取属性。

解决方案

对于标准 Markdown 图片

使用以下方式获取 alt 文本：

md.renderer.rules.image = (tokens, idx, options, env, self) => {
    const token = tokens[idx];
    const alt = token.content;  // 注意这里是 content 而不是 attrGet('alt')
    // ...其他处理逻辑
}

对于 HTML 图片标签

如果需要处理 HTML 图片标签，有以下几种方案：

1. 使用正则表达式解析：从 html_block token 中提取 alt 属性
2. 自定义 HTML 解析规则：扩展 markdown-it 的解析能力
3. 统一使用标准 Markdown 语法：这是推荐的做法，可以保持一致性

最佳实践建议

1. 在 Vitepress 项目中，尽量使用标准的 Markdown 图片语法
2. 如果需要特殊样式，可以通过 CSS 类来实现，而不是直接使用 HTML
3. 对于复杂的图片处理需求，考虑编写专门的插件来处理

总结

理解 Markdown 解析器对不同语法的处理方式是解决问题的关键。在 Vitepress 中自定义图片渲染时，开发者需要根据实际使用的语法选择合适的处理方式。标准 Markdown 语法通常能提供更好的兼容性和可维护性。