Support the compilation to additional output-formats for subsections of a (website) project/ white- & black-listing specific render-targets per format.

[Gewerd-Strauss]

Description

As discussed in #8394 I will be outlining the reasoning for rendering subsections of a project to additional formats/excluding subsections of a project from specific formats¹.
In the context of this FR, the project-type is set to website. I am not building a book-project as there is significant overlap between both submission-documents. As a result, I would need to duplicate a lot of code and information across both projects - which just screams for issues.

I do think there might be some merit in implementing this for books as well, but I haven't given it enough thoughts so far. I will henceforth refer to website-projects unless explicitly stated otherwise.

---

For some background on why I am opening this, see this comment

---

The actual FR:
I don't claim that this is the best-end-of-discussion solution to this; I am certain that I lack some understanding of the greater picture.

In some (website) projects, you may require different sets of formats for different files. You might want to supply certain documents in html and pdf, but do not require all documents in all defined formats. Depending on the architecture - even with tools like freeze - rendering to multiple formats can introduce significant overhead for every file you compile to a format you don't need it in. In the outside-facing website/outputs one can disable linking to other formats for specific formats, yet they are still rendered.

I would suggest a means to completely block a format being rendered-to on a per-file level. Below is a (sensible to me) approach for implementing the user-facing configuration side of things.

The root/_quarto.yml-file allows setting render targets via the project.render-key that controls which documents are and are not rendered. It's responsible for most of the heavy lifting for configuring any project, so it seems a suitable place to configure this as well.
In principle, the format-key could be expanded by a sub-key à la format.<format>.render, which would essentially operate the same way:

format:
    html:
        toc: true
        <config stripped for clarity>
        render:
            - "*.qmd"
            - "*.md"
            - "!excludes/*.md"
            - "!excludes/*.qmd"
            - "!private/*/*.md"
            - "!private/*/*.qmd"
            - "!private/*.md"
            - "!private/*.qmd"
            - "!assets/*/*.md"
            - "!assets/*/*.qmd"
      pdf:
        toc: true
        <config stripped for clarity>
        render:
            - "report/manuscript.qmd"
            - "preproject/manuscript.qmd"
            - "!*.qmd"
            - "!*.md"

I think Metadata-merging would take normal precedence, meaning directory- & document-level format.render-values would either trump, or get merged to the project-definition. If root/documentation/methods/formats.yaml contains

format:
    pdf:
        render:
            - "pls.qmd"

Then after merging, we get in total:

format:
    html:
        toc: true
        <config stripped for clarity>
        render:
            - "*.qmd"
            - "*.md"
            - "!excludes/*.md"
            - "!excludes/*.qmd"
            - "!private/*/*.md"
            - "!private/*/*.qmd"
            - "!private/*.md"
            - "!private/*.qmd"
            - "!assets/*/*.md"
            - "!assets/*/*.qmd"
      pdf:
        toc: true
        <config stripped for clarity>
        render:
            - "report/manuscript.qmd"
            - "preproject/manuscript.qmd"
            - "documentation/methods/pls.qmd"
            - "!*.qmd"
            - "!*.md"
    

Upon execution, the file root/documentation/methods/pls.qmd should be rendered to html (blanket whitelist in global _quarto.yml) and pdf (local whitelist in directory). If configured, the pdf-file should be linked-to on the documents' html-representation. Accordingly, documents which are not rendered to multiple formats should not contain the links to said formats if they are not generated for that file.

I believe this solution is reasonably simple on the UI-level, but I don't pretend to understand the scope of the underlying codebase itself.

Thank you for considering this FR.

Sincerely,
~Gw

---

P.S.: I am happy to elaborate if I failed to bring my points across or missed something that is not clear.

Footnotes

1. This is kind of the same, just inversed. ↩

[Gewerd-Strauss]

Background:
I am currently finalising the planning for my upcoming programming-related thesis project for my B.Sc.. For this Thesis, I must submit two documents:

1. a manuscript of the thesis itself. Must be printable to physical paper - which realistically requires either pdf or docx as format.
2. a manuscript of a preliminary project report. See 1.
3. Alongside this, documentation on methods employed (and written code/general rationale/…) must be provided. These must not be rendered to pdf. And while documenting source-code is possible in pdf or docx ,it is also painful. There are several similar reasons which make a blanket-pdf-render undesirable.

The thesis is set in the general area of multivariate data-analysis & computations are expected to take a somewhat significant amount of time (even after considering common countermeasures).

Time/Performance-Loss due to unwanted renders:
Additionally, there are certain pre- and post-rendering steps which must scale with the number documents rendered - meaning every unnecessary pdf-document I generate increases execution time for quarto render. And obviously, the rendering of these documents themselves takes time as well.

Time/Performance-Loss due to format-specific computations & limitations to codechunk-caching across formats:
Code often has to be re-executed for each output-format (at least in my experience with R/rmarkdown/bookdown/quarto). Well it doesn't have to be strictly speaking, but you often risk introducing a variety of issues when keeping data across formats - and my experience fully supports this warning. Doing stuff 2+ times takes time, sometimes even more-so. If you have a 20-something documents, this scales very quickly. Codechunk-caching can reduce this time somewhat, but it also introduces a whole other set of issues. Managing these situations reliably is often neither trivial nor "simple and reliable".

vsc-maintenance:
And finally, on a more minor scale, I would also prefer not to throw a bunch of additional (pdf)-documents under source-control in the gh-pages-branch. Obviously one could always checkout the gh-pages-branch and update a branch-only .gitignore prior to executing quarto publish …, but I find this solution unwieldy and error-prone. You can go a long way with some well-defined needles, however I still believe there to be too much potential for committing unwanted data.

And while getting rid of an unintentionally introduced file is certainly doable in git, this just piles up on the amount of corrective-maintenance one would have to do in order to keep their repo clean. If users could "whitelist" or "blacklist" output-formats for specific directories, this risk would be significantly reduced (and as a nice side-effect, we wouldn't need to rely on git to do so.)

---

This comment can be marked off-topic; it's an excerpt of the original state of the discussion which I cut out for clarity.

[petrbouchal]

I wonder if this is a (reverse?) variant of #7101