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

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.