How to produce a file to the _files directory within a shortcode?

[rchaput]

Description

Hi,

I'm developing an extension that produces figures from shortcodes that I want to integrate in the document. I can return a pandoc.Image from my shortcode, but I'm wondering where (on the filesystem) I should produce my figure to make sure it is included in the document's "resources"?

I assume the _files directory would be the best place, but I'm not sure how to access it from the Quarto API? I could probably hack some way to list all files in the current working directory and find a directory that ends with _files, but that really does not seem a sound idea...

For reference, my shortcode function currently looks like this:

function shortcode(args, kwargs, meta)
    local output_filepath = "test.png" -- HERE: where to place this file?
    pandoc.pipe("some_command_to_generate_a_figure", { "--output", output_filepath }, "")

    local caption = ""
    return pandoc.Image(caption, output_filepath, nil, nil)
end

I've read about HTML dependencies, but I'm not sure this is what I'm looking for.
First, my shortcode is not limited to HTML documents. And it seems more related to JS/CSS files.
I remember that in Rmarkdown, I could use the engine to get a path to the resources' folder, and produce my file there.

What's the best practice when generating an external figure in Quarto?

[mcanouil]

Why not base64 encode the image?

[rchaput]

I guess that would work; however, there are 2 performance issues:

• it would be harder for me to implement some sort of caching mechanism when rendering the document (i.e., to avoid re-generating the same image twice);
• for HTML output, because the image would be embedded within the document and not served as an external file, the browser could not cache it.

These are not blocking problems, so I'll try to use base64 for now, thanks!

[mcanouil]

Note that there is no "best practices" so you can do whatever you want.

Quarto LUA API provides a base64 function if you go that road.

QUARTO_PROJECT_OUTPUT_DIR should be available in LUA filters.

Alternatively, you could also generate the content in a directory inside the project, Quarto should automatically add it to the resources if it is used.
If not, you can also add it explicitly to project resources.

[rchaput]

QUARTO_PROJECT_OUTPUT_DIR seems promising, thanks again!

IMHO, it's a shame that there is no "best practice", especially since Quarto has some specific folders (_files, .quarto). That would make extensions/shortcodes feel a bit more "integrated" to the user.

[mcanouil]

I mean there is no "best practice" guide because there are internal changes and future evolution planned which are designed to improve things.
Making a "best practice guide" for extension would only make things more complicated rather than help.

• https://github.com/quarto-dev/quarto-cli/issues?q=state%3Aopen%20label%3Aextensions

This being said, a developer guide is planned but it takes time.

[cscheid]

I've read about HTML dependencies, but I'm not sure this is what I'm looking for.

I think it is what you're looking for. Dependencies are the mechanisms Quarto uses to let you communicate resources in disk. If you explicitly add one such dependency, then Quarto will ensure the file is copied to _site (or whatever the output directory that is configured.)