本文详解如何在 quarto 文档中安全、有效地嵌入原生 html 代码，以实现如 gif 背景左栏 + 文本按钮右栏的自定义布局，并指出常见配置错误（如重复 yaml 区块）及正确用法。
本文详解如何在 quarto 文档中安全、有效地嵌入原生 html 代码，以实现如 gif 背景左栏 + 文本按钮右栏的自定义布局，并指出常见配置错误（如重复 yaml 区块）及正确用法。
Quarto 原生支持 HTML 内容嵌入，但需遵循其文档结构规范：YAML 元数据区块必须唯一且位于文件开头，不可拆分或重复出现。你原始代码中将 format: html 单独置于第二个 --- 区块，导致 Quarto 解析失败（YAML 解析中断，后续 HTML 被当作普通文本渲染，而非 DOM 结构）。
✅ 正确写法是将所有元数据整合到一个 YAML 头部中，并确保 HTML 结构直接置于其后（无需额外 或
标签包裹——Quarto 会自动注入完整 HTML 模板，你只需提供 内的有效内容）：---
title: ""
format: html
---
<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/skill5806" title="html-deploy"><img
src="https://img.php.cn/upload/skill/000/000/081/179066538882434.jpg" alt="html-deploy" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a rel="nofollow" href="/xiazai/skill5806" title="html-deploy" class="overflowclass">html-deploy</a>
<p class="overflowclass">使用 htmlcode.fun 将 HTML 内容或文件部署到网页，适用于用户要求“部署到网页”“托管此 HTML”“生成此前端...的实时链接”等场景。</p>
</div>
<a rel="nofollow" href="/xiazai/skill5806" title="html-deploy" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
</a>
</div>
</div>
<button onclick="window.location.href='#'">Przycisk</button>
</div>
? 关键注意事项：
- ✅ gif_example.gif 需存放于项目根目录或 resources/ 子目录中（推荐放入 resources/ 并使用 url('resources/gif_example.gif') 提升可移植性）；
- ✅ 标签虽非必需（Quarto 允许直接写 ），但显式声明有助于语义清晰和样式控制；
- ⚠️ 避免在 Quarto 文档中手动添加 、 或重复 —— 这会导致嵌套冲突或渲染异常；
- ? 如需为按钮添加真实跳转，将 onclick 替换为 onclick="window.location.href='https://example.com'"，或更推荐使用标准 标签配合 CSS 按钮样式以保障可访问性。
最终生成的页面将严格按 Flex 布局等分视口，左侧满屏 GIF 背景（居中覆盖），右侧垂直水平居中文本与按钮，适配桌面端主流分辨率。此方案兼顾简洁性与可控性，是 Quarto 中实现定制化 UI 的标准实践。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
