rmarkdown.Rmd

---
title: "Using here with rmarkdown"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using here with rmarkdown}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  error = !identical(Sys.getenv("IN_PKGDOWN"), "true")
)

project_path <- system.file("demo-project", package = "here")
```

The here package enables easy file referencing by using the top-level directory of a file project to easily build file paths.
This article demonstrates the case where the working directory is set to a subdirectory of the project root, for instance when rendering an R Markdown document that lives in a subdirectory.
See `vignette("here")` for a more general introduction.

## rmarkdown starts in a subdirectory

For demonstration, this article uses a data analysis project that lives in `` `r project_path` `` on my machine.
This is the *project root*.
The path will most likely be different on your machine, the here package helps deal with this situation.

The project has the following structure:

```{r echo = FALSE}
fs::dir_tree(project_path)
```

When `report.Rmd` is rendered, the working directory is internally set to `<project root>/analysis` by rmarkdown:

```{r eval = FALSE}
setwd(file.path(project_path, "analysis"))
```

```{r include = FALSE}
knitr::opts_knit$set(root.dir = file.path(project_path, "analysis"))
```

```{r}
getwd()
```

However, `penguins.csv` still lives in the `data/` subdirectory.
The report requires the `penguins.csv` file to work.

## here always uses project-relative paths

To render `report.Rmd`, you would have to ensure the path to `penguins.csv` is relative to the `analysis/` directory - i.e., `../data/penguins.csv`. The chunks would knit properly, but could not be run in the console since the working directory in the console *isn't* `analysis/`.

The here package circumvents this issue by always referring to the project root:

```{r}
here::i_am("analysis/report.Rmd")
```

All files accessed by `report.Rmd` should be referred to using `here()`:

```{r}
library(here)
here("data", "penguins.csv")
here("data/penguins.csv")
```

This ensures that `penguins.csv` can be read both when the report is knit and when the code is run interactively in the console.