---
title: "Introduction to vitae"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to vitae}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The vitae package makes creating and maintaining a Résumé or CV with R Markdown simple. It provides a collection of LaTeX templates, with helpful functions to add content to the documents. These functions allow you to dynamically include CV entries from any data source, which is particularly useful when this data is obtained/prepared by other R packages. Some examples of what this allows you to do includes:

- Automatically get your work experience from the web
- List the R packages you have contributed to
- Filter CV entries by keywords relevant to the current job
- Include your academic publications

## Creating a CV

If using RStudio, a new CV document can be easily produced from one of the templates provided in the package. This using the RStudio R Markdown template selector, accessible via `File` > `New File` > `R Markdown...`, and lastly `From Template`. This will show a list of R Markdown templates provided by all installed packages, and you should be able to find some templates from the vitae package to use.

If not using RStudio, you can create a new `*.Rmd` document and use an output format that is provided by the package. A list of output formats provided by the package can be found on the package website: https://pkg.mitchelloharawild.com/vitae/#templates. Examples of a YAML header that use one of these output formats is shown below.

Like other R Markdown documents, the file is split into two sections: the YAML header, and the main body.

### The YAML header

The YAML header contains general entries that are common across many templates, such as your name, address and social media profiles. This is also where the output format (the CV template used) is specified, along with any options that the template supports. An example of what this header may look like is shown below:

`r htmltools::pre(htmltools::code(paste0(readLines("sample.txt")[1:11],collapse = "\n")))`

You can also see that the output is set to `vitae::awesomecv`, which indicates that this CV uses the [Awesome CV](https://github.com/posquit0/Awesome-CV) template. Some of the templates allow for the choosing of a theme, or changing other options. These options can be found in the help file for each output format (say `?moderncv)`.  For example, the `moderncv` template allows for the selection of one of five themes:  "casual", "classic", "oldstyle", "banking" or "fancy".
To change default options of output formats you can modify the yaml as follows:

````yaml
# Choose a theme and pass other arguments
output:
  vitae::moderncv:
    theme: banking
````


Currently, the YAML header allows these fields to be specified:

- `name`: Your name
- `surname`: Your family or last name
- `position`: Your current workplace title or field
- `address`: Your address
- `date`: The current date
- `profilepic`: A local file path to an image
- `www`: Your website address
- `email`: Your email address
- `twitter`: Your twitter handle
- `github`: Your GitHub handle
- `linkedin`: Your LinkedIn username
- `aboutme`: A short description that is included in a template specific location
- `headcolor`: A featured colour for the template
- `docname`: Control the document name (typically curriculum vitae, or résumé)


### The document body

Like other R Markdown documents, the body allows you to mix R code with markdown to create the main content for your document. Below is an example of the start for a typical CV:

`r htmltools::pre(htmltools::code(paste0(readLines("sample.txt")[14:23],collapse = "\n")))`

The setup chunk is useful to load in any packages that you may use, and also prevent R code and warnings/notes from appearing in your CV. The above code also includes a professional summary using markdown syntax, which will appear in the final CV.

Unlike other R markdown formats, the vitae package and its templates support functions to generate CV entries from data: `detailed_entries()` and `brief_entries()`. Both functions provide sections for `what`, `when`, and `with`, and the `detailed_entries()` additionally supports `where` and `why`. They use an interface similar to [dplyr](https://CRAN.R-project.org/package=dplyr), in that the data can be piped (`%>%`) into these functions, and the arguments can involve some calculations.

#### Detailed entries

Let's add to the main body with some education history. I'm creating a dataset in R to do this, although you can read in the data from excel, or if you have it documented somewhere online like [ORCID](https://orcid.org) you can dynamically access it via their API.

`r htmltools::pre(htmltools::code(paste0(readLines("sample.txt")[25:40],collapse = "\n")))`

In the example above, the [glue](https://CRAN.R-project.org/package=glue) package has been used to combine the start and end years for our `when` input. Excluding any arguments is also okay (as is done for `why`), it will just be left blank in the CV.

#### Brief entries

Brief entries can be included with the same interface as `detailed_entries()`, and is appropriate for entries that do not need as much detail (such as skills). Another application of this is to include a list of R packages that you have published to CRAN using the [pkgsearch](https://CRAN.R-project.org/package=pkgsearch) package.

`r htmltools::pre(htmltools::code(paste0(readLines("sample.txt")[42:53],collapse = "\n")))`

This example also uses several other packages to prepare the data:
- [dplyr](https://CRAN.R-project.org/package=dplyr) to `filter()` my contributed packages, and `arrange()` the data by downloads
- [purrr](https://CRAN.R-project.org/package=purrr) to map over `package_data` column to find packages I've contributed to
- [lubridate](https://CRAN.R-project.org/package=lubridate) to display only the year from the `date` column

#### Bibliography entries

The package also supports bibliography entries from a `*.bib` file using the `bibliography_entries()` function. This outputs the contents of a bibliography using a citation style, and is suitable for CVs containing publications.

`r htmltools::pre(htmltools::code(paste0(readLines("sample.txt")[55:57],collapse = "\n")))`