本文介绍如何绕过 quarto 默认布局限制，通过自定义 css grid 实现跨设备一致的 20%（侧边栏 toc）–60%（主内容）–20%（右侧留白）html 页面布局，兼容 quarto 1.4+，无需修改核心模板即可生效。
本文介绍如何绕过 quarto 默认布局限制，通过自定义 css grid 实现跨设备一致的 20%（侧边栏 toc）–60%（主内容）–20%（右侧留白）html 页面布局，兼容 quarto 1.4+，无需修改核心模板即可生效。
Quarto 默认的 HTML 输出采用响应式栅格系统（如 column-page 或 sidebar），但其内置 grid 配置（如 sidebar-width: 20%）常因预设像素值（如 max-width、margin）与百分比冲突而失效，导致在宽屏下左右额外留白、TOC 消失或内容偏移。要真正实现严格按视口比例划分的三区布局（20% TOC + 60% 内容 + 20% 右侧空白），推荐采用「CSS Grid + 视口单位」的轻量级覆盖方案——不依赖 Quarto 的栅格配置，而是直接控制 级别布局。
✅ 推荐实现方式（纯 CSS + HTML 结构微调）
将页面结构简化为两个语义化区块：<aside></aside> 承载目录（TOC），<main></main> 承载正文，并通过 vw（viewport width）单位确保比例严格守恒：
/* _styles.css 或在 _quarto.yml 的 css 字段中引用 */
* {
box-sizing: border-box;
}
body {
margin: 0 20vw 0 0; /* 右侧预留 20vw 空白 */
display: grid;
grid-template-columns: 20vw 60vw; /* 左侧 TOC 20%，主内容 60% */
min-height: 100vh;
}
aside {
grid-column: 1;
width: 20vw;
padding: 1.5rem 1rem;
position: sticky;
top: 1rem;
height: fit-content;
/* 可选：添加背景/边框增强视觉区分 */
background: #f8f9fa;
border-right: 1px solid #e9ecef;
}
main {
grid-column: 2;
width: 60vw;
padding: 0 1.5rem;
}? 关键点说明：
DeepBI DHTML 页面生成器下载生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
- 使用
20vw和60vw直接锚定视口宽度，彻底规避px与%混用导致的计算偏差；body { margin: 0 20vw 0 0 }将右侧 20vw 设为“不可见外边距”，等效于固定右空；position: sticky保证 TOC 在滚动时始终可见，height: fit-content防止高度塌陷；- 不需修改 Quarto 的
_quarto.yml中format: html: grid:设置，避免配置冲突。
? 在 Quarto 项目中启用
- 创建
styles.css文件（如./styles.css），粘贴上述 CSS； - 在
_quarto.yml中声明样式文件：format: html: css: [styles.css] -
强制渲染 TOC 到
<aside></aside>：在文档 YAML 头部启用并指定位置：format: html: toc: true toc-location: left # 或使用 toc-before = "section-title" 等⚠️ 注意：Quarto 默认 TOC 插入在
<nav class="toc"></nav>中，若需完全托管到<aside></aside>，建议配合include-after-body注入（进阶场景），但对多数用户，上述 CSS 已能正确包裹并定位默认生成的 TOC 元素。立即学习“前端免费学习笔记（深入）”；
✅ 效果验证与注意事项
- ✅ 全尺寸适配：从手机（
20vw ≈ 390px × 0.2 ≈ 78px）到 4K 屏（3840px × 0.2 = 768px）均保持精确比例； - ❌ 避免使用
grid-template-columns: 1fr 3fr：原文示例中的1fr 3fr实际分配为 25%/75%，无法达成 20%/60% 要求（1fr : 3fr = 1:3 → 25%:75%），务必改用20vw 60vw； - ? TOC 安全性：若发现 TOC 文字被截断，可在
aside中追加overflow-y: auto; max-height: 80vh;； - ? 无障碍友好：保留
<aside></aside>与<main></main>语义标签，屏幕阅读器可正确识别导航与主体区域。
该方案以最小侵入性解决 Quarto 布局灵活性瓶颈，兼顾专业排版需求与开发效率，是构建学术报告、技术文档或多屏协作界面的理想基础布局。
