本文详解如何在 quarto 文档中正确嵌入原生 html 代码，实现响应式双栏页面布局（左侧 gif 背景、右侧居中文本与按钮），并规避常见 yaml 配置错误与结构陷阱。
本文详解如何在 quarto 文档中正确嵌入原生 html 代码，实现响应式双栏页面布局（左侧 gif 背景、右侧居中文本与按钮），并规避常见 yaml 配置错误与结构陷阱。
Quarto 原生支持 HTML 内容嵌入，但需严格遵循其文档结构规范：YAML 元数据块必须唯一且位于文档最开头，不可拆分或重复；所有自定义 HTML 应置于 YAML 结束之后的正文区域，而非包裹在
标签内（Quarto 会自动构建完整 HTML 文档结构，手动添加 反而会导致嵌套冲突或渲染异常）。✅ 正确写法如下（保存为 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><div class="aritcle_card flexRow artxards">
<div class="artcardd flexRow">
<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill6712" title="Wechat HTML Publisher"><img
src="https://img.php.cn/upload/skill/000/000/081/179109368394970.jpg" alt="Wechat HTML Publisher" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a rel="nofollow" href="/xiazai/skill6712" title="Wechat HTML Publisher" class="overflowclass">Wechat HTML Publisher</a>
<p class="overflowclass">直接上传HTML富文本到微信公众号草稿箱。支持完整的HTML格式,无需Markdown转换。</p>
</div>
<a rel="nofollow" href="/xiazai/skill6712" title="Wechat HTML Publisher" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
</a>
</div>
</div>
<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>
⚠️ 关键注意事项：
- 移除手动 标签：Quarto 输出的 HTML 已包含标准 ，额外嵌套会导致浏览器解析异常（如布局失效、样式丢失）；
- 确保 GIF 路径正确：gif_example.gif 需置于项目根目录或 ./images/ 等 Quarto 默认资源路径下，推荐使用相对路径；
- 按钮建议用 替代 ：若需跳转链接， 语义更清晰、兼容性更好；如需 JavaScript 交互，可保留
- 添加 width: 100vw 和 padding：增强跨设备适配性，并避免文字紧贴边缘；
- 避免重复 YAML 块：原示例中两个 --- 分隔的 YAML 块（title 和 format）会被 Quarto 视为语法错误，必须合并为单个元数据块。
最终效果为全屏横向分割的两栏布局：左侧铺满 GIF 动画背景，右侧垂直水平居中文本与可点击链接按钮。该方案轻量、无需额外 CSS 文件，适用于快速原型或定制首页场景。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
