Playbook

Quarto Graft separates concerns: contributors work in isolated graft branches, while the trunk maintainer orchestrates the unified site.

This page explains the roles and workflows in a quarto-graft project.

Roles

Content Creator (Graft Author)

Responsibility: Create and maintain content in an isolated graft branch.

Workflow: 1. Request a graft from the trunk maintainer (or create one yourself if you have access) 2. Check out your graft branch: git checkout graft/my-graft 3. Edit content in docs/ 4. Preview locally: quarto preview docs 5. Commit and push: git add . && git commit -m "Update content" && git push

Key Points: - You never merge back to main — the trunk pulls your rendered content - Your graft has its own dependencies (Python packages, R libraries, etc.) - Execute notebooks before committing (trunk doesn’t run code) - Preview your graft standalone or wait for trunk maintainer to build the full site

Example Session:

git checkout graft/my-tutorial
vim docs/chapter1.qmd
quarto preview docs           # Preview your graft
git add docs/chapter1.qmd
git commit -m "Add chapter 1"
git push

Trunk Maintainer

Responsibility: Manage the overall site structure, collars, builds, and graft lifecycle.

Owns: - The main branch and _quarto.yaml (collar definitions) - grafts.yaml configuration - Build and publish pipeline - Graft lifecycle management

Common Tasks:

Create a new graft for a contributor:

quarto-graft graft create contributor-name --collar articles

Build all grafts and update navigation:

quarto-graft trunk build

Check the status dashboard:

quarto-graft status

List and manage grafts:

quarto-graft graft list
quarto-graft graft destroy old-graft

Manage the render cache:

quarto-graft trunk cache update    # after quarto render
quarto-graft trunk cache status    # inspect cached pages
quarto-graft trunk cache clear     # reset cache

Define new collars in _quarto.yaml:

sidebar:
  contents:
    - section: New Section
      contents:
        - _GRAFT_COLLAR: new-collar

Template Author

Responsibility: Design and contribute reusable templates for trunks and grafts.

Template Types:

Trunk Templates: Define site structure, styling, collars - Located in src/quarto_graft/trunk-templates/ - Include _quarto.yaml, docs/, grafts.yaml - Use Jinja2 for customization

Graft Templates: Provide starter content for different use cases - Located in src/quarto_graft/graft-templates/ - Examples: python-notebook, r-analysis, documentation - Include language-specific dependencies

How to Contribute: 1. Create a template directory with required structure 2. Test it: quarto-graft trunk init "Test Project" --template ./my-template 3. Submit PR with template in appropriate directory 4. Maintainers review and merge

Template Best Practices: - Include clear README with template purpose - Provide working example content - Document required dependencies - Use Jinja2 variables for customization ({ project_name }, etc.)

Workflows

Adding a New Collar

Trunk maintainer edits _quarto.yaml:

sidebar:
  contents:
    - section: Case Studies
      contents:
        - _GRAFT_COLLAR: case-studies

Authors can now create grafts that attach to case-studies:

quarto-graft graft create my-case-study --collar case-studies

Retiring a Graft

Content creator archives their work (optional)
Trunk maintainer destroys the graft:
```
quarto-graft graft destroy old-graft
```
Rebuild to update navigation:
```
quarto-graft trunk build
```

Pre-rendering a Graft (Archive)

Graft authors can pre-render their content to speed up trunk builds. This is useful for grafts with expensive computations:

From the graft branch, archive the content:

git checkout graft/my-analysis
quarto-graft graft archive

Commit and push the pre-rendered output:

git add _prerendered/ .graft-prerender.json
git commit -m "Pre-render graft"
git push

Trunk builds will automatically use the pre-rendered content (no re-rendering needed).

To revert to source-based rendering:

quarto-graft graft restore

Custom Organization Templates

Organizations can create standard templates:

# Organization's template repo
my-org-templates/
├── trunk-templates/
│   └── corporate/
│       ├── _quarto.yaml     # Corporate branding
│       ├── docs/
│       └── grafts.yaml
└── graft-templates/
    ├── research-paper/
    └── product-docs/

# Use organizational templates
quarto-graft trunk init "My Project" --template my-org-templates/trunk-templates/corporate
quarto-graft graft create study --template my-org-templates/graft-templates/research-paper