quarto-dev / quarto

Quarto open-source scientific and technical publishing system
https://quarto.org
GNU Affero General Public License v3.0
280 stars 19 forks source link

Feature Request: create an "include" capability within _quarto.yml files, for large projects #404

Open donboyd5 opened 2 months ago

donboyd5 commented 2 months ago

It would be great if _quarto.yml files had an include capability so that they could include text from another file. As far as I can tell, they do not have this capability now. Here's an example of what I would like to be able to do (actual syntax could be different):

project:
  type: book

book:
  title: "Building some data"
  author: "Me"
  date: today
  chapters:
    - index.qmd
    - intro.qmd
    - part: "Part 1"

      {{< include part1/chapters.txt >}}

    - part: "Part 2"

      {{< include part2/chapters.txt >}}    

    - summary.qmd
    - references.qmd

My use case

I have a large project in which I am building data files that will be included in an R package. A quarto book is a great way to build these data in a modular way, documenting the data construction steps along the way. The book is not part of the released package but rather just controls and documents the process of building the data. It is information for people building the data on their own, from scratch.

There is a main data-raw folder for building the data. It has a _quarto.yml file that controls the process for building all of the data files that will be released. It also has an index.qmd file. The _quarto.yml file has many parts: each part is in its own subfolder and contains the many .qmd files (chapters) that build the data for that part and document the process of building those data.

Because building each chapter, and each part, is quite time consuming, and some of the parts are completely independent, it is helpful to treat each part like its own book that can be rendered separately. Thus each part has an index.qmd file so that when the part is rendered separately it can be viewed as a web page. And each part has a _quarto.yml file that controls the building of the data in that part and directs the output to a _part folder within the part folder. (The part's _quarto.yml file and index.qmd files are ignored when rendering the entire project using the main _quarto.yml file.) The chapters listed in the _quarto.html file for the part are the same as the chapters listed for the part in the main _quarto.yml file. The names for each chapter are complex and the order in which they are listed and rendered is important. It would be great if these chapter names (data_acs.qmd, data_cps.qmd, ..., data_soi.qmd, etc.) could be listed in another file, such as chapters.txt. This way they could be included in the part _quarto.yml file and the entire project _quarto.yml in exactly the same way, in exactly the same order, without having to copy from one _quarto.yml file to the other and without risk of error.

In my use case there would have to be a way for me to make the included filenames absolute relative to the main project folder, or fixed in some other way so that they would be referenced correctly regardless of whether they were included in the main _quarto.yml file or the part _quarto.yml file.

cderv commented 2 months ago

I don't think it could solve everything or 💯 works in your case, but did you try Shared metadata logic (https://quarto.org/docs/projects/quarto-projects.html#shared-metadata) with maybe metadata-files ?

The merging may not happen exactly as you expect though.

Your description reminds me of a project we did to include some books in another books : https://github.com/rstudio/r-manuals

In there we used only the results of the internal book rendering to include into a main book project, and we dynamically build the _quarto.yml based on books rendered. Meta rendering of books in books I would say.

Not a solution per-se but shows what could be done by programming around how quarto works.