Catalog a new webrarian project

Creates a new webrarian collection, with a _webrarian.yml and, for some templates, a starting directory structure. The project name is the directory's name. Change it with settings_set(path, "project.name" = ...). When run on an existing directory containing R files, it detects package dependencies and file patterns to include.

Usage

catalog(
  path = ".",
  template = c("minimal", "data-analysis", "package"),
  packages = NULL,
  detect = TRUE
)

Arguments

path

Path where the project should be created. Use "." for the current directory (default), or provide a directory name. If the directory exists and contains R files, package dependencies are auto-detected.

template

The project template, one of these:

• "minimal": Basic configuration only

• "data-analysis": Includes common data analysis packages

• "package": For bundling an existing R package

packages

Character vector of prebuilt WebAssembly package names to add to the template's own (see acquire_package()).

detect

If TRUE (default), scans existing directories for R files and auto-detects package dependencies and file patterns. Set to FALSE for a clean configuration without scanning.

Value

Invisibly returns the project path.

Details

Dependency detection

When detect = TRUE and the directory already exists, webrarian takes two steps:

1. Scans for package dependencies using renv::dependencies():

   • library(pkg) and require(pkg) calls

   • pkg::function() namespace calls

   • Package declarations in Rmd/qmd YAML headers

2. Detects file patterns to include:

   • R scripts (*.R, *.Rmd, *.qmd)

   • Common directories (data/, scripts/, R/)

   • Data files (*.csv, *.rds, etc.)

Dependency detection requires the renv package. Install it with install.packages("renv") for full functionality.

Examples

# Create a collection in a new directory
collection <- file.path(tempdir(), "my-webr-app")
catalog(collection)
#> ✔ Created directory /tmp/RtmpQU25pJ/my-webr-app
#> ✔ Created _webrarian.yml
#> ✔ Added "_site/" and ".webrarian/" to .gitignore
#> ✔ Cataloged webrarian collection: "my-webr-app"
#> 
#> Next steps:
#>   Move into the collection: `setwd("/tmp/RtmpQU25pJ/my-webr-app")`
#>   Acquire packages: `webrarian::acquire_package("dplyr")`
#>   Acquire files: `webrarian::acquire_file("data/")`
#>   Bind: `webrarian::bind()`
#>   Reading room: `webrarian::reading_room()`
#> ℹ Or pass `path` to each call, e.g. `webrarian::bind(path =
#>   "/tmp/RtmpQU25pJ/my-webr-app")`
is_collection(collection)
#> /tmp/RtmpQU25pJ/my-webr-app/_webrarian.yml 
#>                                       TRUE 

# Start from a template, with packages registered up front
analysis <- file.path(tempdir(), "my-analysis")
catalog(
  analysis,
  packages = c("dplyr", "ggplot2"),
  template = "data-analysis"
)
#> ✔ Created directory /tmp/RtmpQU25pJ/my-analysis
#> ✔ Created _webrarian.yml
#> ✔ Created scripts/init.R
#> ✔ Added "_site/" and ".webrarian/" to .gitignore
#> ✔ Cataloged webrarian collection: "my-analysis"
#> 
#> Next steps:
#>   Move into the collection: `setwd("/tmp/RtmpQU25pJ/my-analysis")`
#>   Acquire packages: `webrarian::acquire_package("dplyr")`
#>   Acquire files: `webrarian::acquire_file("data/")`
#>   Bind: `webrarian::bind()`
#>   Reading room: `webrarian::reading_room()`
#> ℹ Or pass `path` to each call, e.g. `webrarian::bind(path =
#>   "/tmp/RtmpQU25pJ/my-analysis")`
collection_packages(analysis)
#> 
#> ── Webrarian Packages ──────────────────────────────────────────────────────────
#> 
#> ── prebuilt ──
#> 
#> • dplyr
#> • ggplot2
#> • tidyr
#> • readr

unlink(c(collection, analysis), recursive = TRUE)

# An existing folder of R scripts: its packages and files are detected
scripts <- file.path(tempdir(), "my-scripts")
dir.create(scripts)
writeLines("library(dplyr)\nsummary(1:10)", file.path(scripts, "analysis.R"))
catalog(scripts)
#> ℹ Detected 1 package from R files: "dplyr"
#> ℹ Detected file patterns: "*.R"
#> ✔ Created _webrarian.yml
#> ✔ Added "_site/" and ".webrarian/" to .gitignore
#> ✔ Cataloged webrarian collection: "my-scripts"
#> 
#> Next steps:
#>   Move into the collection: `setwd("/tmp/RtmpQU25pJ/my-scripts")`
#>   Acquire packages: `webrarian::acquire_package("dplyr")`
#>   Acquire files: `webrarian::acquire_file("data/")`
#>   Bind: `webrarian::bind()`
#>   Reading room: `webrarian::reading_room()`
#> ℹ Or pass `path` to each call, e.g. `webrarian::bind(path =
#>   "/tmp/RtmpQU25pJ/my-scripts")`
unlink(scripts, recursive = TRUE)