如何在 Quarto 内嵌入自定义 HTML 实现双栏布局

作者：袖梨 2026-07-01

本文详解如何在 quarto 文档中正确嵌入原生 html 代码，实现响应式双栏页面布局（左侧 gif 背景、右侧居中文本与按钮），并规避常见 yaml 配置错误与结构陷阱。

本文详解如何在 quarto 文档中正确嵌入原生 html 代码，实现响应式双栏页面布局（左侧 gif 背景、右侧居中文本与按钮），并规避常见 yaml 配置错误与结构陷阱。

Quarto 原生支持 HTML 内容嵌入，但需严格遵循其文档结构规范：YAML 元数据块必须唯一且位于文档最开头，不可拆分或重复；所有自定义 HTML 应置于 YAML 结束之后的正文区域，而非包裹在 <body> 标签内（Quarto 会自动构建完整 HTML 文档结构，手动添加 <body> 反而会导致嵌套冲突或渲染异常）。

✅ 正确写法如下（保存为 index.qmd）：

---title: ""format: 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>    <a href="https://example.com" style="margin-top: 1rem; padding: 0.75rem 1.5rem; background: #007acc; color: white; border: none; border-radius: 4px; text-decoration: none; font-weight: bold;">      Przycisk    </a>  </div></div>

⚠️ 关键注意事项：

移除手动 <body> 标签：Quarto 输出的 HTML 已包含标准 <body>，额外嵌套会导致浏览器解析异常（如布局失效、样式丢失）；
确保 GIF 路径正确：gif_example.gif 需置于项目根目录或 ./images/ 等 Quarto 默认资源路径下，推荐使用相对路径；
按钮建议用 <a> 替代 <button>：若需跳转链接，<a> 语义更清晰、兼容性更好；如需 JavaScript 交互，可保留 <button> 并配合 onclick 属性；
添加 width: 100vw 和 padding：增强跨设备适配性，并避免文字紧贴边缘；
避免重复 YAML 块：原示例中两个 --- 分隔的 YAML 块（title 和 format）会被 Quarto 视为语法错误，必须合并为单个元数据块。

最终效果为全屏横向分割的两栏布局：左侧铺满 GIF 动画背景，右侧垂直水平居中文本与可点击链接按钮。该方案轻量、无需额外 CSS 文件，适用于快速原型或定制首页场景。

立即学习“前端免费学习笔记（深入）”；