项目基础

概述

Quarto 项目是提供以下功能的目录：

通过单个命令渲染目录中的所有或部分文件（例如 quarto render myproject）。
在多个文档之间共享 YAML 配置。
将输出工件重定向到另一个目录的能力。
冻结渲染输出的能力（即除非文档已更改，否则不重新执行文档）。

此外，项目可以具有引入额外行为的特殊“类型”（例如网站或书籍）。

Note

如果你刚刚开始使用 Quarto 或没有使用过 markdown 发布系统的经验，你可能现在想跳过学习项目的内容。一旦你熟悉了基础知识，再回到本文了解更多信息。

创建项目

使用 quarto create project 命令创建一个新项目，使用提示。

Terminal

quarto create project

Output

 ? Type
 ❯ default
   website
   blog
   manuscript
   book
   confluence

或者将类型和项目名称定义为参数。

Terminal

quarto create project <type> <name>

共享元数据

Quarto 项目最重要的功能之一是能够在多个文档之间共享 YAML 元数据选项。共享元数据可以在项目和目录级别定义。

项目元数据

所有 Quarto 项目都包含一个 _quarto.yml 配置文件。在项目目录中渲染的任何文档都会自动继承在项目级别定义的元数据。以下是 _quarto.yml 文件可能的样子：

_quarto.yml

project:
  output-dir: _output

toc: true
number-sections: true
bibliography: references.bib  
  
format:
  html:
    css: styles.css
    html-math-method: katex
  pdf:
    documentclass: report
    margin-left: 30mm
    margin-right: 30mm

请注意，项目文件包含适用于所有格式的全局选项（例如 toc 和 bibliography）以及特定于格式的选项。

你可以根据不同的项目配置文件进一步自定义项目元数据（例如开发与生产或创建书籍或网站的多个版本）。有关更多详细信息，请参阅项目配置文件文章。

目录元数据

你还可以定义仅应由目录中的文件继承的元数据。为此，请在要共享元数据的目录中添加一个 _metadata.yml 文件。例如，以下 _metadata.yml 为一系列演示文稿设置了默认的 Revealjs 选项，并禁用了目录中文档的 search：

_metadata.yml

format:
  revealjs: 
    menu: false
    progress: false
search: false

这些文件中提供的选项使用与 _quarto.yml 相同的模式，并与你在 _quarto.yml 中已经提供的任何选项合并。

元数据合并

在 _quarto.yml、_metadata.yml 和文档级 YAML 选项中定义的元数据会合并在一起。文档级选项优先，其次是目录选项，最后是项目级选项：

文件	角色
`_quarto.yml`	项目级默认选项
`dir/_metadata.yml`	目录级默认选项（覆盖项目）
`dir/document.qmd`	文档选项（覆盖目录和项目）

请注意，当元数据合并时，对象和数组会合并而不是简单地相互覆盖。例如，以下是影响输出格式和参考文献的项目和目录级选项如何合并：

_quarto.yml

format:
  html:
    toc: true
bibliography:
  - refs.bib

dir/_metadata.yml

format:
  html:
    code-fold: true
bibliography:
  - proj.bib

merged

format:
  html:
    toc: true
    code-fold: true
bibliography:
  - refs.bib
  - proj.bib

元数据合并的唯一例外是 format。如果文档级别的 YAML 定义了格式，则必须定义要渲染的完整格式列表。

元数据包含

您可能会发现将元数据拆分为多个文件很方便。您可以使用 metadata-files 选项来实现这一点。例如，在这里我们在 _quarto.yml 中包含了一个单独的 _website.yml 文件来设置一些网站选项：

_quarto.yml

project:
  type: website
  
metadata-files:
  - _website.yml

_website.yml

website:
  navbar:
    background: primary
    left:
      - href: index.qmd
        text: Home
      - about.qmd

metadata-files 中列出的文件与父文件以相同的方式合并，就像项目、目录和文档选项的合并方式一样。这意味着包含的文件既可以提供新选项，也可以与现有选项结合。

本地配置

有时定义不提交到版本控制的本地项目配置更改很有用。您可以通过创建一个 _quarto.yml.local 配置文件来实现这一点。例如，在这里我们指定我们希望在本地运行时使用执行缓存：

_quarto.yml.local

execute:
  cache: true

请注意，Quarto 会自动向 .gitignore 写入一个条目，以确保 .local 文件不会被提交（请注意，环境变量也可以在类似的 .local 文件中定义）。

渲染项目

您可以逐个或一次性渲染项目中的文件（无论哪种情况，都将使用共享的项目元数据）。

要渲染项目中的所有文档，只需在项目目录中使用 quarto render（或使用命令行参数指定特定目录）：

Terminal

# 在当前目录中渲染项目
quarto render 

# 在 'myproject' 中渲染项目
quarto render myproject

您还可以仅渲染项目子目录中的文件。例如，如果当前目录包含一个具有子目录 tutorials、how-to 和 articles 的项目，您可以按如下方式仅渲染 articles 的内容：

Terminal

# 仅渲染 'articles' 子目录中的文档
quarto render articles

请注意，在渲染项目时，您传递给 quarto render 的命令行参数将用于项目中的每个文件。例如，此命令将仅渲染 PDF 格式：

Terminal

quarto render --to pdf
quarto render myproject --to pdf

如果您从 R 中使用 Quarto，您还可以使用 quarto R 包从 R 控制台渲染项目。

library(quarto)
quarto_render()

渲染目标

默认情况下，项目目录中所有有效的 Quarto 输入文件（.qmd、.ipynb、.md、.Rmd）都将被渲染，以下情况除外：

文件或目录前缀为 .（隐藏文件）
文件或目录前缀为 _（通常用于非顶级文件，例如在其他文件中包含的文件）
文件名为 README.md 或 README.qmd（这些文件通常不是实际的渲染目标，而是用于版本控制 Web UI 中查看的源代码信息内容）。

如果你不想渲染项目中的所有目标文档，或者希望更精确地控制渲染顺序，可以在项目元数据中添加 project: render: [files] 条目。例如：

project:
  render:
    - section1.qmd
    - section2.qmd

请注意，在定义 render 列表时可以使用通配符。例如：

project:
  render:
    - section*.qmd

你还可以在 render 列表中使用前缀 ! 来忽略某些文件或目录。请注意，在这种情况下，你需要首先指定你确实想要渲染的所有内容。例如：

project:
  render:
    - "*.qmd"
    - "!ignored.qmd"
    - "!ignored-dir/"

Note

如果你的输出文件名需要以 . 或 _ 开头（例如 Hugo 用户的 _index.md），你必须在不带前缀的情况下命名 Quarto 输入文件（例如 index.qmd），并在 YAML 中添加显式的 output-file 参数，例如

---
output-file: _index.md
---

了解更多

这些文章提供了有关 Quarto 项目更高级功能的更多文档：

管理执行涵盖了您可以使用的各种技术，以最小化重建具有昂贵计算的站点所需的时间。
项目配置文件描述了如何为不同场景（例如开发与生产或创建书籍或网站的多个版本）调整项目的选项和内容。
环境变量涵盖了如何定义在渲染项目时应设置的环境变量（包括如何根据项目配置文件和/或用于本地开发而变化这些变量）。
项目脚本描述了如何为项目的输入数据和输出添加定期或预/后渲染脚本以进行特殊处理。
虚拟环境探讨了如何创建项目特定的包库，这有助于随着时间的推移忠实地重现您的环境，并确保在一个项目中升级包不会破坏其他项目。