教程：创作

概述

在本教程中，我们将向您展示如何在 Jupyter Lab 中编写 Quarto 文档。特别是，我们将讨论您可以生成的各种文档格式，并向您展示如何添加目录、方程式、引文、交叉引用等组件。

输出格式

Quarto 支持将笔记本渲染为数十种不同的输出格式。默认情况下，使用该格式，但您可以在文档选项中指定一种（或多种）备用格式。<font style="background-color:rgb(248, 249, 250);">html</font> ### 格式选项 让我们创建一个笔记本并定义要渲染的各种格式，并为每种格式添加一些选项。提醒一下，文档选项在笔记本开头的“原始”单元格中的 YAML 中指定。若要创建 Raw 单元格，请在笔记本顶部添加一个单元格，并使用笔记本工具栏将其类型设置为 Raw：

样式 - 图1

现在，让我们添加一些基本的文档元数据和默认输出格式。 
  1. ---
  2. title: "Quarto Document"
  3. author: "Norah Jones"
  4. format: pdf
  5. jupyter: python3
  6. ---

样式 - 图2

我们指定为默认输出格式（如果我们排除该选项，则它将默认为 ）。<font style="background-color:rgb(248, 249, 250);">pdf</font>``<font style="background-color:rgb(248, 249, 250);">format</font>``<font style="background-color:rgb(248, 249, 250);">html</font> 让我们添加一些选项来控制我们的 PDF 输出。 
  1. ---
  2. title: "Quarto Document"
  3. author: "Norah Jones"
  4. format: 
  5.   pdf: 
  6.     toc: true
  7.     number-sections: true
  8. jupyter: python3
  9. ---

样式 - 图3

多种格式

您创建的某些文档将只有一种输出格式，但在许多情况下，需要支持多种格式。让我们将 和 格式添加到我们的文档中。<font style="background-color:rgb(248, 249, 250);">html</font>``<font style="background-color:rgb(248, 249, 250);">docx</font> plain --- title: "Quarto Document" author: "Norah Jones" toc: true number-sections: true highlight-style: pygments format: html: code-fold: true html-math-method: katex pdf: geometry: - top=30mm - left=20mm docx: default jupyter: python3 --- 样式 - 图4 这里有很多东西可以看！让我们分解一下。前两行是与输出格式完全无关的通用文档元数据。 
  1. title: "Quarto Document"
  2. author: "Norah Jones"
接下来的三行是适用于所有格式的文档格式选项。这就是为什么在根级别指定它们的原因。 
  1. toc: true
  2. number-sections: true
  3. highlight-style: pygments
接下来，我们有一个选项，我们在其中提供特定于格式的选项。<font style="background-color:rgb(248, 249, 250);">format</font> plain format: html: code-fold: true html-math-method: katex pdf: geometry: - top=30mm - left=30mm docx: default 和 格式各提供一两个选项。例如，对于 HTML 输出，我们希望用户能够控制是否显示或隐藏代码 （） 并用于数学文本。对于 PDF，我们定义了一些边距。格式略有不同 - 它指定 .这意味着只需使用格式的所有默认选项。<font style="background-color:rgb(248, 249, 250);">html</font>``<font style="background-color:rgb(248, 249, 250);">pdf</font>``<font style="background-color:rgb(248, 249, 250);">code-fold: true</font>``<font style="background-color:rgb(248, 249, 250);">katex</font>``<font style="background-color:rgb(248, 249, 250);">docx</font>``<font style="background-color:rgb(248, 249, 250);">docx: default</font> ## 渲染 文档选项中指定的格式定义默认呈现的内容。如果我们使用以下命令使用上面给出的所有选项渲染笔记本。 Terminal quarto render notebook.ipynb 然后，将创建以下文件。
  • <font style="background-color:rgb(248, 249, 250);">notebook.html</font>
  • <font style="background-color:rgb(248, 249, 250);">notebook.pdf</font>
  • <font style="background-color:rgb(248, 249, 250);">notebook.docx</font>
我们可以使用该选项选择一种或多种格式。<font style="background-color:rgb(248, 249, 250);">--to</font> Terminal 
  1. quarto render notebook.ipynb --to docx
  2. quarto render notebook.ipynb --to docx,pdf
请注意，目标文件（在本例中）应始终是第一个命令行参数。<font style="background-color:rgb(248, 249, 250);">notebook.ipynb</font> 如果需要，我们还可以呈现文档选项中未指定的格式。 Terminal quarto render notebook.ipynb —to odt 由于格式不包含在文档选项中，因此将使用该格式的默认选项。<font style="background-color:rgb(248, 249, 250);">odt</font> 请注意，在渲染 Quarto 时，默认情况下不会执行笔记本中的单元格（假定您在编辑笔记本时已经执行了它们）。如果要执行单元格，可以传递要渲染的标志。<font style="background-color:rgb(248, 249, 250);">.ipynb</font>``<font style="background-color:rgb(248, 249, 250);">--execute</font> Terminal quarto render notebook.ipynb —execute

部分

您可以使用目录和/或章节编号来使读者更轻松地浏览您的文档。为此，请将 and/or 选项添加到文档选项中。请注意，这些选项通常在根级别指定，因为它们在所有格式之间共享。<font style="background-color:rgb(248, 249, 250);">toc</font>``<font style="background-color:rgb(248, 249, 250);">number-sections</font> plain --- title: Quarto Basics author: Norah Jones date: 'May 22, 2021' toc: true number-sections: true jupyter: python3 --- ## Colors - Red - Green - Blue ## Shapes - Square - Circle - Triangle ## Textures - Smooth - Bumpy - Fuzzy 样式 - 图5 下面是此文档呈现为 HTML 时的样子。

样式 - 图6

有许多选项可用于控制目录和章节编号的行为方式。有关更多详细信息，请参阅输出格式文档（例如 HTML、PDF、MS Word）。

方程

您可以将 LaTeX 方程式添加到 Jupyter Lab 中的降价单元格。 
  1. Einstein's theory of special relatively that expresses the equivalence of mass and energy:
  3. $E = mc^{2}$
𝐸=𝑚𝑐2

样式 - 图7

运行单元格时将呈现方程式。

样式 - 图8

内联方程用 分隔。要在新行中创建方程（显示方程），请使用 。有关更多详细信息，请参阅有关 Markdown 公式的文档。<font style="background-color:rgb(248, 249, 250);">$…$</font>``<font style="background-color:rgb(248, 249, 250);">$$…$$</font> ## 引文 引用 Quarto 文档中的其他作品。首先，以支持的格式（BibTeX 或 CSL）创建参考书目文件。然后，使用 YAML 元数据选项将参考书目链接到您的文档。<font style="background-color:rgb(248, 249, 250);">bibliography</font> 这是一本笔记本，包括参考书目和单个引文。请注意，Markdown 单元格是未执行的，因此您可以看到所有语法。 
  1. ---
  2. title: Quarto Basics
  3. format: html
  4. bibliography: references.bib
  5. jupyter: python3
  6. ---
  8. ## Overview
  10. Knuth says always be literate [@knuth1984].
  12. ```{python}
  13. 1 + 1

References

  2. ![](https://cdn.nlark.com/yuque/0/2024/png/39191047/1721718602752-5910e07d-59e5-412b-bdb1-ffa5ce9ac48b.png)
  4. <font style="color:rgb(52, 58, 64);">请注意，参考书目中的项目使用语法引用。</font>`<font style="background-color:rgb(248, 249, 250);">@citeid</font>`
  6. <font style="color:rgb(0, 59, 79);"> Knuth says always be literate [@knuth1984].</font>
  8. <font style="color:rgb(52, 58, 64);">参考文献将包含在文档的末尾，因此我们在笔记本的底部包含一个标题。</font>`<font style="background-color:rgb(248, 249, 250);">## References</font>`
  10. <font style="color:rgb(52, 58, 64);">这是此文档呈现时的样子。</font>
  12. ![](https://cdn.nlark.com/yuque/0/2024/png/39191047/1721718603230-fc8f8731-e7d0-4277-8d2b-4d33a56b4a21.png)
  14. <font style="color:rgb(52, 58, 64);">  
  15. </font><font style="color:rgb(52, 58, 64);">引文语法非常灵活，包括对前缀、后缀、定位符和文本内引文的支持。请参阅有关</font>[<font style="color:rgb(52, 58, 64);">引文</font>](https://quarto.org/docs/authoring/citations.html)<font style="color:rgb(52, 58, 64);">的文档以了解更多信息。</font>`<font style="background-color:rgb(248, 249, 250);">@</font>`
  17. ## 交叉引用
  18. <font style="color:rgb(52, 58, 64);">交叉引用通过提供编号的参考文献和指向图形、表格、方程式和部分的超链接，使读者更容易浏览您的文档。可交叉引用的实体通常需要标签（唯一标识符）和标题。</font>
  20. <font style="color:rgb(52, 58, 64);">下面的笔记本演示了各种类型的实体的交叉引用。再次取消执行 markdown 单元格，以便语法可见。</font>
  22. ```plain
  23. ---
  24. title: Quarto Crossrefs
  25. format: html
  26. jupyter: python3
  27. ---
  29. ## Overview
  31. See @fig-simple in @sec-plot for a demonstration of a simple plot. 
  33. See @eq-stddev to better understand standard deviation.
  35. ## Plot {#sec-plot}
  37. ```{python}
  38. #| label: fig-simple
  39. #| fig-cap: "Simple Plot"
  40. import matplotlib.pyplot as plt
  41. plt.plot([1,23,2,4])
  42. plt.show()

Equation {#sec-equation}

$$ s = \sqrt{\frac{1}{N-1} \sum_{i=1}^N (x_i - \overline{x})^2} $$ {#eq-stddev}

  2. <font style="color:rgb(52, 58, 64);">𝑥</font><font style="color:rgb(52, 58, 64);">+</font><font style="color:rgb(52, 58, 64);">1</font>
  4. ![](https://cdn.nlark.com/yuque/0/2024/png/39191047/1721718604433-1ccdb168-54af-4d68-8674-707c00989655.png)
  6. <font style="color:rgb(52, 58, 64);">此示例包括交叉引用的截面、图形和方程式。下表显示了我们如何表达这些。</font>
  8. | 实体 | 参考 | 标签/标题 |
  9. | --- | --- | --- |
  10. | 部分 | `<font style="background-color:rgb(248, 249, 250);">@sec-plot</font>` | 添加到标题的 ID：<br/><font style="color:rgb(0, 59, 79);"># Plot {#sec-plot}</font> |
  11. | 数字 | `<font style="background-color:rgb(248, 249, 250);">@fig-simple</font>` | 代码单元中的 YAML 选项：<br/>```plain #| label: fig-simple #| fig-cap: "Simple Plot" ```  |
  12. | 方程 | `<font style="background-color:rgb(248, 249, 250);">@eq-stddev</font>` | 在显示公式的末尾：<br/><font style="color:rgb(0, 59, 79);">$$ {#eq-stddev}</font> |
  15. <font style="color:rgb(52, 58, 64);">最后，这是这个笔记本在渲染时的样子。</font>
  17. ![](https://cdn.nlark.com/yuque/0/2024/png/39191047/1721718604598-131a4878-dba7-4c7b-9cfb-98fcabef67f6.png)
  19. <font style="color:rgb(52, 58, 64);">请参阅有关</font>[<font style="color:rgb(52, 58, 64);">交叉引用</font>](https://quarto.org/docs/authoring/cross-references.html)<font style="color:rgb(52, 58, 64);">的文章以了解更多信息，包括如何自定义标题和参考文本（例如，使用“Fig.”而不是“Figure”）。</font>
  21. ## 标注
  22. <font style="color:rgb(52, 58, 64);">标注是引起对某些概念的额外关注，或者更清楚地表明某些内容是补充或仅适用于某些方案的绝佳方式。</font>
  24. <font style="color:rgb(52, 58, 64);">标注是具有特殊标注属性的 Markdown div。下面是在 Markdown 单元格中创建标注的示例。</font>
  26. ```plain
  27. ::: {.callout-note}
  28. Note that there are five types of callouts, including:
  29. `note`, `tip`, `warning`, `caution`, and `important`.
  30. :::

样式 - 图9

当我们最终使用 Quarto 渲染文档时，标注会按预期显示。

注意

请注意，有五种类型的标注，包括 、 、 、 和 。<font style="background-color:rgb(248, 249, 250);">note</font>``<font style="background-color:rgb(248, 249, 250);">tip</font>``<font style="background-color:rgb(248, 249, 250);">warning</font>``<font style="background-color:rgb(248, 249, 250);">caution</font>``<font style="background-color:rgb(248, 249, 250);">important</font> 您可以在标注文档中了解有关不同类型的标注及其显示选项的更多信息。

文章布局

Quarto 文章的正文默认宽度约为 700 像素。选择此宽度是为了优化可读性。这通常会在文档页边距中留下一些可用空间，您可以通过多种方式利用此空间。 在此笔记本中，我们使用该选项来指示我们希望将脚注放在右边距中。<font style="background-color:rgb(248, 249, 250);">reference-location</font> 我们还使用单元格选项来表示我们希望我们的图形占据屏幕的整个宽度，并带有一个小插图。<font style="background-color:rgb(248, 249, 250);">column: screen-inset</font> plain --- title: Quarto Layout format: html reference-location: margin jupyter: python3 --- ## Placing Colorbars Colorbars indicate the quantitative extent of image data. Placing in a figure is non-trivial because room needs to be made for them. The simplest case is just attaching a colorbar to each axes:^[See the [Matplotlib Gallery](https://matplotlib.org/stable/gallery/subplots_axes_and_figures/colorbar_placement.html) to explore colorbars further].{python} #| code-fold: true #| column: screen-inset import matplotlib.pyplot as plt import numpy as np fig, axs = plt.subplots(2, 2) fig.set_size_inches(20, 8) cmaps = [‘RdBu_r’, ‘viridis’] for col in range(2): for row in range(2): ax = axs[row, col] pcm = ax.pcolormesh( np.random.random((20, 20)) * (col + 1), cmap=cmaps[col] ) fig.colorbar(pcm, ax=ax) plt.show() 样式 - 图10 这是此文档呈现时的样子。

样式 - 图11

您可以在页边空白处找到引文、脚注和旁白。您还可以为图窗、表格或其他内容定义自定义列跨度。有关更多详细信息，请参阅有关文章布局的文档。

了解更多

您现在已经学习了使用 Quarto 的基础知识！一旦您对创建和自定义文档感到满意，这里还有几件事需要探索：
  • 演示文稿 — 使用您在创建文档时学到的相同语法编写 PowerPoint、Beamer 和 Revealjs 演示文稿。
  • 网站 — 将文档集合发布为网站。网站支持多种形式的导航和全文搜索。
  • 博客 — 创建一个包含关于页面、灵活的帖子列表、类别、RSS 提要和 20 多个主题的博客。
  • 书籍 — 创建印刷版（PDF、MS Word）和在线版（HTML、ePub）格式的书籍和手稿。
  • 交互性 — 包括交互式组件，以帮助读者更深入地探索您正在呈现的概念和数据。