Light-weight use of Quarto extensions

[allefeld]

Description

I proposed this idea elsewhere, but it didn't receive a response, so I'm posting it as a separate feature request. It is related to the comments #2845 (reply in thread) and #2845 (reply in thread), but as far as I can see there is no equivalent existing feature request.

Background & Motivation

Quarto has no global configuration, which means that if a user has a certain preferred way to set things up (options, stylesheets, etc.), they have to copy over this configuration into each new project. Or they can create an extension for a custom format, which then has to be installed in each new project – but this basically does the same copying, albeit in a neater way. Consistent with no global configuration in general, extensions cannot be installed "into Quarto", only into a specific project. That is a design decision which will not be changed, based on the goal to have reproducibly rendered, self-contained projects.

The problem with that is that

there are many use-cases for Quarto which do not fit into the self-contained reproducible project mold.

For example, I use Quarto to write solutions for exercises in a module I teach. In my module, there are different contents for each week, and when the module repeats the next year there may be changes and therefore new versions. Each solution fits into a single qmd file – it's not a project and doesn't intend to be. Now I can put all my settings into the YAML metadata block, but that means I have to copy-and-paste for every qmd file I create. And maybe at some point I decide to change something, and then I have to go back to every file and change it there. I had hoped that custom formats would solve this, but then files get copied into each weekly / yearly folder, cluttering them up. And when I change the format, I have to run quarto update everywhere.

@go-bayes commented

@cscheid, respectfully, many users want to update LaTeX macros, along with bibliographies, functions, templates, and much else, across their projects. Duplication is not only inefficient, it leads to errors. And indeed, when we use PDF we can obtain this desired behaviour using header-includes: - \input{/home/.../macro-file-here.tex}. This is, at any rate, my use case. With @allefeld

I'd rather not have dozens of copies of my math-definitions.tex.

Defining an extension for a custom format makes things slightly better, because at least now the clutter goes into a subdirectory _extensions, but it doesn't change the fact that lots of files are duplicated (triplicated, …) and that a simple single-file document carries with it a whole bunch of ancillary files. It would be perfect if an extension could be installed "into Quarto" instead of a project, but that goes against the "no global configuration" design decision which will not be changed.

Proposal "Light-weight use of Quarto extensions"

Make "installing" an extension something that can be achieved by a YAML metadata key. E.g.

---
title: "Presentation"
subtitle: "LexConf 2022"
author: "Your Name"
date: today
use-extension: lexcorp/lexconf
format: lexconf-revealjs
---

The extension / custom format would be hosted on GitHub etc., if needed with version management. The contents are not downloaded into the directory of the document, but cached by Quarto.

This would satisfy both Quarto's focus on reproducibility and my and some other users' wish for reduced clutter and duplication (because the extension files are not put into the folder of the file). For full reproducibility, the user would specify a particular version, e.g. lexcorp/lexconf@v1.2, or they could just use the generic reference lexcorp/lexconf and always get the latest version. Both is already possible with installing an extension into a project, but clutter & duplication are avoided.

[allefeld]

Checking in: Is there any chance to get such a feature?
In case I tried to implement it myself: Is there a chance that it gets adopted (merged)?

[allefeld]

Okay, but that still doesn't explain what it does.

[mcanouil]

I don't understand what you want/expect here.
Everything in Quarto is a project (especially since 1.5). A single document is a project where the document defines the root and is a "default" project. Setting a _quarto.yml means you want your directory to be a project and the root of that project is where the _quarto.yml is, by default the project is "default", even if you did not set it explicitly.

[allefeld]

What I want/expect is that the documentation explains how the software works.

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.

The use case I explained above does not call for such an integration; I want each single file treated as a single file, just sharing some configuration, which I assumed should be done via custom formats, which then motivated my proposal for lightweight use of such custom formats.

After all this back and forth, I suspect a default project is one where there is no such integration – is that correct?

If yes, then it does indeed partially solve my problem – but I still think that my lightweight use proposal makes sense.

[baptiste]

Just curious, can you not make softlinks from a centralised location?

[mcanouil]

@baptiste When using text with hyperlinks, the text needs to explain what the link is about.
Currently, your comment is not at all accessible (even without disabilities, it's not meaningful as is), see https://www.w3.org/WAI/tips/writing/#make-link-text-meaningful.