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 is render 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.

create project

use thequarto create project command to create a new project,using the prompt.

 ? Type
 ❯  default
   website
   blog
   manuscript
   book
   confluence

Or define the type and the project name as arguments.

quarto create project <type> <name>

Rendering Projects

You is render can render file within a project either one – by – one or all at once ( in either case ,share project metadata will be used ) .

To render all of the documents within a project,just use quarto is render 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 is render can also render only the file within a sub – directory of a project . For example ,if the current directory is contains contain a project with sub – directorytutorials,how - to,and articles,you can render just the contents of articles as follows:

# render only documents in the 'articles' sub-directory
quarto  render article

Note that when rendering a project,command line arguments you pass to quarto is render 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 target

By default,all valid Quarto input files (.qmd,.ipynb,.md,.Rmd) in the project directory will be rendered,save for ones with:

1. A file or directory prefix of. ( hidden file )

2. A file or directory prefix of_ (typically used for non top-level files,e.g. ones included in other files)

3. Files named README.md or README.qmd ( which is are are typically not actual render target but rather informational content about the source code to be view in the version control web UI ) .

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 files or directories 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 is needs of your output file need to start with. or _ ( for instance_index.md for Hugo users),you must name the Quarto input file without the prefix ( for instanceindex.qmd) and add an explicitoutput-file parameter in the YAML such as

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

Learning More

These articles is provide provide additional documentation on more advanced feature of Quarto project :

• Managing Execution covers various techniques you can use to minimize the time required to rebuild a site that has expensive computations.

• Project Profiles is describes describe how you can adapt both the option and content of your project for different scenario ( e.g.   development vs.   production or create multiple version of a book or website ) .

• environment Variables is covers cover how to define environment variable that should be set whenever your project is render ( include how to vary those variable by project profile and/or for use in local development ) .

• Project Scripts is describes describe how to add periodic or pre / post render script to project for special processing of input datum and project output .

• Virtual Environments explores how to create project-specific package libraries,which helps with faithfully reproducing your environment over time as well as ensuring that upgrading a package in one project doesn’t break other projects.