Shouldn't {{< include >}} follow the project's execute-dir option?

[edalfon]

Hi,

We use includes to re-use content across documents in a Quarto website project.

In this project, we set the option execute-dir: project to keep the working directory for computations pinned to the root directory of the project. That way, for example, all documents can refer to ./data/fancy_data, regardless of which subfolder they are placed in. For us this is important because we organize the content of the project in a bunch of subfolders that can go nested to different depth. Without the execute-dir: project the project would simply be much harder to mantain and keep track of the paths we should use in each document.

We expected {{< include >}} to follow the same project's execute-dir option, but it doesn't seem so. Instead, it always resolves to the same folder of the file you are including content in. So if you are in a subfolder and whant to include some content in the root of the project, you cannot do this {{< include _codebit.qmd>}}, but you have to do something like this {{< include ../../../_codebit.qmd>}}. And the ../../... part would depend on where the document lives and if you decide to reorganize the structure of the documents, you would need to update that as well. So, it is a bit of a mess.

We couldn't find a way around this or any other option similar to execute-dir, but for the whole working directory of the project and not only for computations.

Wouldn't it be better to have the includes directive to follow the execute-dir option?, is there currently any way to do it?

[mcanouil]

We expected {{< include >}} to follow the same project's execute-dir option

Why did you expect this? execute options are for computation only, it has nothing to do with all files/resources are located by their path. Files/resources are relatives to the document using them.

Wouldn't it be better to have the includes directive to follow the execute-dir option?

This would require all Quarto files to have unique names.
I do not believe what you are asking should be implemented at all, because contrary to what you might think, it would be a nightmare to navigate through the files if when looking at the include shortcode or any options that include resources, you have to think twice to find out to what it is relative to.
Also, this would lead to inconsistent behaviour, if options use path relative to the document, while include use path relative to project root, etc.

[edalfon]

In Quarto projects, an include path that begins with a leading slash will be interpreted as project relative, meaning that you should be able to use an include such as:

{{< include /_codebit.qmd >}}

to include from the project root no matter the subdirectory of the file itself.

HTH!

Awesome!, thank you very much. Will try that ... (we didn't try that one, as we thought that would just point to the root of the drive/system, sort of like c: in windows)

[mcanouil]

@dragonstyle Maybe this "trick" should be mentioned/highlighted in the documentation.

https://quarto.org/docs/authoring/includes.html

[dragonstyle]

Yeah I was thinking it might make sense to document more generally where 'project paths' can be used (they work in many other places of Quarto as well). I can make a note in the include docs as well.

[davidpomerenke]

In Quarto projects, an include path that begins with a leading slash will be interpreted as project relative, meaning that you should be able to use an include such as:

{{< include /_codebit.qmd >}}

to include from the project root no matter the subdirectory of the file itself.

HTH!

This is quite handy, but it does not seem to work for embeds. Maybe it makes sense to implement the same mechanism there?

My use case is that I would like to use nested includes (which works!), some of which also have embeds (depending on how I specify the path, these work either only when rendering the composite document, or only when rendering the (sub-)include). My workaround for rendering at both levels is using absolute paths, which is totally okay for my project, but maybe not for larger collaborative projects. It is of course not a given that it should be possible to render both the (sub-)include and the composite document, but I find it quite handy to get faster renders for the parts that I am working on.

[mcanouil]

@davidpomerenke I opened a dedicated issue #6147