本文介绍如何绕过 quarto 默认布局限制，通过自定义 css grid 实现跨设备一致的 20%（侧边栏 toc）–60%（主内容）–20%（右侧留白）html 页面布局，兼容 quarto 1.4+，无需修改核心模板即可生效。
本文介绍如何绕过 quarto 默认布局限制，通过自定义 css grid 实现跨设备一致的 20%（侧边栏 toc）–60%（主内容）–20%（右侧留白）html 页面布局，兼容 quarto 1.4+，无需修改核心模板即可生效。
Quarto 默认的 HTML 输出采用响应式栅格系统（如 将页面结构简化为两个语义化区块： ? 关键点说明： ⚠️ 注意：Quarto 默认 TOC 插入在 生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力：
- 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面；
- 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”；
- 提及位于 `apps/console/src/featur 该方案以最小侵入性解决 Quarto 布局灵活性瓶颈，兼顾专业排版需求与开发效率，是构建学术报告、技术文档或多屏协作界面的理想基础布局。column-page 或 sidebar），但其内置 grid 配置（如 sidebar-width: 20%）常因预设像素值（如 max-width、margin）与百分比冲突而失效，导致在宽屏下左右额外留白、TOC 消失或内容偏移。要真正实现严格按视口比例划分的三区布局（20% TOC + 60% 内容 + 20% 右侧空白），推荐采用「CSS Grid + 视口单位」的轻量级覆盖方案——不依赖 Quarto 的栅格配置，而是直接控制 级别布局。✅ 推荐实现方式（纯 CSS + HTML 结构微调）
承载目录（TOC）， 承载正文，并通过 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;
}
20vw 和 60vw 直接锚定视口宽度，彻底规避 px 与 % 混用导致的计算偏差； body { margin: 0 20vw 0 0 } 将右侧 20vw 设为“不可见外边距”，等效于固定右空； position: sticky 保证 TOC 在滚动时始终可见，height: fit-content 防止高度塌陷； _quarto.yml 中 format: html: grid: 设置，避免配置冲突。? 在 Quarto 项目中启用
styles.css 文件（如 ./styles.css），粘贴上述 CSS； _quarto.yml 中声明样式文件：format:
html:
css: [styles.css]
：在文档 YAML 头部启用并指定位置：format:
html:
toc: true
toc-location: left # 或使用 toc-before = "section-title" 等
中，若需完全托管到 ，建议配合 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； aside 中追加 overflow-y: auto; max-height: 80vh;； 与 语义标签，屏幕阅读器可正确识别导航与主体区域。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
