% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/create-qmd.R
\name{create_qmd}
\alias{create_qmd}
\title{Create a new Quarto document from a template}
\usage{
create_qmd(
  filename = NULL,
  path = ".",
  yaml_data = NULL,
  overwrite = FALSE,
  use_purl = TRUE
)
}
\arguments{
\item{filename}{A string or \code{NULL}. Name of the generated \code{.qmd} file.
Must be supplied explicitly, e.g. \code{"analysis.qmd"}.}

\item{path}{A string. Path to the directory where the document will be
created. Defaults to \code{"."} (the current working directory).}

\item{yaml_data}{A string or \code{NULL}. Path to a YAML file containing
metadata to pre-populate the document header. If \code{NULL} (the default),
the template is copied as-is with placeholder prompts intact.}

\item{overwrite}{A logical. Whether to overwrite existing files. Defaults
to \code{FALSE}.}

\item{use_purl}{Logical. If \code{TRUE} (the default), creates a \verb{_quarto.yml}
file with a post-render hook and a \code{purl.R} script inside \verb{R/} that
extracts R code from the rendered document into a \code{.R} file. The target
document is resolved dynamically by scanning the project root for \code{.qmd}
files, so the same \code{purl.R} works regardless of the document name.}
}
\value{
Invisibly returns \code{path}.
}
\description{
Creates a new Quarto document in the specified directory, along with a
sample dataset and UW-Madison branded assets. Optionally pre-populates
the YAML header with user-supplied metadata.
}
\details{
\code{create_qmd()} performs the following steps:
\enumerate{
\item Validates that \code{path} exists.
\item Validates that \code{filename} is supplied.
\item Creates a \verb{data/} folder under \code{path} and copies \code{sample.csv} there.
\item Checks for \code{assets/styles.css} and \code{assets/header.html} - creates the
\verb{assets/} folder if needed and copies both from the package.
\item Copies the template \code{.qmd} to \code{path/filename}.
\item If \code{yaml_data} is provided, reads the YAML file and substitutes values
into the document header.
\item If \code{use_purl = TRUE}, writes a \verb{_quarto.yml} with a post-render hook
pointing to \code{R/purl.R}, and copies \code{purl.R} from the package templates
into \code{path/R/purl.R}.
}

Note: \code{filename} has no default value and must always be supplied
explicitly. Use \code{tempdir()} for temporary output during testing or
exploration.
}
\examples{
\donttest{
# Create a document in a temp directory
create_qmd(path = tempdir(), filename = "analysis.qmd")

# Create with a custom filename, without the purl hook
create_qmd(path = tempdir(), filename = "report.qmd",
            overwrite = TRUE, use_purl = FALSE)

# Create with pre-populated YAML
yaml_file <- tempfile(fileext = ".yml")
writeLines("author:\n  - name: 'Your Name'", yaml_file)
create_qmd(path = tempdir(), filename = "analysis.qmd",
            yaml_data = yaml_file, overwrite = TRUE)
}
}
