How should extension versioning work inside a git project (format-resources)?

[fuhrmanator]

Description

Let's say I'm using the quarto-monash/report extension, which is version 2.0.0 and it has format-resources: for various icons that are used in the LaTeX via title.tex.

I'm using the extension in my own project, which is under version control with git. When I install that extension to make reports, those resources are copied to the project's root directory when I do quarto render ..., and they remain there afterwards. Most of the other LaTeX-related build files are erased, however.

So, my IDE (VSCode) sees those "new" format-resources: icon files as files to add (possibly) to my git repository. I'm unsure what to do, so I put them in .gitignore, since by the principle of information hiding (encapsulation), they're just a detail of the extension. Furthermore, they already got added to the repo when I installed the extension to my project and got an _extension subdirectory. Otherwise, I'd have to re-install my extension each time I re-cloned my report project, right?

Later, I assume that the report format (extension) could evolve, say to version 2.0.1 (I assume I can update it in my project with quarto). Maybe in 2.0.1 the format-resource icons change? I assume the quarto command will take care of updating the _extension directory (and maybe I have to check-in the changes to git).

But still, those un-versioned format-resources hanging out in the project's main directory become troublesome.
It's really not a big deal, but is this how it's supposed to work? Could they be cleaned up after the quarto render (or preview) the way the LaTeX temporary files are? I realize there are many ways extensions can work, and maybe it doesn't make sense to clean up the format-resources.

Maybe the report extension can use those icons without making them format-resources (it's a bug in the extension)? Again, my main .qmd file doesn't see them (they're loaded in the title.tex partial).

[mcanouil]

The behaviour of format-resources is the intended one and is documented: https://quarto.org/docs/extensions/formats.html#format-resources

[fuhrmanator]

Looking at the documentation, I see:

You can usually include other files and resources within a format extension by placing those files within the extension directory and using relative paths to reference them in your _extension.yml metadata file. These relative paths will be properly handled as your extension’s metadata is merged with the rendered document metadata.

Next, I emphasize the word logo, since that is what's happening in my case.

If there are resources that you need to have copied to the input directory as a part of rendering the document (for example, a bst file for LaTeX bibliographies or a logo or other file referenced from a LaTeX template), you can provide format-resources, which is a list of file paths1.

Footnote 1 explains the complexity of LaTeX PDF builds, files need to be "discoverable", etc.

Now, recalling my last point:

Maybe the report extension can use those icons without making them format-resources (it's a bug in the extension)?

So, I tried the following. In the title.tex partial I changed it to use relative links to the images (logos) within the extension directory, e.g., \includegraphics{_extensions/quarto-monash/report/icon.png} and it works without needing to make a copy of the images with format-resources.

This resolves the problem with doubly-versioned files in my case.

[mcanouil]

Yes, you can for some things use paths to content of the extension.
Since LaTeX is not homogeneous and consistent, you basically have to try which file can be anywhere and which needs to be in the root.

Note that setting the path to within an extension can appear not very reliable.
If you intend to share, be sure to check how it goes when installing the extension.

[fuhrmanator]

If you intend to share, be sure to check how it goes when installing the extension.

Excellent point! Indeed, the path of files of an extension in its distribution site (i.e., the GitHub repo where it's released) and where it has been installed (project using the extension) is NOT the same. The former is something like _extensions/report/Logo.png and the latter includes the GitHub username (of the distribution of the extension), e.g., _extensions/quarto-monash/report/Logo.png.

I asked Copilot for some LaTeX-fu (hacky solution) to help out, and here's what I used finally for my own extension's title.tex partial (distributed on my fuhrmanator) account:

\usepackage{ifthen}
% Define possible paths
% Quarto extension after it's installed
\def\logopathA{_extensions/fuhrmanator/report/Logo.png}
% Quarto extension on its distribution site (before it's installed, there's no github username in the path)
\def\logopathB{_extensions/report/Logo.png}

% Macro to check file existence and include graphic (or nothing)
\newcommand{\includegraphicspath}[2][]{%
  \IfFileExists{#2}{\includegraphics[#1]{#2}}{}%
}

%% further down in title.tex where the logo is used

    % display the logo that exists (one or the other)
    \includegraphicspath[width=6cm]{\logopathA}
    \includegraphicspath[width=6cm]{\logopathB}

I tested it in both the distribution and usage projects, and it appears to work.