Your Metadata, Your Way

Introduction

The settings() function is your gateway to effortless metadata management in froggeR. Whether you’re a researcher publishing papers, a data analyst sharing reports, or anyone who creates Quarto documents, settings() helps you maintain consistent author information across all your projects.

What Metadata Does froggeR Store?

froggeR manages six metadata fields:

Name (required): Your full name as it appears in publications
Email (required): Your contact email address
ORCID (optional): Your ORCID identifier (e.g., 0000-0001-2345-6789)
URL (optional): Your personal website or profile URL
GitHub (optional): Your GitHub username
Affiliations (optional): Your institution, department, or organization

The Interactive Workflow

Let’s walk through how settings() works with a real-world example of Dr. Rachel Kim, a neuroscience researcher.

First-Time Setup

When Rachel runs settings() for the first time:

> froggeR::settings()

froggeR Metadata Status
✖ No project-level metadata
✖ No global metadata

What would you like to do?

1: Create or update metadata
2: View current metadata
3: Exit

Selection: 1

froggeR guides her through creating metadata:

Enter your metadata (press Enter to skip optional fields):

Full name
  Your full name as it appears in publications
  : Dr. Rachel Kim

Email address
  Contact email
  : rachel.kim@neuroscience.edu

ORCID
  Optional (e.g., 0000-0001-2345-6789)
  : 0000-0002-1234-5678

Website or profile URL
  Optional (e.g., https://yoursite.com)
  : https://rachelkim.science

GitHub username
  Optional (e.g., octocat)
  : rkim-neuro

Affiliations
  Optional (e.g., Institution, Department)
  : University of Washington, Department of Neuroscience

After entering all fields, froggeR shows a preview:

Your metadata preview:

---
name: Dr. Rachel Kim
email: rachel.kim@neuroscience.edu
orcid: 0000-0002-1234-5678
url: https://rachelkim.science
github: rkim-neuro
affiliations: University of Washington, Department of Neuroscience
---

Rachel chooses to save globally so she can reuse it in all future projects:

Where would you like to save this metadata?

1: Save to this project only
2: Save globally (reuse in all future projects)
3: Save to both locations
4: Cancel (discard changes)

Selection: 2

✔ Saved to global: /home/rachel/.config/froggeR/_variables.yml

✔ froggeR metadata configured successfully!

ℹ Your metadata will automatically be used in future froggeR projects.

Input Validation

froggeR validates your input and provides helpful error messages:

Email validation:

Email address
  Contact email
  : rachel.kim

  Email must be in format: user@example.com

ORCID validation:

ORCID
  Optional (e.g., 0000-0001-2345-6789)
  : 1234-5678

  ORCID must be in format: 0000-0000-0000-0000

URL validation:

Website or profile URL
  Optional (e.g., https://yoursite.com)
  : rachelkim.science

  URL must start with http:// or https://

GitHub username validation:

GitHub username
  Optional (e.g., octocat)
  : -rkim-

  GitHub username: alphanumeric and hyphens only (no leading/trailing hyphens, max 39 chars)

Updating Existing Metadata

When metadata exists, froggeR asks whether to update or start fresh:

Metadata already exists. What would you like to do?

1: Update existing metadata
2: Start fresh

Selection: 1

When updating, current values appear in brackets. You can press Enter to keep them or type new values:

Full name
  Your full name as it appears in publications
  [Dr. Rachel Kim]:

# Press Enter to keep, or type new value

Email address
  Contact email
  [rachel.kim@neuroscience.edu]: rachel.kim@stanford.edu

# Type to change

Project-Specific Overrides

Sometimes you need different metadata for a specific project:

Selection: 2

# Choose "Start fresh" to override your global settings for this project

Now this project has custom metadata while your global settings remain unchanged.

Where Is Metadata Stored?

froggeR stores metadata in two locations:

Project-level: _variables.yml in your project directory
- Used by current project only
- Takes precedence over global settings
- Committed to version control
Global: Platform-specific configuration directory
- Linux/macOS: ~/.config/froggeR/_variables.yml
- Windows: C:\Users\<username>\AppData\Local\froggeR/_variables.yml
- Used as default for all new projects

Next Steps

Now that you understand metadata management with settings(), explore:

Building Your Brand Identity - Learn about brand_settings()
Set Once, Use Everywhere - Understand the global configuration philosophy
From Zero to Project in Seconds - See how quarto_project() uses your settings

Summary

The settings() function provides an interactive way to manage your author metadata:

Validates input with helpful error messages
Stores globally for reuse across all projects
Allows project-specific overrides when needed
Shows clear previews before saving
Provides flexible save options to match your workflow

By configuring metadata once with settings(), you eliminate repetitive data entry and ensure consistency across all your Quarto projects.