本文详解如何在 quarto 文档中安全、有效地嵌入原生 html 代码，实现自定义页面结构（如左右等宽双栏布局），并指出常见配置错误（如重复 yaml 区块）及解决方案。
本文详解如何在 quarto 文档中安全、有效地嵌入原生 html 代码，实现自定义页面结构（如左右等宽双栏布局），并指出常见配置错误（如重复 yaml 区块）及解决方案。
Quarto 原生支持 HTML 嵌入，但需严格遵循其文档结构规范。你遇到的问题核心在于 YAML 元数据区块的误用：将 format: html 单独写在第二个 --- 区块中，会导致解析失败或渲染异常——Quarto 要求所有元数据必须集中声明于首个 YAML 区块内。
✅ 正确做法是：将标题、格式及其他元数据统一置于开头的单个 YAML 区块中，随后直接编写 HTML 结构（无需额外 或
标签包裹，Quarto 会自动注入到页面主体中）。以下为可直接运行的 index.qmd 示例：---
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; background: #fff;">
<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>
<button onclick="window.location.href='https://example.com'">Przycisk</button>
</div>
⚠️ 关键注意事项：
- GIF 路径需有效：确保 gif_example.gif 与 index.qmd 同目录，或使用相对路径（如 images/gif_example.gif）；建议将静态资源放入 ./images/ 文件夹并启用 Quarto 的静态资源管理。
- 避免重复 YAML 区块：多个 --- 分隔的 YAML 块会被视为不同文档片段，第二块 format: html 不生效且可能破坏解析。
- 交互增强：示例中为按钮添加了 onclick 属性实现跳转；也可改用标准 标签配合 CSS 样式替代
-
响应式补充（推荐）：若需适配移动设备，可在 HTML 外层添加 并配合 Quarto 的 CSS 扩展机制，或在 _quarto.yml 中引入自定义样式表。
最终生成的 HTML 页面将严格按 Flex 布局渲染：左侧全高 GIF 背景，右侧居中文本与按钮。此方法适用于需要精细控制结构的场景，同时完全兼容 Quarto 的渲染流程与 RStudio 预览功能。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
