寫在前面
學(xué)習(xí)一個軟件最好的方法就是啃它的官方文檔。本著自己學(xué)習(xí)拂铡、分享他人的態(tài)度，分享官方文檔的中文教程葱绒。軟件可能隨時更新，建議配合官方文檔一起閱讀斗锭。
1.quarto 教程 1：Hello, Quarto
2.quarto 教程 2：Computations
::: block-1
目錄
- 1 概述
- 2 輸出格式
- 3 渲染
- 4 部分
- 5 方程
- 6 引文
- 7 交叉引用
- 8 標(biāo)注
- 9 文章布局
- 10 發(fā)布
- 11 了解更多
:::
官網(wǎng)教程：
https://quarto.org/docs/get-started/authoring/rstudio.html
1 概述
在本教程中地淀，我們將向您展示如何在 RStudio 中創(chuàng)作 Quarto 文檔。特別是岖是，我們將討論您可以使用相同源代碼生成的各種文檔格式帮毁，并向您展示如何添加目錄实苞、方程式、引文等組件烈疚。RStudio 中的可視化 Markdown 編輯器使許多此類任務(wù)變得更加容易我們將在本教程中重點介紹它的用途黔牵，但請注意，也可以在源代碼編輯器中完成這些任務(wù)爷肝。
如果您想在自己的環(huán)境中逐步進(jìn)行操作猾浦，請確保您已安裝最新版本的 RStudio (v2023.06)。
2 輸出格式
Quarto 支持將筆記本渲染為數(shù)十種不同的輸出格式灯抛。默認(rèn)情況下金赦，使用 html 格式，但您可以在文檔選項中指定替代格式（或多個格式）对嚼。
格式選項
您可以在創(chuàng)建新文檔時選擇要渲染 Quarto 文檔的格式夹抗。要創(chuàng)建新文檔，請轉(zhuǎn)到 File > New File > Quarto Document… 或者纵竖，使用命令選項板（可通過 Ctrl+Shift+P 訪問）漠烧，搜索 Create a new Quarto document 并按回車鍵。
在 Title 字段中靡砌，為文檔指定一個標(biāo)題（例如已脓，下面的屏幕截圖顯示 “Housing Prices”），并將您的姓名添加到 Author 字段中乏奥。接下來摆舟，您將為文檔選擇輸出格式。默認(rèn)情況下邓了，RStudio 建議使用 HTML 作為輸出恨诱，我們暫時保留該默認(rèn)值。
將使用以下 YAML 創(chuàng)建一個新文檔骗炉。
---
title: "Housing Prices"
author: "Mine ?etinkaya-Rundel"
---
請注意照宝，我們的格式選擇 (HTML) 甚至沒有反映在 YAML 中，因為它是 Quarto 文檔的默認(rèn)輸出格式句葵。但是厕鹃，您可以直接編輯 YAML 來更改輸出格式，例如轉(zhuǎn)換為 PDF (pdf) 或 MS Word (docx)乍丈。將 format: pdf 添加到文檔的 YAML 中剂碴，如下所示。
---
title: "Housing Prices"
author: "Mine ?etinkaya-Rundel"
format: pdf
---
不幸的是轻专，該文檔沒有內(nèi)容忆矛，因此渲染它不會產(chǎn)生非常有趣的輸出。為了更容易地演示我們想要在本教程中強(qiáng)調(diào)的所有功能，讓我們關(guān)閉這個空文檔并從其中包含一點內(nèi)容的文檔開始催训。如果您想在自己的環(huán)境中逐步進(jìn)行操作洽议，請下載下面的 Quarto 文檔 (.qmd) 并在 RStudio 中打開它。
Download authoring.qmd:
https://quarto.org/docs/get-started/authoring/_authoring.qmd
為了創(chuàng)建 PDFs漫拭，您需要安裝最新的 LaTeX 發(fā)行版亚兄。我們推薦使用 TinyTeX（它基于 TexLive），您可以使用以下命令安裝它：
quarto install tinytex
有關(guān)使用其他 LaTeX 發(fā)行版和 PDF 編譯引擎的詳細(xì)信息采驻，請參閱有關(guān) PDF Engines 的文章审胚。
設(shè)置完 LaTeX 后，單擊 Render（或使用鍵盤快捷鍵 ??K）挑宠。我們建議還選中 Render on Save 框菲盾，以實時預(yù)覽您的更改。如下所示各淀，您應(yīng)該在 RStudio 的查看器中看到渲染的 PDF懒鉴。
接下來，讓我們向 YAML 添加一個選項碎浇，例如將行號添加到代碼塊中（code-line-numbers：true）临谱。將此選項添加到文檔的 YAML 中，如下所示奴璃，注意縮進(jìn)方案悉默。在 format: 中我們的格式選擇 pdf 是縮進(jìn)的（有兩個空格），后面跟著 : 表示將指定該格式的更多選項苟穆。在下一行中抄课，進(jìn)一步縮進(jìn)兩個空格，我們添加 code-line-numbers: true雳旅。
---
title: "Housing Prices"
author: "Mine ?etinkaya-Rundel"
format:
pdf:
code-line-numbers: true
---
如果您之前選中了 Render on Save跟磨，則只需在進(jìn)行此更改后保存文檔即可進(jìn)行實時預(yù)覽。否則呈現(xiàn)文檔以查看反映的更新攒盈，包括如下所示的目錄抵拘。
revealjs 是一個令人難以置信的令人興奮的格式選項，我們不會在本教程中詳細(xì)介紹型豁。是的僵蛛，您也可以使用 Quarto 進(jìn)行演示文稿！事實上迎变，Quarto 支持多種用于創(chuàng)建演示文稿的格式充尉，包括用于 HTML 幻燈片的 revealjs、用于 PowerPoint 的 pptx 以及用于 LaTeX/PDF 的 beamer衣形。Presentations 文章詳細(xì)介紹了如何使用 Quarto 創(chuàng)建幻燈片驼侠。
多種格式
您創(chuàng)建的某些文檔只有一種輸出格式，但在許多情況下，需要支持多種格式泪电。讓我們將 html 和 docx 格式添加到我們的文檔中，并修改特定于每種格式的一些選項纪铺。
---
title: "Housing Prices"
author: "Mine ?etinkaya-Rundel"
highlight-style: pygments
format:
html:
code-fold: true
html-math-method: katex
pdf:
geometry:
- top=30mm
- left=30mm
docx: default
---
這里有很多東西值得一看相速！讓我們把它分解一下。前兩行是通用文檔元數(shù)據(jù)鲜锚，與輸出格式根本無關(guān)突诬。
---
title: "Housing Prices"
author: "Mine ?etinkaya-Rundel"
---
下一行是適用于所有格式的文檔格式選項，這就是它在根級別指定的原因芜繁。
---
highlight-style: pygments
---
接下來旺隙，我們有 format 選項，我們在其中提供特定于格式的選項骏令。
---
format:
html:
code-fold: true
html-math-method: katex
pdf:
geometry:
- top=30mm
- left=30mm
docx: default
---
html 和 pdf 格式各自提供一兩個選項蔬捷。例如，對于 HTML 輸出榔袋，我們希望用戶能夠控制是否顯示或隱藏代碼 (code-fold: true) 并使用 katex 來處理數(shù)學(xué)文本周拐。對于 PDF，我們定義了一些邊距凰兑。 docx 格式有點不同 -- 它指定 docx: default妥粟。這表明我們只想使用該格式的所有默認(rèn)選項。
3 渲染
單擊 RStudio 中的 Render 按鈕（或使用鍵盤快捷鍵 ??K）會將文檔渲染為 YAML 中列出的第一種格式吏够。
請注意勾给，Render 按鈕還有一個下拉菜單，使您能夠渲染為 YAML 前面列出的任何格式：
如果您想渲染為所有格式锅知，可以使用 quarto 包來實現(xiàn)播急，它為 Quarto CLI 提供了 R 接口。例如喉镰，要渲染當(dāng)前文檔旅择，請使用 quarto::quarto_render()。您還可以指定要呈現(xiàn)的文檔的名稱以及輸出格式侣姆。
quarto::quarto_render(
"authoring.qmd",
output_format = c("pdf", "html", "docx")
)
結(jié)果生真，您將看到三個新文件出現(xiàn)在“Files”窗格中：
authoring.docxauthoring.htmlauthoring.pdf
4 部分
您可以使用目錄和/或章節(jié)編號來使讀者更輕松地瀏覽您的文檔。通過將 toc 和/或 number-sections 選項添加到文檔選項來執(zhí)行此操作捺宗。請注意柱蟀，這些選項通常在根級別指定，因為它們在所有格式之間共享蚜厉。
---
title: "Housing Prices"
author: "Mine ?etinkaya-Rundel"
toc: true
number-sections: true
highlight-style: pygments
format:
html:
code-fold: true
html-math-method: katex
pdf:
geometry:
- top=30mm
- left=30mm
docx: default
---
這是該文檔呈現(xiàn)為 HTML 時的樣子长已。
有很多選項可用于控制目錄和章節(jié)編號的行為方式。有關(guān)更多詳細(xì)信息，請參閱輸出格式文檔（例如 HTML术瓮、PDF康聂、MS Word）。
5 方程
如果您使用可視化編輯器模式胞四，則可以使用 Insert Anything 工具將 LaTeX 方程添加到 RStudio 中的 Quarto 文檔中恬汁。您可以在空塊的開頭使用 / 或在其他任何地方使用 Cmd+/ 來訪問它。
顯示方程（在新行中）用 $$...$$ 分隔辜伟，而內(nèi)聯(lián)方程用 $...$ 分隔氓侧。添加以下內(nèi)容作為文檔中的顯示數(shù)學(xué)。
$$
price = \hat{\beta}_0 + \hat{\beta}_1 \times area + \epsilon
$$
當(dāng)您在編輯器中鍵入教程時导狡，RStudio 會顯示教程的渲染版本约巷。有關(guān)更多詳細(xì)信息，請參閱有關(guān) markdown equations 的文檔旱捧。
6 引文
Insert Anything 工具還可用于在文檔中插入引文独郎。
在下一個窗口中，您可以通過各種來源插入引文廊佩，包括您的文檔書目遮咖、Zotero 個人或團(tuán)隊 libraries憎茂、DOI (Document Object Identifier) references 以及 Crossref根吁、DataCite 或 PubMed 的搜索譬涡。您可以在此處找到有關(guān)使用可視化編輯器引用的更多信息。
選擇左側(cè)的 From DOI料皇，然后將 DOI 10.1093/comjnl/27.2.97 復(fù)制并粘貼到搜索欄中谓松，然后點擊 Search。然后践剂，選擇找到的 reference鬼譬，并將其 insert 到您的文檔中。
如果這是您添加到文檔中的第一個 citation逊脯，RStudio 將自動為您創(chuàng)建一個參考書目文件优质。默認(rèn)情況下，該文件名為 references.bib军洼，RStudio 還會將 bibliography: references.bib 添加到文檔的 YAML 元數(shù)據(jù)中巩螃。
請注意，參考書目中的項目是使用 @citeid 語法引用的匕争。將以下文本添加到您的文檔中避乏。
We're going to do this analysis using literate programming [@knuth1984].
參考文獻(xiàn)將包含在文檔的末尾，因此我們在筆記本底部包含一個 ## References甘桑。您還可以通過單擊三個點 (...) 來編輯其屬性拍皮，將 .unnumbered 類添加到此部分歹叮。
這是該文檔渲染后的樣子（刪除了中間部分以突出顯示相關(guān)部分）。
@ 引用語法非常靈活铆帽，包括對前綴咆耿、后綴、定位符和文本內(nèi)引用的支持爹橱。請參閱有關(guān) Citations and Footnotes 的文檔以了解更多信息票灰。
7 交叉引用
交叉引用通過提供數(shù)字、表格宅荤、方程和章節(jié)的編號參考和超鏈接，使讀者能夠更輕松地瀏覽文檔浸策》爰可交叉引用的實體通常需要標(biāo)簽（唯一標(biāo)識符）和標(biāo)題。
例如庸汗，要向之前插入的方程添加標(biāo)簽惫确，請單擊三個點來編輯其屬性并使用建議的格式（以 #eq- 開頭）來標(biāo)記方程。
然后蚯舱，使用可視化編輯器中的 Insert Anything 工具添加交叉引用改化。您可以添加諸如 "We can fit a simple linear regression model of the form shown in" 之類的句子來將交叉引用置于上下文中，然后將引用添加到該句子的末尾枉昏。
在 Insert Cross Reference 菜單中陈肛，導(dǎo)航到左側(cè)所需的交叉引用實體，然后選擇之前標(biāo)記的方程兄裂。
或者句旱，開始在可視化編輯器中鍵入要引用的方程的標(biāo)簽，自動填充工具將顯示交叉引用以供選擇晰奖。
下面我們使用您一直使用的文檔中的片段來說明交叉引用各種類型的實體谈撒。
We present the results of exploratory data analysis in @sec-eda and the regression model in @sec-model.
@fig-scatterplot displays the relationship between these two variables in a scatterplot.
@tbl-stats displays basic summary statistics for these two variables.
We can fit a simple linear regression model of the form shown in @eq-slr.
該示例包括交叉引用的部分、圖形和方程匾南。下表總結(jié)了我們?nèi)绾伪磉_(dá)這些內(nèi)容啃匿。
| Entity | Reference | Label / Caption | ||
|---|---|---|---|---|
| Section | @sec-eda |
ID added to heading: # Exploratory data analysis {#sec-eda}
|
||
| Figure | @fig-scatterplot |
YAML options in code cell: `# | label: fig-scatterplot # | fig-cap: "Scatterplot of price vs. area of houses in Duke Forest"` |
| Table | @tbl-stats |
YAML options in code cell: `# | label: tbl-stats # | tbl-cap: "Summary statistics for price and area of houses in Duke Forest"` |
| Equation | @eq-slr |
At end of display equation: $$ {#eq-slr}
|
請參閱有 Cross References 的文章以了解更多信息，包括如何自定義標(biāo)題和參考文本（例如使用“Fig.”而不是“Figure”）蛆楞。
8 標(biāo)注
標(biāo)注是一種很好的方式溯乒，可以吸引人們對某些概念的額外關(guān)注，或者更清楚地表明某些內(nèi)容是補(bǔ)充性的或僅適用于某些場景臊岸。
標(biāo)注是具有特殊標(biāo)注屬性的 Markdown div橙数。我們可以使用 Insert Anything 工具插入標(biāo)注。
在隨后的對話框中帅戒，您可以選擇五種標(biāo)注類型之一（注釋灯帮、提示崖技、重要、注意或警告）钟哥，自定義其外觀（默認(rèn)迎献、簡單或最小）腻贰，并決定是否要顯示圖標(biāo)吁恍。
然后，嘗試在標(biāo)注框中插入以下文本播演。
This is a pretty incomplete analysis, but hopefully the document provides a good overview of some of the authoring features of Quarto!
這是可視化編輯器中標(biāo)注的樣子冀瓦。
這是輸出文檔中渲染的標(biāo)注。
您可以在 Callouts 文檔中了解有關(guān)不同類型標(biāo)注及其外觀選項的更多信息写烤。
9 文章布局
Quarto 文章正文的默認(rèn)寬度約為 700 像素翼闽。選擇此寬度是為了優(yōu)化可讀性。這通常會在文檔頁邊距中留下一些可用空間洲炊，您可以通過多種方式利用該空間感局。
我們可以使用 column: page-right 單元選項來指示我們希望圖形占據(jù)屏幕的整個寬度，并帶有一些插圖暂衡。繼續(xù)并將此代碼塊選項添加到標(biāo)記為 fig-histogram 的代碼塊中询微。
#| label: fig-histogram
#| fig-cap: "Histograms of individual variables"
#| fig-subcap:
#| - "Histogram of `price`s"
#| - "Histogram of `area`s"
#| layout-ncol: 2
#| column: page-right
以下是文檔的相關(guān)部分渲染后的樣子。
您可以在頁邊空白處找到引文狂巢、腳注和旁白撑毛。您還可以為圖形、表格或其他內(nèi)容定義自定義列跨度唧领。有關(guān)更多詳細(xì)信息代态，請參閱有關(guān) Article Layout 的文檔。
10 發(fā)布
將文檔渲染為 HTML 后疹吃，您只需單擊編輯器工具欄或預(yù)覽窗口上的 Publish 按鈕即可將其發(fā)布到 RPubs（RStudio 的一項免費服務(wù)蹦疑，用于在網(wǎng)絡(luò)上共享文檔）∪唬或者歉摧，您可以使用 quarto::quarto_publish_doc() 函數(shù)。
quarto::quarto_publish_doc(
"authoring.qmd",
server = "rpubs.com"
)
其他可能的發(fā)布選項包括 RStudio Connect 和 ShinyApps 以及 GitHub Pages腔呜、Netlify 等叁温。Publishing HTML 文章更詳細(xì)地概述了您的發(fā)布選項。
如果您按照本教程的步驟進(jìn)行操作核畴，那么您現(xiàn)在應(yīng)該擁有一個 Quarto 文檔膝但，該文檔實現(xiàn)了我們所涵蓋的所有內(nèi)容。否則谤草，您可以下載下面的 computations.qmd 的完整版本跟束。
Download authoring-complete.qmd:
https://quarto.org/docs/get-started/authoring/_authoring-complete.qmd
11 了解更多
您現(xiàn)在已經(jīng)了解了使用 Quarto 的基礎(chǔ)知識莺奸！一旦您能夠輕松地創(chuàng)建和自定義文檔，這里還有一些需要探索的事情：
- Presentations 使用您為創(chuàng)建文檔所學(xué)的相同語法來創(chuàng)作 PowerPoint冀宴、Beamer 和 Revealjs 演示文稿灭贷。
- Websites 將文檔集發(fā)布為網(wǎng)站。網(wǎng)站支持多種形式的導(dǎo)航和全文搜索略贮。
- Blogs 創(chuàng)建一個包含“關(guān)于”頁面甚疟、靈活的帖子列表、類別逃延、RSS 源和二十多個主題的博客览妖。
- Books 創(chuàng)建印刷版（PDF、MS Word）和在線版（HTML揽祥、ePub）格式的書籍和手稿黄痪。
- Interactivity 包括交互式組件，以幫助讀者更深入地探索您所呈現(xiàn)的概念和數(shù)據(jù)盔然。
詳細(xì)教程請參考 quarto Guide：
https://quarto.org/docs/guide/
<center><strong>結(jié)束</center></strong>
本文由mdnice多平臺發(fā)布
