Quarto项目中视频嵌入短代码的正确使用方式

在Quarto项目中使用视频嵌入功能时，开发者需要注意短代码的书写规范。近期有用户反馈在Visual Editor中视频嵌入标签会被破坏的问题，这实际上是由于短代码格式不规范导致的。

问题现象

当用户使用以下格式嵌入视频时：

{{<video "filename.mp4" >}}

在Visual Editor中会被转换为：

{{\<video "filename.mp4" \>}}

这种转换会导致视频嵌入功能失效。

根本原因

Quarto的短代码解析器要求短代码名称与开头的双花括号之间必须保留一个空格。这是Quarto短代码的标准语法规范。

正确写法

正确的视频嵌入短代码格式应为：

{{< video "filename.mp4" >}}

注意：

1. {{<和短代码名称video之间有一个空格
2. 短代码名称和参数之间也有空格
3. 结尾的>前保留空格

技术细节

Quarto的短代码处理器会严格解析这种格式：

1. 开头的{{<标识短代码开始
2. 空格作为分隔符
3. 短代码名称（如video）
4. 参数部分
5. 结尾的>

这种格式规范确保了：

• Visual Editor能正确识别短代码结构
• 渲染引擎能准确解析嵌入内容
• 保持文档结构的一致性

最佳实践建议

1. 始终在短代码名称前后保留空格
2. 对于复杂参数，考虑使用命名参数格式
3. 在提交前使用预览功能验证嵌入效果
4. 对于团队协作项目，建立统一的短代码书写规范

总结

Quarto作为现代化的文档创作工具，其短代码系统提供了强大的内容嵌入能力。遵循正确的语法规范不仅能避免Visual Editor中的解析问题，还能确保文档在各种输出格式中都能正确渲染。视频嵌入作为常见需求，掌握其正确用法对提升文档质量至关重要。