Project Basics
Overview
Quarto projects are directories that provide:
A way to render all or some of the files in a directory with a single command (e.g.
quarto render myproject
).A way to share YAML configuration across multiple documents.
The ability to redirect output artifacts to another directory.
The ability to freeze rendered output (i.e. don’t re-execute documents unless they have changed).
In addition, projects can have special “types” that introduce additional behavior (e.g. websites or books).
If you are just getting started with Quarto and/or you don’t have previous experience with markdown publishing systems, you probably want to skip learning about projects for now. Once you are comfortable with the basics, come back to this article to learn more.
Creating Projects
Use the quarto create-project
command to create a new project. If you have an existing directory of documents that you want to treat as a project just invoke create-project
with no arguments from within the directory:
quarto create-project
To create a project in a new directory just provide a directory name on the command line:
quarto create-project myproject
Rendering Projects
You can render files within a project either one-by-one or all at once (in either case, shared project metadata will be used).
To render all of the documents within a project, just use quarto render
within the project directory (or target a specific directory with a command line argument):
# render project in current dir
quarto render
# render project in 'myproject'
quarto render myproject
You can also render only the files within a sub-directory of a project. For example, if the current directory contains a project with sub-directories tutorials
, how-to
, and articles
, you can render just the contents of articles
as follows:
# render only documents in the 'articles' sub-directory
quarto render articles
Note that when rendering a project, command line arguments you pass to quarto render
will be used for each file in the project. For example. this command will render only the PDF format:
quarto render --to pdf
quarto render myproject --to pdf
If you are working with Quarto from R, you can also render a project from the R console using the quarto R package.
library(quarto)
quarto_render()
Render Targets
By default, all valid Quarto input files (.qmd, .ipynb, .md, .Rmd) in the project directory will be rendered, save for ones with a file or directory prefix of .
(hidden files) or _
(typically used for non top-level files, e.g. ones included in other files).
If you don’t want to render all of the target documents in a project, or you wish to control the order of rendering more precisely, you can add a project: render: [files]
entry to your project metadata. For example:
project:
render:
- section1.qmd
- section2.qmd
Note that you can use wildcards when defining the render
list. For example:
project:
render:
- section*.qmd
You can also use the prefix !
to ignore some paths in the render
list. Note that in that case you need to start by specifying everything you do want to render. For example:
project:
render:
- "*.qmd"
- "!ignored.qmd"
- "!ignored-dir/"
If the name of your output file needs to start with .
or _
(for instance _index.md
for Hugo users), you must name the Quarto input file without the prefix (for instance index.qmd
) and add an explicit output-file
parameter in the YAML such as
---
output-file: _index.md
---
Project Scripts
Many more complex projects have additional processing that needs to take place periodically (e.g. data import and preparation) or even before/after each render. Project scripts are a way to incorporate this processing into your workflow.
Periodic Scripts
You can use the quarto run
command to run a TypeScript, R, Python, or Lua script. For example:
quarto run import.py
Available script interpreters for quarto run
include:
Language | Interpreter |
---|---|
TypeScript | Deno (embedded in Quarto) |
R | Rscript from PATH |
Python | Python from PATH (or launcher on Windows) |
Lua | Lua 5.3 (embedded in Pandoc) |
Using TypeScript or Lua enables you to create scripts with no additional installation requirements. On the other hand, if your project is already using Python or R then scripts in those languages might be more convenient.
If you are using TypeScript, please be sure to consult the section below on Deno Scripts for additonal details on the Deno standard library and importing external scripts.
Pre and Post Render Scripts
You can arrange for one or more scripts to execute before and/or after each render using the pre-render
and post-render
project options. For example:
project:
type: website
pre-render: prepare.py
post-render:
- compress.ts
- fix-links.py
Note that pre-render
and post-render
also support arbitrary shell commands. So you could for example use make
to do data preparation this way:
project:
type: website
pre-render: make prepare
Pre and post render scripts are run with the main project directory.
The following environment variables are passed to pre and post-render scripts (note that all paths are relative to the main project directory):
Variable | Description |
---|---|
QUARTO_PROJECT_RENDER_ALL |
Set to “1” if this is a render of all files in the project (as opposed to an incremental render or a render for preview). This unset if Quarto is not rendering all files. |
QUARTO_PROJECT_OUTPUT_DIR |
Output directory |
QUARTO_PROJECT_INPUT_FILES |
Newline separated list of all input files being rendered (passed only to pre-render ) |
QUARTO_PROJECT_OUTPUT_FILES |
Newline separated list of all output files rendered (passed only to post-render ). |
If you have a pre-render
step that is expensive, you may want only run it when the entire project is being rendered. Here’s how you would do this in the various supported script languages:
if (!Deno.env.get("QUARTO_PROJECT_RENDER_ALL")) {
.exit();
Deno }
import os
if not os.getenv("QUARTO_PROJECT_RENDER_ALL"):
exit()
if (!nzchar(Sys.getenv("QUARTO_PROJECT_RENDER_ALL"))) {
quit()
}
if not os.getenv("QUARTO_PROJECT_RENDER_ALL") then
os.exit();
end
Deno Scripts
If you want to create project scripts with TypeScript, quarto run
enables you to use the Deno TypeScript interpreter bundled with Quarto. This interpreter also includes the complete Deno standard library. For example, to use the Deno YAML parser you would do this:
import { parse } from "https://deno.land/std/encoding/yaml.ts";
const config = parse(Deno.readTextFileSync("_quarto.yml"));
The reference to the Deno encoding
library above uses a URL: it’s important to note that in spite of this the library is not downloaded from a remote server (in fact, importing from remote servers is disabled entirely in the Quarto Deno interpreter). Rather, the Deno standard library is shipped with Quarto, making standard library URLs available in an offline cache.
You may come across example code that embeds versions directly in Deno library imports. For example:
import { format } from "https://deno.land/std@0.119.0/datetime/mod.ts";
These version-bound imports will not work with Quarto (as its local standard library cache is populated with unversioned URLs). The correct form of the above import is thus:
import { format } from "https://deno.land/std/datetime/mod.ts";
You may also see examples of Deno code that imports 3rd party libraries directly from URLs. As noted above, this functionality is not available in Quarto Deno scripts. Rather, you should download any external libraries you wish to use, include them with your project source code, and import them using relative file paths.