Quarto 基础

1 许可

Quarto 是一个完全免费且开源的排版与数据科学出版系统， 核心工具 Quarto CLI 采用 MIT许可， 政策非常宽松，核心逻辑可以总结为 ：工具开源，内容归你

2 开始 Quarto

使用 Quarto 需要安装两个软件

  1. 安装支持的开发平台，推荐使用官方的 RStudio

  2. 安装 Quarto， 通常 RStudio 会自带

3 Hello Quarto

Quarto 和 RStudio 都是 Posit 公司推出的产品

3.1 概述

下图左侧是一个扩展名为 .qmd 的 Quarto 文档， 右侧是它在 RStudio 中被渲染成 HTML 后的效果 ：

按照下面步骤安装 RStudio 并打开范例 hello.qmd 完成第一个任务 ：

  1. 下载最新的 RStudio 并进行安装

  2. 在 console 中输入命令安装 tidyverse 和 palmerpenguins

    install.packages(“tidyverse”)

    install.packages(“palmerpenguins”)

  3. 下载入门文件 hello.qmd 双击打开

3.2 渲染

在 RStudio 中点击 Render 按钮， 对文档进行渲染 ：

3.3 文档编写

RStudio 提供 Visual可视化编辑器。一份完整 Quarto 文档由三部分组成：YAML头、Chunks代码块、Markdown文本 ：

3.3.1 YAML 头

YAML 头 在文档开头使用前后三条短横线 --- 包裹 ：

3.3.2 chunks 代码块

下面是绘制正弦函数的代码块 ：

代码块还可以单独在 RStudio 中运行 ：

3.3.3 Markdown文本

RStudio 提供可视化 Markdown 编辑器，入门阶段不用记忆太多语法

3.4 底层运行原理

当你点击 Render 按钮的时候， RStudio 自动按照下面流程执行 ：

4 代码计算

Quarto 里面包含 代码块 并且每次渲染的时候这些代码会被相同的执行， 由此可以创建 完全可复现 的文档

4.1 输出控制

默认情况下渲染后的文档会同时展示代码和代码运行结果 ：

可以在 YAML头 中直接要求所有的代码块都不输出源码 ：

如果你开启了Render on Save ，保存 .qmd 文档时会自动执行渲染 ：

还可以设置保留 代码块标记符 一起输出 ：

完整参数 ： Knitr Cell Options

4.2 代码折叠

不想彻底隐藏代码时，可以开启 代码折叠 ：

还可以对整个页面的代码折叠统一控制 ：

4.3 图表

可以通过代码块参数优化图表外观、提升可读性与无障碍访问 ：

正文还可以交叉引用图表 ：

4.4 多图表

下面并列显示多个图表 ：

  1. 将两个图表并排显示，每个子图都有标题， 总图也有标题

  2. 图表宽度超过正常文本很大范围

  3. 子图、总图都进行了交叉引用

上面是利用 layout-ncol 选项来控制图表两列并排显示的， 更多布局请参考 Figure Layout 多图表的布局控制。 上面是利用 column 让图表横跨整个页面， 更多布局请参考 网页布局

4.5 数据框

可以使用 df-print 文档选项来控制数据框的默认打印输出形式。可用的选项包括 ：

选项 说明
default 使用数据框默认的 S3 方法
kable 使用 knitr::kable() 函数生成的 Markdown 表格
tibble 使用 tibble 包生成的纯文本表格
paged HTML 表格，支持行和列溢出时的分页功能（使用 rmarkmarkdown::paged_table() 实现）

下面是使用 paged 时的效果， 表格被分页显示 ：

4.6 行内代码

下面是行内代码的一个最简单范例 ，更详细的语法参考 inline Code 专题 ：

如果嵌入行内的表达式过于复杂， 建议像下面这样处理 ：

4.7 缓存

当开启了 Render on Save 以后， 每次保存就重新渲染一次， 有些计算量比较大的可以缓存起来， 不要每次都重新渲染浪费时间。更深入的缓存主题 参考 ：

5 排版

下面简单介绍在 RStudio 中使用 Visual模式 编辑 .qmd 文件。 主要内容包括 ：

  1. 同一个源码， 渲染成多种输出格式

  2. 添加章节

  3. 编写公式

  4. 添加交叉引用

  5. 提示框 Callout

  6. 文档布局的简介

5.1 输出格式

Quarto 支持将 .qmd 文件渲染为多种输出格式， 默认的输出格式是 HTML

5.1.1 格式选择

下面使用 RStudio 创建一个 Quarto 文档， 并选择 html 的输出格式 ：

文档输出的是 pdf 需要输入命令安装 TinyTeX 引擎（不支持中文）， 更多关于 pdf 渲染问题可以参考 PDF Engines ：

下面在 YAML 设置 代码添加行号 ：

5.1.2 多种格式输出

下面范例在一个 .qmd文档 中，进行三种格式 HTML、pdf、docx 的输出，并为每种格式做出了很多不同的设置 ：

注意 ：

  1. 为了在浏览器中查看 .docx 文档， 需要安装谷歌的插件 Office Editing for Docs, Sheets & Slides
  2. 每次点击 Render 只能从下拉箭头里面选择输出其中一种， 下面有详细的介绍

5.2 多目标渲染

点击 Render 按钮， 渲染的是文档中第一个输出设置 ：

如果需要一次构建多种输出， 需要安装包 install.packages("quarto") ：

5.3 章节

下面是使用 目录 和 章节编号 ：

5.4 公式

在 Visual 模式下使用 Insert Anything tool 向 Quarto 中插入公式 ：

公式分为 行内公式 和 行间公式 ：

输入 LaTeX 公式以后就被实时渲染出来， 更多公式请参阅 markdown equations ：

5.5 参考文献

可以使用 Insert Anything tool 插入参考文献 ：

可以直接在 from DOI 中搜索 10.1093/comjnl/27.2.97 得到一个引用 ：

输出的 HTML 会把参考文献放在最后 ：

还可以自己去控制 Reference 的标题 ：

还可以自己修改 References 的标题，设置为不编号 .unnumbered ：

参考文献 @ 的语法非常灵活， 支持前缀、后缀、定位符、正文引用， 详细参考 Citations

5.6 交叉引用

图表、数据框、公式、章节都可以编号， 设置交叉引用可以提高阅读速度。 需要设置这些功能块的 label 和 caption 选项， 其中 label 起到唯一标识符的作用。下面给公式设置一个链接 ：

qmd为公式设置交叉引用

链接到上面设置的公式 #eq-slor ：

qmd交叉引用到一个公式

下面是设置好交叉引用以后的页面效果 ：

更多交叉引用的语法和内容， 可以参考 Cross References

5.7 提示框 Callout

提示框用吸引力比较强的框包裹着一段文字，它是特殊的 div 标签。更多效果可以参考 Callouts ：

qmd插入callout提示框

5.8 文档布局

Quarto 文档的正文默认宽度大约 700 像素， 这个宽度是为了优化可读性， 正文区域两侧还会留有 边距区域（margin）。 Quarto 提供了几种方式，可以充分利用这些额外空间 ：

还可以将参考文献、 脚注、 旁注 放置在边距区域。还可以为图表、表格 或其他内容定义自定义的列跨度。要了解更多细节，请参阅 网页布局

6 延申学习

下面是一些扩展内容， 这部分大部分要整合到 html 中 ：

  • 网站 Websites ： 将一系列文档集合发布为一个网站。网站支持多种导航形式以及全文检索
  • 博客 Blogs ： 创建一个带有 “关于” 页面、灵活的文章列表、文章分类、RSS 订阅源以及拥有 20 多套主题的博客
  • 书籍 Books ： 创建印刷格式（PDF、MS Word）和在线格式（HTML、ePub）的书籍和手稿
  • 交互性 Interactivity ： 引入交互式组件，这部分到 quarto2.0 之后才能实用，帮助读者更深层次地探索你所展示的概念和数据
  • 给大语言模型 LLMs ： 生成必要的文档给大语言模型

7 链接