quarto-dev / quarto-dev/quarto

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

Open
#404 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
645
Forks
62
Avg merge
17h 42m
Merged PRs (30d)
13

Description

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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the main and per-part _quarto.yml files described in the issue, along with the shared chapters.txt files and their index.qmd entry points. Define how the included chapter lists are resolved in both project contexts, including paths relative to the main project. Done means the same ordered list can be reused without copying between configuration files.

Written by the indexing model from the issue text.

Assessment

Tech stack
yaml
Domain
build-system
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.