(How) Can one exclude specific output files from being published?

[Gewerd-Strauss]

Description

Hello,

Assume I have a quarto website project, and within I have two profiles defined:

1. _quarto-default: This renders <root>/report/manuscript.qmd (among others)
2. _quarto-dev: This renders <root>/report/manuscript.qmd and <root>/report/manuscript_restruct.qmd (and all the files rendered by default-profile).

The default-profile is set up as default in the main _quarto.yml.

Naturally, I can now execute quarto render/quarto render report and only generate outputs for manuscript.qmd; or execute quarto render --profile dev/quarto render report --profile dev and also generate the restructured report.

Rendering would then create the outputs, and move them to the site directory (_site).
I should note that I always decouple rendering and publishing, meaning quarto publish is always called with flag --no-render; since various directories in this project take a lot longer to recompute for irrelevant reasons.

This means however, that if I execute

quarto render report/ --profile dev
quarto publish gh-pages --no-render

the outputs stemming from input-files exclusive to the dev-profile will also be published to the website.

Currently, the only possible solution is to remember to always re-render directories containing dev-related documents with the default profile before executing quarto publish. This works fine, and for worst-cases I can just purge the gh-pages branch manually afterwards.

However, I wondered if there exists another way of selectively suppressing the addition of specific documents to the published website, such that I don't have to re-render with default profile before publishing.

---

A few thoughts (which are most probably moot anyways because I don't know the internals of quarto)

• My first thought went to using a branch-specific .gitignore. But that
  1. doesn't seem to exist on the gh-branch when using quarto publish gh-pages
  2. would only be a hotfix since the ignored document would still be linked-to in navbars/sidebars on other documents, essentially giving a dead link to a non-existing target file.¹
• I am not sure what quarto publish ... --profile X actually achieves if combined with flag --no-render. I assume that --profile is only used when rendering before publishing, and thus would be ignored in combination with --no-render.
• One could render to two different output directories, (i.e. set output-dir in profile config to _site and _site-dev respectively), but that would also introduce issues:
  1. Outputs present in both profiles can become unsynced.
  2. I am not sure what quarto publish would actually do with outputs under a different output-dir like _site-dev. Would they also be pushed to gh-pages, or would the directory be ignored by quarto?

I am using quarto 1.5.56, on Windows 11 (v. 10.0.22631 Build 22631).

---

Thank you.
Sincerely,
~Gw

Footnotes

1. This is especially tricky if the document is placed on the navbar, since that element is generally present in all documents, unlike for documents listed in a sidebar under a single navbar-link. (Does that make sense, or am I bad at explaining what I mean?) ↩

[jimjam-slam]

Can you use the render project option? I'm not sure whether it supports excluding files (eg. with a negation syntyax), but it does support globbing, and I would imagine it'd work well with profiles (especially with different output-dirs specified)!

[Gewerd-Strauss]

Yea that is what I outlined. By using different profiles with different sets of render targets, you can render different sets of them - obviously.

But the "friction" I experience here stems from the fact that to my knowledge, quarto publish ... is indiscriminate towards the contents of the output-dir (here _site).

multiple output-dirs

As addressed above, I believe that solution to potentially raise more issues than it can resolve.

[mcanouil]

quarto publish is not really designed for advanced use. It does not much.
I don't think rendering several profiles in the exact same output directory is a smart move, especially if you intend to publish only a subset of the profiles.
I would recommend to use output-dir.
I believe, quarto publish will publish the profile specific output-dir and nothing else.

The "unsynced state" would only happen, if you don't render all profiles, but that's on you not Quarto because Quarto can't possibly know how to use your profiles.

[Gewerd-Strauss]

Sorry for the late answer, I've been busy.

I believe, quarto publish will publish the profile specific output-dir and nothing else.

So setting in profiles

_quarto-dev.yml:

project:
  output-dir: _site-dev

_quarto-present.yml:

project:
  output-dir: _site-present

_quarto-default.yml:

project:
  output-dir: _site

Then configuring the .gitignore as

/_site/
/_site-dev/
/_site-present/

and setting the profile default as default profile as

profile:
  default: default

And then exclusively calling quarto publish gh-pages --no-render should exclusively publish the contents of the default-profile?

[mcanouil]

Yes, it should. If not, then it might be a bug or a missing component of profiles.

[Gewerd-Strauss]

Seems to work so far on my side. Thank you for the help.