Quarto 入门

Quarto 快速简单上手

如何在VS Code中快速开始第一个Quarto文件，执行渲染得到想要的结果

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 格式之间的相互转换。官方称之为该领域中的“瑞士军刀”

{.lightbox fig-alt=“qmd-how-it-works” fig-align=“center”

2. qmd使用内容

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等，并且可以执行代码并显示输出结果

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. qmd中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
---

渲染文档,每个单元格的输出上方都会显示一个“代码”控件