本文介绍在 quarto 中正确嵌入原生 html 的方法，重点解决因 yaml 元数据格式错误导致的 html 渲染失败问题，并演示如何构建左右等宽、左侧 gif 背景、右侧居中文本与按钮的响应式页面布局。
本文介绍在 quarto 中正确嵌入原生 html 的方法，重点解决因 yaml 元数据格式错误导致的 html 渲染失败问题，并演示如何构建左右等宽、左侧 gif 背景、右侧居中文本与按钮的响应式页面布局。
Quarto 默认支持在 .qmd 文件中直接编写 HTML，但需严格遵循其文档结构规范：YAML 元数据块（front matter）必须唯一且连续置于文件开头，不可拆分或重复声明。原始代码中将 --- 分割为两段（分别定义 title 和 format），导致 Quarto 解析失败，HTML 内容被忽略或转义输出。
✅ 正确写法是合并 YAML 配置为单个 front matter 块：
--- title: "" format: html ---
随后紧跟 HTML 内容（无需额外 <html> 或 <body> 标签包裹——Quarto 会自动注入完整 HTML 文档结构）。但需注意：直接使用 <body> 标签虽可工作，但更推荐语义化、可维护的写法，即用 <div> 替代，并通过 CSS 控制全屏布局：
Article To Html
下载
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
<div style="
margin: 0;
padding: 0;
display: flex;
height: 100vh;
width: 100vw;
">
<div style="
flex: 1;
background: url('gif_example.gif') no-repeat center center;
background-size: cover;
"></div>
<div style="
flex: 1;
display: flex;
flex-direction: column;
justify-content: center;
align-items: center;
text-align: center;
padding: 2rem;
">
<p>To jest napis na prawej stronie</p>
<button onclick="window.location.href='#'">Przycisk</button>
</div>
</div>? 关键注意事项：
立即学习“前端免费学习笔记（深入）”；
- 路径问题：确保 gif_example.gif 位于 Quarto 项目根目录或 ./images/ 等已配置的静态资源路径下（推荐放入 images/ 文件夹，并引用为 images/gif_example.gif）；
- 交互增强：示例中为按钮添加了 onclick 跳转逻辑，实际使用时请替换 # 为真实 URL（如 https://example.com）或锚点；
- 响应式补充：若需适配移动设备，建议添加媒体查询或使用 Quarto 内置布局类（如 {.column-margin}），或引入 Bootstrap Grid（通过 format: html: default: true 启用）；
- 安全性提醒：Quarto 默认对用户 HTML 进行基本转义防护；如需执行内联脚本（如 onclick），无需额外配置，但避免动态拼接不可信内容。
? 最佳实践建议：对于复杂布局，优先使用 Quarto 原生语法（如 ::: {.columns} + ::: {.column}）实现语义化分栏；仅当原生能力不足时，再嵌入定制 HTML——既保障可维护性，又利于未来升级兼容性。
