Include static site resources at a custom path

[gadenbuie]

I'm in the process of migrating a blog from Hugo (blogdown) to Quarto and have stumbled on a small problem. With Hugo, a special folder named static is used to store files that become available on the website at the website root. A file at static/blog/cat.png becomes {site_url}/blog/cat.png on the final site.

Is it possible to map project resources from their relative project path to a new path in the rendered site? I'm envisioning something like

project:
  type: website
  resources:
    - "static/blog:blog"

but AFAICT no such syntax exists for Quarto. (More realistically, I'd probably do "static:/" to mean copy files in static/ into the site root.)

One alternative I've considered is to move everything out of static into the right place within the website repo structure. This will work, but it will also require a decent bit of metadata surgery to ensure that static files that Quarto shouldn't attempt to render are skipped. For example, it was helpful to have static/ as a place to put files that I knew wouldn't be touched by the site generator and would appear in my site as-is.

Also, I have a lot of small top-level files that I'd rather not have cluttering the repo. Storing them in static/ certainly added some overhead complexity but made it a lot easier to locate the post content quickly.

Although... after writing out the above, the alternative I'll likely use for now is a post-render script to copy static/ into _site.

[gadenbuie]

Okay, so post-render works pretty well for me. Here's a super minimal version that moves everything under static/ into the rendered _site/ folder.

project:
  type: website
  post-render:
    - "cp -rnv static/. _site/"

The -rnv means to copy -r recursively (include subdirectories), without overwriting existing files (-n stands for no clobber), and showing every action verbosely (-v). It's important to have the . in static/. to ensure that files and directories contained within static/ are copied rather than copying the files to a _site/static/ directory.

With the -n flag I think this is fairly safe but likely overly cautious. If a file is created by your dynamic content and happens to have the same path as a file in your static/ directory, the rendered file will win and the static file won't be copied.

[gadenbuie]

FYI, the -n flag causes issues (at least on macOS) with Quarto 1.4. cp -n causes cp to exit with status code 1 if a file isn't copied, which Quarto now interprets as an error, causing quarto preview to halt. That's probably the right thing for quarto to do, so any of us using this post-render script may need to remove the -n flag or use an alternative command (like rsync).

see: #7710

[maptv]

I tried to use the resources project option: https://quarto.org/docs/reference/projects/core.html#:~:text=resources,to%20output%20directory
and it worked for me. The post-render script method also works well.

[gadenbuie]

Yes, project: resources existed when I wrote this post. IIRC, the problem is that the final location of the resources can't be customized. So ./static/foo is copied into _site/static/foo, but you can't take ./static/foo and move it into ./_site/foo.