Documentation of project types is incomplete and/or not well organised

[allefeld]

What would you like to do?

Report an issue on quarto.org

Description

This issue is motivated by the discussion #9091, where I proposed a feature and @mcanouil pointed to the possibility to use a project of type default instead. This led to me trying to understand what a default project is, and finding the documentation unhelpful. Instead of rewriting, I'm citing myself from that discussion:

… I don't understand is what project: type: default does. I have used website projects, and it is relatively obvious what a book or manuscript project is – but what is a default project? I've searched the documentation but didn't come up with anything. Hugo Example uses project: type: default, but there is no explanation.

Generally, the documentation of project types is a bit sparse, or maybe just not well organised. On the Project Basics page in the Guide there is a list of project types in the form of output from quarto create project. Websites, Manuscripts, and Books have dedicated entries menu on the left, but the others don't. And in the Reference part of the documentation, Projects has sections again on Websites, Books, and Manuscripts, but not the other types.

In response to his statement that "Everything in Quarto is a project (especially since 1.5).":

Nowhere in the documentation is it stated that "everything in Quarto is a project". The Guide says:

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).

That strongly suggests that Quarto works with two kinds of input, a) single files where these additional features are not available (or do not apply) and b) directories containing multiple files (aka projects) where these additional features are available.

Moreover, all the project types which are documented (Websites, Books, and Manuscripts) create some sort of integration, where output files are either connected through links (e.g. in the navbar or sidebar) or there is only a single output file. That strongly suggests that such integration is the point of projects.

… I suspect a default project is one where there is no such integration – is that correct?

In summary, the documentation leaves me confused as to a) what a project is exactly and b) what different types there are and how they work.

[mcanouil]

Independently of updating the documentation, here is a new try:

A (default) project is a directory where Quarto documents (qmd/ipynb) obeys the configuration set in a file named _quarto.yml.

Website/Book/Manuscripts projects are "default" projects but with additional logics driven by a "format/layout" goal. The additional logics to use is defined by the project type value: type: website means apply all the code path related to a website layout.

In 1.5, single file document behaves as a project, in the sense as they follow the same code path, allowing the use of project options/keys such as output-dir.

[cscheid]

Yes, the project documentation will be updated as 1.5 is released. Please bear with us in the meantime, and thank you.

[allefeld]

Thanks @mcanouil for the explanation of default, that now makes sense.

Thanks @cscheid, of course, I'll wait for the new version. I just assumed you do the documentation updates along the way, since other 1.5 features are already documented.

[mcanouil]

Thanks @cscheid, of course, I'll wait for the new version. I just assumed you do the documentation updates along the way, since other 1.5 features are already documented.

It's a bit more complicated than that. Major features are documented as "preview" with a callout note indicating it's not in the stable version.
Then at a release, most if not all changes from the changelog are integrated in the documentation which can lead to refactoring several pieces of the documentation.
You can see that with all documentation Doc improvements & quarto-web issues.

[allefeld]

I made some experiments trying to wrap my head around how projects work (using 1.5.27), and wrote up my understanding. It would be great if you could comment whether I got it right. Maybe this can even be useful for future documentation – at least this is the kind of explanation I would like to see in it.

quarto render is equivalent to quarto render .

quarto render <dir> checks whether the given directory or any of its ancestors contain a file _quarto.yml. The first directory which does is taken as the project directory. It then renders all eligible files in the given directory and its subdirectories according to the project configuration in _quarto.yml. If no project directory is found, an error is raised.

quarto render <file> checks whether the directory of the given file or any of its ancestors contain a file _quarto.yml. The first directory which does is taken as the project directory. It then renders the given file according to the project configuration in _quarto.yml. If no project directory is found, the given file is treated as if its directory contained an empty _quarto.yml file.

Therefore, every rendering by Quarto takes place in the context of a (possibly virtual) project.

If _quarto.yml is empty, or contains no project key, or project contains no type key, the project type is default. In a default project, unless otherwise configured, each file is rendered separately (i.e. no cross-references and navigation / sidebar) and locally (i.e. the output is placed in the directory of the input).

In order for an extension to be available from an given file, it has to be installed in the directory of the file or in any of its ancestors up to the project directory. (If an extension is installed in a directory, the directory contains a subdirectory _extensions.)