-
Notifications
You must be signed in to change notification settings - Fork 383
Description
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 usedwebsite
projects, and it is relatively obvious what abook
ormanuscript
project is – but what is adefault
project? I've searched the documentation but didn't come up with anything. Hugo Example usesproject: 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.