README.Rmd

---
output: github_document
---

<!-- 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%"
)
```

# gluedown <img src="man/figures/logo.png" align="right" width="120" />

<!-- badges: start -->
[![Lifecycle: experimental][life_badge]][life_link]
[![CRAN status][cran_badge]][cran_link]
![Downloads][dl_badge]
[![Codecov test coverage][cov_badge]][cov_link]
[![R build status][ga_badge]][ga_link]
<!-- badges: end -->

The goal of `gluedown` is to ease the transition from R's powerful vectors to
formatted markdown text. The package uses [`glue()`][glue] to wrap character
vectors in markdown syntax. With the [`knitr`][knitr] package, users can print
the formatted vectors directly to the body of a markdown document.

## Installation

Install the release version from [CRAN][cran]:

```{r release, eval=FALSE}
install.packages("gluedown")
```

The development version can be installed from [GitHub][gh]:

```{r develop, eval=FALSE}
# install.packages("remotes")
remotes::install_github("k5cents/gluedown")
```

## Usage

```{r prepare, warning=FALSE, message=FALSE}
library(gluedown)
library(stringr)
library(rvest)
```

Use the `results='asis'` chunk option to print the formatted output to the body
of a document.

````markdown
`r ''````{r results='asis'}
md_order(x = c("Legislative", "Executive", "Judicial"))
```
````

```{r asis, results='asis', echo=FALSE}
md_order(x = c("Legislative", "Executive", "Judicial"))
```

### Lists

Printing vectors as markdown lists was the initial inspiration for the package.
Here, we use five different functions to create five elements of a new vector.

```{r vector}
inlines <- c(
  md_bold("Alabama"),
  md_code("Alaska"),
  md_link("Arizona" = "https://az.gov"),
  md_italic("Arkansas"),
  md_strike("California")
)
print(inlines)
```

Then we can print that new vector as a list, including the inline formatting.

```{r bullets, results='asis'}
md_bullet(inlines)
```

### Inline

You can also use `gluedown` to format R [inline code results][inline].

```{r inline}
name <- sample(state.name, size = 1)
abb <- state.abb[match(name, state.name)]
# `r md_bold(name)`
# `r md_italic(abb)`
```

In this case, our randomly selected state is  `r md_bold(name)`, which has the 
abbreviation `r md_italic(abb)`.

### Pipes

All functions are designed to fit within the tidyverse ecosystem and work with
[pipes][pipe].

```{r pipe, results='asis'}
read_html("https://w.wiki/A58") %>% 
  html_node("blockquote") %>% 
  html_text(trim = TRUE) %>% 
  str_remove("\\[.*\\]") %>% 
  md_quote()
```

### Extensions

The package primarily uses [GitHub Flavored Markdown][gfm], with support 
for useful extensions like [task lists][task].

```{r extension, results='asis'}
legislation <- c("Houses passes", "Senate concurs", "President signs")
md_task(legislation, check = 1:2)
```

## Contribute

Please note that the `gluedown` project is released with a 
[Contributor Code of Conduct][coc]. By contributing to this project, you agree
to abide by its terms.

<!-- links: start -->
[life_badge]: https://img.shields.io/badge/lifecycle-maturing-blue.svg
[life_link]: https://lifecycle.r-lib.org/articles/stages.html#maturing
[cran_badge]: https://www.r-pkg.org/badges/version/gluedown
[cran_link]: https://CRAN.R-project.org/package=gluedown
[ga_badge]: https://github.com/k5cents/gluedown/workflows/R-CMD-check/badge.svg
[ga_link]: https://github.com/k5cents/gluedown/actions
[cov_badge]: https://codecov.io/gh/k5cents/gluedown/graph/badge.svg?token=Ln4HFpOH2P
[cov_link]: https://app.codecov.io/gh/k5cents/gluedown?branch=master
[dl_badge]: https://cranlogs.r-pkg.org/badges/grand-total/gluedown
[coc]: https://k5cents.github.io/gluedown/CODE_OF_CONDUCT.html
[cran]: https://cran.r-project.org/package=gluedown
[gfm]: https://github.github.com/gfm/
[gh]: https://github.com/k5cents/gluedown
[glue]: https://github.com/tidyverse/glue
[inline]: https://rmarkdown.rstudio.com/lesson-4.html
[knitr]: https://github.com/yihui/knitr
[pipe]: https://magrittr.tidyverse.org/reference/pipe.html
[rmd]: https://github.com/rstudio/rmarkdown
[task]: https://help.github.com/en/articles/about-task-lists
<!-- links: end -->