---
title: Get started
vignette: >
  %\VignetteIndexEntry{r2typ}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
knitr:
  opts_chunk:
    collapse: true
    comment: '#>'
    message: false
---

`{r2typ}` is an R package designed to generate **Typst markup**. You can use it as is, but it also works well with [Quarto](https://quarto.org/).

## Installation

You can install it with:

```r
# install.packages("pak")
pak::pkg_install("y-sunflower/r2typ")
```

## Quick start

```{r}
library(r2typ)
```

```{r}
#| echo: false
# this cell is here to tell r2typ/knitr to not consider current
# page a Quarto doc in order to just display raw text output.
library(knitr)
knit_print.typst_markup <- function(x, ...) {
  unclass(x)
}
registerS3method(
  "knit_print",
  "typst_markup",
  "knit_print.typst_markup"
)
```

All functions accept any kind of positional or named arguments:

```{r}
heading(level = 2, "A title")
text_(weight = 500, "Some text")
```

However, in Typst, not all functions behave the same way regarding positional and named arguments. For this reason, `{r2typ}` automatically adjusts the behavior when necessary.

For example, the `list_()` function will put everything in a list format:

```{r}
list_(tight = FALSE, "hey", "you", "!")
```

> Note that the function is `list_()` and not `list()` because `list()` is a base R function.

The same applies to the `table_()` function:

```{r}
table_("hey", "you", "!")
```

## Typst units

Typst uses a unique approach for units, as they are not quoted.

`{r2typ}` provides several utility functions to make working with Typst units easy:

```{r}
text_(size = pt_(20), "Ice cream")
```

This works with all Typst units:

```{r}
image_("image.png", width = percent(80))
```

## Typst colors

Typst offers a large set of predefined colors such as `red` or `blue`. `{r2typ}` provides the same:

```{r}
text_(fill = green, "Green text")
```

All built-in Typst colors are available in `{r2typ}`. You can find them [here](../reference/typst_colors.html).

You can also use the `rgb_()` function:

```{r}
text_(fill = rgb_("#ffc300"), "Yellow-ish text")
```

## Typst alignment

Similarly to colors, Typst includes specific objects for alignment. They work well in `{r2typ}`:

```{r}
place(
  center,
  dy = pt_(15),
  "hello"
)
```

You can combine them to mimic Typst syntax:

```{r}
place(
  top + left,
  dy = pt_(15),
  "hello"
)
```

You can even combine them with colors, which is often useful for strokes:

```{r}
line_(stroke = pt_(2) + blue)
```

## Convert R types to Typst types

`{r2typ}` converts some R types into Typst types:

- `NULL` becomes `none`

```{r}
image_("image.png", width = percent(80), alt = NULL)
```

- `TRUE`/`FALSE` become `true`/`false`

```{r}
list_(tight = FALSE, "hey", "you")
```

- `c()` vectors and unnamed `list()` (such as `list("a", "b"`) become arrays:

```{r}
text_(`stylistic-set` = c(1, 2, 3), "10 years ago")

text_(`stylistic-set` = list(1, 2, 3), "10 years ago") # equivalent
```

- Named `list()` (such as `list(a = "hello", b = "world")`) become dictionnaries:

```{r}
text_(costs = list(hyphenation = percent(100), runt = percent(100)))
```

> Note that the goal here is **only** to translate R data types that have an equivalent in Typst, **not to be exhaustive**.

## Set and show rules

`{r2typ}` has all a function for all set and (simple) show rules. If you're unfamiliar with them, check out the [official documentation](https://typst.app/docs/reference/styling/).

### set rules

```{r}
set_text(red)

set_enum(tight = FALSE)

set_par(
  `first-line-indent` = em(1),
  spacing = em(0.65),
  justify = TRUE
)
```

### show rules

```{r}
show_heading(set_text(navy))
```

## Nested function calls

Calling a function within another function works as well:

```{r}
place(
  center + horizon,
  dy = pt_(15),
  square(size = pt_(35), fill = red)
)

page(
  flipped = TRUE,
  columns = 2,
  fill = red,
  place(
    top + left,
    dx = pt_(-5),
    rect_(
      fill = blue,
      radius = pt_(2),
      "yooooo"
    )
  )
)
```

## Tables

You create tables manually:

```{r}
table_(
  columns = 2,
  "hey",
  "folks!"
)
```

Or from a data frame:

```{r}
df <- data.frame(x = c(1, 2, 3), y = c(4, 5, 6))

table_(
  `columns-gutter` = cm_(1),
  align = right,
  df
)
```

It automatically detects the number of columns, but you can specify it yourself!