29 Quarto formats

29.1 Introduction

So far, you’ve seen Quarto used to produce HTML documents.
到目前为止，你已经看到了如何使用 Quarto 来生成 HTML 文档。

This chapter gives a brief overview of some of the many other types of output you can produce with Quarto.
本章将简要概述你可以使用 Quarto 制作的许多其他类型的输出。

There are two ways to set the output of a document:
有两种方法可以设置文档的输出：

Permanently, by modifying the YAML header:
永久性地，通过修改 YAML 标题：

yaml title: "Diamond sizes" format: html
Transiently, by calling quarto::quarto_render() by hand:
临时性地，通过手动调用 quarto::quarto_render()：

{r} #| eval: false quarto::quarto_render("diamond-sizes.qmd", output_format = "docx")

This is useful if you want to programmatically produce multiple types of output since the output_format argument can also take a list of values.
如果你想以编程方式生成多种类型的输出，这会很有用，因为 output_format 参数也可以接受一个值列表。

{r} #| eval: false quarto::quarto_render("diamond-sizes.qmd", output_format = c("docx", "pdf"))

29.2 Output options

Quarto offers a wide range of output formats.
Quarto 提供了多种输出格式。

You can find the complete list at https://quarto.org/docs/output-formats/all-formats.html.
你可以在 https://quarto.org/docs/output-formats/all-formats.html 查看完整列表。

Many formats share some output options (e.g., toc: true for including a table of contents), but others have options that are format specific (e.g., code-fold: true collapses code chunks into a <details> tag for HTML output so the user can display it on demand, it’s not applicable in a PDF or Word document).
许多格式共享一些输出选项（例如，用于包含目录的 toc: true），但其他格式则有其特定的选项（例如，code-fold: true 会将代码块折叠成一个 HTML 输出的 <details> 标签，以便用户可以按需显示，这在 PDF 或 Word 文档中不适用）。

To override the default options, you need to use an expanded format field.
要覆盖默认选项，你需要使用一个扩展的 format 字段。

For example, if you wanted to render an html with a floating table of contents, you’d use:
例如，如果你想渲染一个带有浮动目录的 html，你可以这样写：

format:
  html:
    toc: true
    toc_float: true

You can even render to multiple outputs by supplying a list of formats:
你甚至可以通过提供一个格式列表来渲染成多种输出：

format:
  html:
    toc: true
    toc_float: true
  pdf: default
  docx: default

Note the special syntax (pdf: default) if you don’t want to override any default options.
注意，如果你不想覆盖任何默认选项，可以使用特殊语法 (pdf: default)。

To render to all formats specified in the YAML of a document, you can use output_format = "all".
要渲染到文档 YAML 中指定的所有格式，你可以使用 output_format = "all"。

quarto::quarto_render("diamond-sizes.qmd", output_format = "all")

29.3 Documents

The previous chapter focused on the default html output.
上一章重点介绍了默认的 html 输出。

There are several basic variations on that theme, generating different types of documents.
在这个主题上有几种基本的变化，可以生成不同类型的文档。

For example:
例如：

pdf makes a PDF with LaTeX (an open-source document layout system), which you’ll need to install. RStudio will prompt you if you don’t already have it.
pdf 使用 LaTeX（一个开源的文档排版系统）来创建 PDF，你需要安装它。如果你尚未安装，RStudio 会提示你。
docx for Microsoft Word (.docx) documents.
docx 用于生成 Microsoft Word (.docx) 文档。
odt for OpenDocument Text (.odt) documents.
odt 用于生成 OpenDocument 文本 (.odt) 文档。
rtf for Rich Text Format (.rtf) documents.
rtf 用于生成富文本格式 (.rtf) 文档。
gfm for a GitHub Flavored Markdown (.md) document.
gfm 用于生成 GitHub Flavored Markdown (.md) 文档。
ipynb for Jupyter Notebooks (.ipynb).
ipynb 用于生成 Jupyter Notebooks (.ipynb)。

Remember, when generating a document to share with decision-makers, you can turn off the default display of code by setting global options in the document YAML:
请记住，在生成与决策者共享的文档时，你可以通过在文档 YAML 中设置全局选项来关闭代码的默认显示：

execute:
  echo: false

For html documents another option is to make the code chunks hidden by default, but visible with a click:
对于 html 文档，另一个选择是让代码块默认隐藏，但可以通过点击来显示：

format:
  html:
    code: true

29.4 Presentations

You can also use Quarto to produce presentations.
你还可以使用 Quarto 来制作演示文稿。

You get less visual control than with a tool like Keynote or PowerPoint, but automatically inserting the results of your R code into a presentation can save a huge amount of time.
与 Keynote 或 PowerPoint 这样的工具相比，你的视觉控制力较弱，但将 R 代码的结果自动插入演示文稿可以节省大量时间。

Presentations work by dividing your content into slides, with a new slide beginning at each second (##) level header.
演示文稿的工作方式是将你的内容分成幻灯片，每一张新的幻灯片都以二级 (##) 标题开始。

Additionally, first (#) level headers indicate the beginning of a new section with a section title slide that is, by default, centered in the middle.
此外，一级 (#) 标题表示新章节的开始，其标题幻灯片默认居中。

Quarto supports a variety of presentation formats, including:
Quarto 支持多种演示文稿格式，包括：

revealjs - HTML presentation with revealjs
revealjs - 使用 revealjs 的 HTML 演示文稿
pptx - PowerPoint presentation
pptx - PowerPoint 演示文稿
beamer - PDF presentation with LaTeX Beamer.
beamer - 使用 LaTeX Beamer 的 PDF 演示文稿

You can read more about creating presentations with Quarto at https://quarto.org/docs/presentations.
你可以在 https://quarto.org/docs/presentations 阅读更多关于使用 Quarto 创建演示文稿的信息。

29.5 Interactivity

Just like any HTML document, HTML documents created with Quarto can contain interactive components as well.
就像任何 HTML 文档一样，使用 Quarto 创建的 HTML 文档也可以包含交互式组件。

Here we introduce two options for including interactivity in your Quarto documents: htmlwidgets and Shiny.
这里我们介绍在你的 Quarto 文档中加入交互性的两种选择：htmlwidgets 和 Shiny。

29.5.1 htmlwidgets

HTML is an interactive format, and you can take advantage of that interactivity with htmlwidgets, R functions that produce interactive HTML visualizations.
HTML 是一种交互式格式，你可以利用 htmlwidgets（生成交互式 HTML 可视化的 R 函数）来利用这种交互性。

For example, take the leaflet map below.
例如，看看下面的 leaflet 地图。

If you’re viewing this page on the web, you can drag the map around, zoom in and out, etc.
如果你正在网页上查看此页面，你可以拖动地图，放大和缩小等。

You obviously can’t do that in a book, so Quarto automatically inserts a static screenshot for you.
在书中你显然不能这样做，所以 Quarto 会自动为你插入一个静态截图。

library(leaflet)
leaflet() |>
  setView(174.764, -36.877, zoom = 16) |> 
  addTiles() |>
  addMarkers(174.764, -36.877, popup = "Maungawhau")

The great thing about htmlwidgets is that you don’t need to know anything about HTML or JavaScript to use them.
htmlwidgets 的优点在于，你无需了解任何 HTML 或 JavaScript 知识就可以使用它们。

All the details are wrapped inside the package, so you don’t need to worry about it.
所有的细节都被封装在包里，所以你不需要担心。

There are many packages that provide htmlwidgets, including:
有许多提供 htmlwidgets 的包，包括：

dygraphs for interactive time series visualizations.
dygraphs 用于交互式时间序列可视化。
DT for interactive tables.
DT 用于交互式表格。
threejs for interactive 3d plots.
threejs 用于交互式 3D 图。
DiagrammeR for diagrams (like flow charts and simple node-link diagrams).
DiagrammeR 用于图表（如流程图和简单的节点链接图）。

To learn more about htmlwidgets and see a complete list of packages that provide them visit https://www.htmlwidgets.org.
要了解更多关于 htmlwidgets 的信息并查看提供它们的包的完整列表，请访问 https://www.htmlwidgets.org。

29.5.2 Shiny

htmlwidgets provide client-side interactivity — all the interactivity happens in the browser, independently of R.
htmlwidgets 提供客户端 (client-side) 交互性——所有的交互都发生在浏览器中，与 R 无关。

On the one hand, that’s great because you can distribute the HTML file without any connection to R.
一方面，这很好，因为你可以分发 HTML 文件而无需任何与 R 的连接。

However, that fundamentally limits what you can do to things that have been implemented in HTML and JavaScript.
然而，这从根本上限制了你只能做那些已经在 HTML 和 JavaScript 中实现的事情。

An alternative approach is to use shiny, a package that allows you to create interactivity using R code, not JavaScript.
另一种方法是使用 shiny，这是一个允许你使用 R 代码而不是 JavaScript 来创建交互性的包。

To call Shiny code from a Quarto document, add server: shiny to the YAML header:
要从 Quarto 文档中调用 Shiny 代码，请在 YAML 头部添加 server: shiny：

title: "Shiny Web App"
format: html
server: shiny

Then you can use the “input” functions to add interactive components to the document:
然后你可以使用“输入”函数向文档添加交互式组件：

library(shiny)

textInput("name", "What is your name?")
numericInput("age", "How old are you?", NA, min = 0, max = 150)

Two input boxes on top of each other. Top one says, "What is your name?", the bottom, "How old are you?".

And you also need a code chunk with chunk option context: server which contains the code that needs to run in a Shiny server.
你还需要一个带有 context: server 块选项的代码块，其中包含需要在 Shiny 服务器中运行的代码。

You can then refer to the values with input$name and input$age, and the code that uses them will be automatically re-run whenever they change.
然后你可以用 input$name 和 input$age 来引用这些值，使用它们的代码会在它们改变时自动重新运行。

We can’t show you a live shiny app here because shiny interactions occur on the server-side.
我们无法在这里向你展示一个实时的 Shiny 应用，因为 Shiny 的交互发生在服务器端 (server-side)。

This means that you can write interactive apps without knowing JavaScript, but you need a server to run them on.
这意味着你可以编写交互式应用而无需了解 JavaScript，但你需要一个服务器来运行它们。

This introduces a logistical issue: Shiny apps need a Shiny server to be run online.
这就带来了一个后勤问题：Shiny 应用需要一个 Shiny 服务器才能在线运行。

When you run Shiny apps on your own computer, Shiny automatically sets up a Shiny server for you, but you need a public-facing Shiny server if you want to publish this sort of interactivity online.
当你在自己的计算机上运行 Shiny 应用时，Shiny 会自动为你设置一个 Shiny 服务器，但如果你想在线发布这种交互性，你需要一个面向公众的 Shiny 服务器。

That’s the fundamental trade-off of shiny: you can do anything in a shiny document that you can do in R, but it requires someone to be running R.
这是 Shiny 的根本权衡：你可以在 Shiny 文档中做任何你在 R 中能做的事情，但这需要有人在运行 R。

For learning more about Shiny, we recommend reading Mastering Shiny by Hadley Wickham, https://mastering-shiny.org.
要了解更多关于 Shiny 的信息，我们推荐阅读 Hadley Wickham 的《精通 Shiny》(Mastering Shiny)，网址：https://mastering-shiny.org。

29.6 Websites and books

With a bit of additional infrastructure, you can use Quarto to generate a complete website or book:
通过一些额外的基础设施，你可以使用 Quarto 生成一个完整的网站或书籍：

Put your .qmd files in a single directory. index.qmd will become the home page.
将你的 .qmd 文件放在一个单独的目录中。index.qmd 将成为主页。
Add a YAML file named _quarto.yml that provides the navigation for the site. In this file, set the project type to either book or website, e.g.:
添加一个名为 _quarto.yml 的 YAML 文件，为网站提供导航。在这个文件中，将 project 类型设置为 book 或 website，例如：

yaml project: type: book

For example, the following _quarto.yml file creates a website from three source files: index.qmd (the home page), viridis-colors.qmd, and terrain-colors.qmd.
例如，下面的 _quarto.yml 文件从三个源文件创建了一个网站：index.qmd（主页）、viridis-colors.qmd 和 terrain-colors.qmd。

project:
  type: website

website:
  title: "A website on color scales"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: viridis-colors.qmd
        text: Viridis colors
      - href: terrain-colors.qmd
        text: Terrain colors

The _quarto.yml file you need for a book is very similarly structured.
你为书籍所需的 _quarto.yml 文件结构非常相似。

The following example shows how you can create a book with four chapters that renders to three different outputs (html, pdf, and epub). Once again, the source files are .qmd files.
下面的例子展示了如何创建一本有四章的书，并渲染成三种不同的输出 (html、pdf 和 epub)。源文件同样是 .qmd 文件。

project:
  type: book

book:
  title: "A book on color scales"
  author: "Jane Coloriste"
  chapters:
    - index.qmd
    - intro.qmd
    - viridis-colors.qmd
    - terrain-colors.qmd

format:
  html:
    theme: cosmo
  pdf: default
  epub: default

We recommend that you use an RStudio project for your websites and books.
我们建议你为你的网站和书籍使用 RStudio 项目。

Based on the _quarto.yml file, RStudio will recognize the type of project you’re working on, and add a Build tab to the IDE that you can use to render and preview your websites and books.
根据 _quarto.yml 文件，RStudio 会识别你正在处理的项目类型，并在 IDE 中添加一个 Build 选项卡，你可以用它来渲染和预览你的网站和书籍。

Both websites and books can also be rendered using quarto::quarto_render().
网站和书籍也可以使用 quarto::quarto_render() 进行渲染。

Read more at https://quarto.org/docs/websites about Quarto websites and https://quarto.org/docs/books about books.
在 https://quarto.org/docs/websites 阅读更多关于 Quarto 网站的信息，在 https://quarto.org/docs/books 阅读更多关于书籍的信息。

29.7 Other formats

Quarto offers even more output formats:
Quarto 提供了更多的输出格式：

You can write journal articles using Quarto Journal Templates: https://quarto.org/docs/journals/templates.html.
你可以使用 Quarto 期刊模板撰写期刊文章：https://quarto.org/docs/journals/templates.html。
You can output Quarto documents to Jupyter Notebooks with format: ipynb: https://quarto.org/docs/reference/formats/ipynb.html.
你可以使用 format: ipynb 将 Quarto 文档输出到 Jupyter Notebooks：https://quarto.org/docs/reference/formats/ipynb.html。

See https://quarto.org/docs/output-formats/all-formats.html for a list of even more formats.
请参阅 https://quarto.org/docs/output-formats/all-formats.html 获取更多格式的列表。

29.8 Summary

In this chapter we presented you a variety of options for communicating your results with Quarto, from static and interactive documents to presentations to websites and books.
在本章中，我们向你介绍了使用 Quarto 交流成果的多种选择，从静态和交互式文档到演示文稿，再到网站和书籍。

To learn more about effective communication in these different formats, we recommend the following resources:
要了解更多关于在这些不同格式中进行有效沟通的知识，我们推荐以下资源：

To improve your presentation skills, try Presentation Patterns by Neal Ford, Matthew McCollough, and Nathaniel Schutta. It provides a set of effective patterns (both low- and high-level) that you can apply to improve your presentations.
为了提高你的演讲技巧，可以试试 Neal Ford、Matthew McCollough 和 Nathaniel Schutta 合著的 Presentation Patterns。它提供了一套行之有效的模式（包括低层次和高层次），你可以应用这些模式来改进你的演讲。
If you give academic talks, you might like the Leek group guide to giving talks.
如果你做学术报告，你可能会喜欢 Leek group guide to giving talks。
We haven’t taken it ourselves, but we’ve heard good things about Matt McGarrity’s online course on public speaking: https://www.coursera.org/learn/public-speaking.
我们自己没有上过，但我们听说过 Matt McGarrity 的在线公开演讲课程的好评：https://www.coursera.org/learn/public-speaking。
If you are creating many dashboards, make sure to read Stephen Few’s Information Dashboard Design: The Effective Visual Communication of Data. It will help you create dashboards that are truly useful, not just pretty to look at.
如果你正在创建许多仪表盘，请务必阅读 Stephen Few 的 Information Dashboard Design: The Effective Visual Communication of Data。它将帮助你创建真正有用而不仅仅是好看的仪表盘。
Effectively communicating your ideas often benefits from some knowledge of graphic design. Robin Williams’ The Non-Designer’s Design Book is a great place to start.
有效地传达你的想法通常会受益于一些图形设计知识。Robin Williams 的 The Non-Designer’s Design Book 是一个很好的起点。