Quarto 入门

Quarto 快速简单上手

如何在VS Code中快速开始第一个Quarto文件，并执行渲染得到想要的html,pdf等文档

Quarto 本质上是： Quarto = Markdown + Pandoc + 代码执行引擎 + 发布系统”

1. 概览

在这篇教程中，将展示如何使用VS Code联合Quarto构建你的第一个Quarto项目。在使用之前，必须安装Quarto扩展插件

  • 一键渲染与预览: 插件提供了集成的渲染和预览功能，让你能在 VS Code 里直接看到生成的 HTML 或 PDF 效果，通常是左右分屏，左边写代码，右边看结果，实时同步

  • 智能语法高亮: 它不仅能识别 Markdown 语法，还能识别嵌入在文档里的编程语言（比如 Python、R 或 Julia）

  • YAML 配置辅助: Quarto 文档顶部的 YAML 区域（用来设置标题、格式等元数据）往往有很多复杂的选项。插件提供了自动补全和诊断功能。当你输入配置项时，它会提示你有哪些选项可用，如果你写错了，它还会像检查拼写错误一样标红提醒你。

  • 代码自动补全: 在写代码块时，插件会提供针对嵌入语言的智能提示

1.1 基础流程

  1. Quarto 中的qmd文件，包含着markdown和可执行的code cell

这里展示了一个创建的qmd文件，在文件夹中创建后缀为qmd文件即可进行编写

qmd file

  1. 预览，将qmd文件按照自己设定的格式(web,pdf,doc等)进行预览

  • 在VS Code中，点击右上角的渲染按钮，选择预览 vscode-preview-button

  • 使用 启动命令面板，然后输入> quarto preview

注记

每次修改之后都可以进行预览，直到达到想要的效果

  1. 渲染，将qmd文件按照自己设定的格式(web,pdf,doc等)进行渲染，得到最终的成品，而不是预览
  • 使用 启动命令面板，然后输入> quarto render
  • 在终端中使用命令行进行操作，quarto render即可

1.2 工作原理

当使用Quarto渲染.qmd文件的时候，如果有代码块(R，python等)，会先执行Jupyter/Kniter，结果组合code，markdown，output等，最后markdown使用Pandoc形成最终的文件

提示

Pandoc 是一个由 John MacFarlane 开发的通用文档转换工具，可以支持大量标记语言之间的格式转换，例如 Markdown 、Microsoft Word、PowerPoint、 JupyterNotebook、HTML、PDF、LaTeX、Wiki、EPUB 格式之间的相互转换。官方称之为该领域中的“瑞士军刀”

qmd-how-it-works

2. Quarto基础包含内容

qmd文件中可以包含多种内容，包括markdown，R，python，YAML Options等，就像是组合起来的多种语言

2.1 YAML Options

YAML Options 是在.qmd文件顶部，用于设置文档的元数据，比如标题、作者、日期、格式等

title: "Quarto 入门"
lang: zh
subtitle: Quarto 快速简单上手
description: 如何在VS Code中快速开始第一个Quarto文件，执行渲染得到想要的结果

可设置的参数非常多，主要是控制展示的标题，作者，格式，其它还有控制code的展示等，后续再展开介绍

2.2 Markdown

Markdown是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML（或者HTML）文档。Markdown的目标是实现“易读易写”。

## Polar Axis

For a demonstration of a line plot on a polar axis, see @fig-polar.

通配各种markdown基础语法

2.3 Code Cell

在Quarto中，代码块可以嵌入在Markdown文档中，并使用特定的语法进行标记。代码块可以包含多种编程语言，如R、Python、Julia等，并且可以执行代码并显示输出结果

Code Cell中开头也相当于YAML，用来进行当前模块的设置

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
  subplot_kw = {'projection': 'polar'} 
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
图 1

代码块使用{}进行标记，其中{python}表示代码块的语言，label表示代码块的标签，fig-cap表示代码块的标题，fig表示代码块的图片展示

在qmd文档中，也可以单独的Run Cell

2.4 预览设置

每个Tools中都可以进行预览设置，用来设定预览的时候是单独形成窗口还是在右侧进行预览

quarto-setting

3. Quarto中Code运算使用

Quarto 提供了大量选项来控制代码和计算输出在文档中

  • 你可以单独允许代码块 得到结果
  • preview预览模式可以实时计算
  • render渲染，在命令行中也可以选择不去运行，仅仅显示quarto render --no-execute
## Matplotlib
import matplotlib.pyplot as plt
import numpy as np

a = np.arange(15).reshape(3, 5)
a

fig = plt.figure()
x = np.arange(10)
y = 2.5 * np.sin(x / 20 * np.pi)
yerr = np.linspace(0.05, 0.2, 10)

plt.errorbar(x, y + 3, yerr=yerr, label='both limits (default)')
plt.errorbar(x, y + 2, yerr=yerr, uplims=True, label='uplims=True')
plt.errorbar(x, y + 1, yerr=yerr, uplims=True, lolims=True,
             label='uplims=True, lolims=True')

upperlimits = [True, False] * 5
lowerlimits = [False, True] * 5
plt.errorbar(x, y, yerr=yerr, uplims=upperlimits, lolims=lowerlimits,
             label='subsets of uplims and lolims')

plt.legend(loc='lower right')
plt.show(fig)

3.1 Cell 运行

在编写文档时，你可能希望执行一个或多个单元格，而无需重新渲染整个文档。你可以通过点击代码单元格上方的 “Run Cell”（运行单元格）按钮来实现。点击该按钮即可执行单元格（输出结果将并排显示在 Jupyter 交互式控制台中

注记

所有的代码底层都是需要编译器运行的，python也好，R也好，都需要相应的包来处理代码，quarto本身只是起到调用的作用

cell-run

如果一篇qmd中有多个code模块，你可以选择运行

  • 运行当前单元格
  • 运行当前单元格和下面的单元格
  • 运行当前单元格和上面的单元格
  • 运行所有单元格

3.2 Cell 展示输出

Cell代码是可选择是否展示在文档中的

源文件中的所有代码默认都会显示在渲染后的文档中。不过，在某些情况下，你可能希望隐藏所有代码，只显示输出结果。让我们直接在文档的执行选项（execute options）中指定 echo: false，以阻止代码被打印出来

---
title: "我的分析报告"
execute:
  echo: false  # 加上这一行，生成的文档里就会隐藏代码，只显示结果
jupyter: python3
---

介绍除了控制代码显示之外，还有更多高级选项可以控制单元格的输出内容，特别是如何处理警告和错误信息

  • warning：用于显示或隐藏警告信息（这对于屏蔽加载软件包时的提示信息特别有用）
  • include：作为一个通用的总开关，用于阻止任何输出（无论是代码还是结果）被包含在最终文档中
  • error：用于防止代码执行中的错误导致文档渲染中断（并会将错误信息打印在渲染后文档中）

3.3 Code 代码块折叠

与其完全隐藏代码，您可能更希望将其折叠起来，让读者自行决定是否查看。您可以使用代码折叠选项来实现这一点。移除我们之前添加的 echo 选项，并添加代码折叠 HTML 格式选项

  1. 可以在yaml中进行全文的代码设置
---
title: Quarto Computations
format:
  html:
    code-fold: true
jupyter: python3
---

渲染文档,每个单元格的输出上方都会显示一个“代码”控件，可以对代码折叠进行全局控制。尝试在 HTML 格式选项中添加 code-tools: true

3.4 Code Figure

Figure一般分为两种

  • Code运算得到的Figure
  • 本身插入的图片

Quarto本身有很强的R背景，所以非常利于代码的运算输出得到图片，从而进行各种图片的设置

Quarto也有多张图片排版的设置，满足美观和布局的需求，提供了各种参数在Code block中设置,后面Figure也有详细的介绍

  • layout-ncol: 2:表示布局按列，2列排版
  • column: page:控制图片在页面上的显示范围，这个涉及到页面布局
  • 还有图片的标题和每个图片的标题

4. 渲染输出设置

这部分简单介绍如何以多种格式渲染文档，并展示如何添加目录、公式、引文、交叉引用等组件。

4.1 渲染输出格式

Quarto 支持将笔记本渲染成数十种不同的输出格式。默认情况下使用 HTML 格式，但可以在文档选项中指定其他格式。

分类 格式/系统 说明 典型用途
文档（Documents） HTML 网页标准格式 博客、在线报告
PDF 排版严谨的文档 论文、正式报告
Word（.docx） 办公文档格式 汇报材料、修改稿
ODT / ePub 开放文档 / 电子书 电子书、跨平台阅读
演示（Presentations） Reveal.js HTML 幻灯片框架 技术分享
PowerPoint 微软 PPT 商务汇报
Beamer LaTeX 幻灯片 学术报告
Markdown 生态 GitHub Flavored Markdown GitHub 使用的 Markdown README / 文档
CommonMark 标准 Markdown 规范 跨平台兼容
Hugo / Docusaurus 静态网站系统 技术博客 / 文档站
Wiki 系统 MediaWiki 维基百科格式 知识库
Jira Wiki 项目管理文档 团队协作
DokuWiki / XWiki 企业 Wiki 内部文档
计算与笔记 Jupyter Notebook 代码+文档一体 数据分析
出版/结构化 JATS / DocBook XML 标准 学术出版
LaTeX / ConTeXt 排版系统 高质量论文
其他格式 RTF / reST / AsciiDoc 各类文本系统 兼容 legacy 系统

在Quarto中可以在YAML中通过format进行设置，也可以同时输出多个格式

---
title: "Quarto Document"
author: "Norah Jones"
toc: true
number-sections: true
syntax-highlighting: pygments
format: 
  pdf: 
    geometry: 
      - top=30mm
      - left=20mm
  html: 
    code-fold: true
    html-math-method: katex
  docx: default
---
提示

生成PDF文件需要安装LaTeX，LaTex比较大但是比较全，LaTex具体安装使用请看另外文档Latex安装语法

Quarto也提供了一个缩小版的tex安装

quarto install tinytex

中文需要特殊的宏包来加载！不然会是乱码

  • toc:是否形成目录
  • syntax-highlighting: 语法高亮的模式

4.2 渲染

Quarto可以使用命令指定渲染格式，可以render单个文件，也可以render整个文件夹

quarto render authoring.qmd

# 多文件输出
quarto render authoring.qmd --to docx
quarto render authoring.qmd --to docx,pdf

# 指定输出
quarto render authoring.qmd --to odt

4.3 数学公式

Quarto支持LaTex语法，可以方便的插入数学公式

Einstein's theory of special relatively that expresses the equivalence of mass and energy:

$E = mc^{2}$
  • 支持LaTex语法
  • 可以使用$$表示块数学式
  • 可以使用$表示行内数学式

4.4 引用外部文献

要在 Quarto 文档中引用其他作品，首先要创建一个受支持格式（BibTeX 或 CSL）的参考文献文件。然后，使用参考文献 YAML 元数据选项将参考文献链接到您的文档

一般情况下，卸载YAMl中后，会自动创建.bib

---
title: Quarto Basics
format: html
bibliography: references.bib
---

## Overview

Knuth says always be literate [@knuth1984].

## References

@ 引用语法非常灵活，支持前缀、后缀、定位符和文内引用,后续在引用中了解高级用法

4.5 交叉引用

交叉引用通过提供编号引用和指向图表、表格、公式和章节的超链接，使读者能够更轻松地浏览文档。可交叉引用的实体通常需要一个标签（唯一标识符）和一个标题。

交叉引用是引用的拓展用法，更像是文章内的超链接，可以方便的跳转到指定位置

类型 引用方式 定义方式 示例 说明
Section（章节） @sec-plot 在标题后添加 ID # Plot {#sec-plot} 用于引用章节
Figure（图） @fig-simple 在代码块 YAML 中定义 # | label: fig-simple
# | fig-cap: "Simple Plot"		 用于引用图
Equation（公式） @eq-stddev 在公式末尾添加 ID $$ {#eq-stddev} 用于引用数学公式

4.6 标注

标注是一种极好的方式，可以特别强调某些概念，或者更清楚地表明某些内容是补充性的，或者只适用于某些情况。

标注框是带有特殊标注属性的 Markdown div 元素, 要在 Markdown 单元格中创建标注框，请在文档中输入以下内容。

::: {.callout-note}
Note that there are five types of callouts, including:
`note`, `tip`, `warning`, `caution`, and `important`.
:::

语言设置为中文后，标注也会切换为中文

后续还有页面布局，Tables,Diagrams, Shortcodes等自定义的设置