Best Practices to Re-Use Elements of a Parent project in Sub-Projects (Proposal, Project Plan, Manuscript, Website)

[jorishijmans]

For a research project, I try to re-use elements of a parent project in a sub-projects (manuscripts, proposal, project plan, manuscript, and website) by:

1. Centralising resource repositories
2. Centralising metadata for project-level profile groups

• _quarto.yml in the root folder
• _metadata.yml in sub-folder if relevant. (Only for posts in website project, and presentations)

3. Setting resource-paths in document metadata
4. Troubleshooting a YAMLError (see below)
5. Requesting your feedback to effectively re-use elements of a parent project in multiple sub-projects

1. Centralising resource repositories

I have organised my project directory to centralise shared resources. Here is an abbreviated structure for clarity:

- xxx-name-research-project (root)
   - _quarto.yml (repo info, contact info)
  - D02-submit-proposal (folder)
      - D02-proposal-name.qmd (includes 
  - D03-submit-manuscript
  - D03-manuscript.qmd (manuscript project)
  - D04-presentations
     - _metadata-affiliationA-name.yml 
     - _metadata-affiliationB-name.yml 
   - sec-results 
     - intro-graph.qmd
    - sec-introduction
      - intro-graph.qmd 
  - analyse-data (folder)
    -  thematic-analysis-case-id
      -  06-outputs
         - tables
           - _D03-manuscript-sec-results-tbl-name.qmd (markdown table) 
  - collect-data (folder)
  - images (folder)
  - notes (folder
   - contructs-concepts (sub-folder)
      - concept-name.qmd 
    - theories-models (sub-folder)
   - website (folder)
      - _metadata.yml
      - docs (folder)
      - index.qmd
      - etc.

2. Centralising metadata for project-level profile groups

I have centralised metadata files to streamline configuration and ensure consistency across different deliverables.

_quarto.yml

# profile:
#  group: 
#  - [receive-feedback-content, format-affiliation-a, affiliation-b, for-participants, for-peers, guide] 
#  default: format-affiliation-a
# execute-dir: project

# metadata-files:
#  - _receive_feedback_content.yml
# - etc.

_metadata.yml (in root/presentations)

date: today
format:
 revealjs: 
  menu: false
  progress: false
  search: false
  slide-number: true 

3. Setting resource-paths in document metadata

I set resource paths in my document metadata to enable inclusion of shared resources outside the sub-project, which is a sub(sub)-directory of the parent-project containing _quarto.yml.

---
title: title
etc.
resource-path:   
- "xxx-name-research-project/notes/"
- "xxx-name-research-project/images/"
- "xxx-name-research-project/D03-submit-manuscript/"
- "xxx-name-research-project/analyse-data/"
---

4. Troubleshooting YAMLError

The following error appears when I try to render a document in a sub-directory/project (i.e., D03-manuscript):

ERROR: YAMLError: C:\Users\joris\Practice\Researcher\xxx-research-project\D03-submit-manuscript\D03-manuscript.qmd:
can not read a block mapping entry; a multiline key may not be an implicit key at line 107, column 11:
    key-points:
              ^

Stack trace:
can not read a block mapping entry; a multiline key may not be an implicit key at line 107, column 11:
    key-points:
              ^

5. Request for Feedback

I am looking for suggestions on how to effectively re-use elements of a parent project in multiple sub-projects such as proposals, project plans, manuscripts, and websites. Specifically, I would appreciate feedback on:

1. Improving my directory structure
2. Managing and centralising metadata
3. Setting and troubleshooting resource paths

Any other tips you think may help are welcome too!