README.Rmd

---
output: github_document
always_allow_html: true
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# tweetrmd

<!-- badges: start -->
<!-- badges: end -->

Easily embed Tweets anywhere R Markdown turns plain text into HTML.

## Installation

You can install the released version of **tweetrmd** from GitHub:

``` r
# install.packages("devtools")
devtools::install_github("gadenbuie/tweetrmd")
```

## Embed a Tweet

```{r setup, include=FALSE, eval=FALSE}
# not using yet because memoising screenshots 
# doesn't work with knitr out of the box yet
library(memoise)
tweet_url <- tweetrmd::tweet_url
tweet_embed <- memoise(tweetrmd::tweet_embed, cache = cache_filesystem(".tweets"))
tweet_screenshot <- memoise(tweetrmd::tweet_screenshot, cache = cache_filesystem(".tweets"))
```

```{r}
library(tweetrmd)
tweet_embed("https://twitter.com/alexpghayes/status/1211748406730706944")
```

Or if you would rather use the screen name and status id.

```{r}
tweet_embed(tweet_url("alexpghayes", "1211748406730706944"))
```

In rich HTML outputs, the full embedded tweet is available and interactive.
Here, in GitHub-flavored markdown, only the content of the tweet is seen.

## Embed many tweets

If you have several tweets you would like to embed at once,
you can use the following pattern to include add a vector of tweets to your document.
This works well when you want to include a 
[thread of tweets](https://gist.github.com/gadenbuie/33c350458305f4423f30c1274be63b34).

```{r}
thread <- c(
  "https://twitter.com/grrrck/status/1333804309272621060",
  "https://twitter.com/grrrck/status/1333804487148855300", 
  "https://twitter.com/grrrck/status/1333805092152123394"
)

htmltools::tagList(
  lapply(thread, tweet_embed, plain = TRUE)
)
```

(Note that I used `plain = TRUE` to embed each tweet [as markdown](#embed-without-tracking).)

## Take a screenshot of a tweet

Screenshots are automatically embedded in R Markdown documents,
or you can save the screenshot as a `.png` or `.pdf` file.
Uses the [rstudio/webshot2](https://github.com/rstudio/webshot2) package.

```{r screenshot, out.width="400px"}
tweet_screenshot(tweet_url("alexpghayes", "1211748406730706944"))
```

## Just include a tweet in any R Markdown output format

When you want to include a tweet in multiple R Markdown formats,
you can use `include_tweet()`.
It's like `knitr::include_graphics()` but for tweets.
The function will automatically include the tweet
as HTML in HTML outputs,
or as a screenshot in all others.

````markdown
```{r tweet-from-dsquintana}`r ''`
include_tweet("https://twitter.com/dsquintana/status/1275705042385940480")
```
````

```{r tweet-from-dsquintana, echo=FALSE, out.width="400px"}
include_tweet("https://twitter.com/dsquintana/status/1275705042385940480")
```


## Customize tweet appearance

Twitter's [oembed API](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-oembed)
provides a number of options, 
all of which are made available for customization in `tweet_embed()` and `tweet_screenshot()`.

```{r screenshot-customized, out.width="300px"}
tweet_screenshot(
  tweet_url("alexpghayes", "1211748406730706944"),
  maxwidth = 300,
  hide_media = TRUE,
  theme = "dark"
)
```

## Embed without tracking

You can use `tweetrmd` to embed tweets in your documents and outputs without
including Twitter JavaScript or tracking.
The easiest way is to set `plain = TRUE` in `include_tweet()`.
This will insert minimal HTML for web outputs
or convert the tweet text to markdown for non-web outputs.

```{r tweet-from-dsquintana2, echo=TRUE, results='hide'}
include_tweet(
  "https://twitter.com/dsquintana/status/1275705042385940480",
  plain = TRUE
)
```

````
```{r ref.label="tweet-from-dsquintana2", echo=FALSE}
```

````

Alternatively, you can choose to use `tweet_screenshot()` or `tweet_markdown()`
to embed all tweets in your documents.

## Caching tweets with memoization

Tweets are often deleted and re-running `tweet_embed()` or `tweet_screenshot()`
may fail or overwrite a previous screenshot of a tweet.
To avoid this, you can use the [memoise](https://github.com/r-lib/memoise) package.

```r
library(memoise)

tweet_cached <- memoise(tweet_embed, cache = cache_filesystem('.tweets'))
tweet_shot_cached <- memoise(tweet_screenshot, cache = cache_filesystem('.tweets'))
```

<sup>*</sup>When memoising `tweet_screenshot()` you need to manually save the file
to a specific location. In the future my goal is for this to be automatic.

---

Note: When using `tweet_embed()`,
you may need to add the following line to your YAML header
for strict markdown output formats.

```yaml
always_allow_html: true
```