diff --git a/.Rbuildignore b/.Rbuildignore
index c3a8f4a..eff1609 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -9,3 +9,4 @@
 
 ^src/rust/.cargo$
 ^src/rust/target$
+^README\.Rmd$
diff --git a/README.Rmd b/README.Rmd
new file mode 100644
index 0000000..32224cf
--- /dev/null
+++ b/README.Rmd
@@ -0,0 +1,45 @@
+---
+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%"
+)
+```
+
+# blazr <a href="https://r-staceans.github.io/blazr/"><img src="man/figures/logo.png" align="right" height="138" /></a>
+
+<!-- badges: start -->
+[![R-CMD-check](https://github.com/r-staceans/blazr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-staceans/blazr/actions/workflows/R-CMD-check.yaml)
+[![Codecov test coverage](https://codecov.io/gh/r-staceans/blazr/graph/badge.svg)](https://app.codecov.io/gh/r-staceans/blazr)
+[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+<!-- badges: end -->
+
+⚠️ **This package is a work in progress and is not yet ready for use.**
+
+The goal of blazr is to provide R with a blazingly fast interface to multi-threading in Rust.
+
+## Installation
+
+Install the development version of `blazr` from GitHub with:
+
+``` r
+# install.packages("pak")
+pak::pak("r-staceans/blazr")
+```
+
+## Example
+
+This is just a dummy example:
+
+```{r example}
+library(blazr)
+
+blazr::to_upper("hello, world")
+```
diff --git a/README.md b/README.md
index e4210cd..3c430a0 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,38 @@
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
 # blazr <a href="https://r-staceans.github.io/blazr/"><img src="man/figures/logo.png" align="right" height="138" /></a>
+
 <!-- badges: start -->
+
 [![R-CMD-check](https://github.com/r-staceans/blazr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-staceans/blazr/actions/workflows/R-CMD-check.yaml)
-[![Codecov test coverage](https://codecov.io/gh/r-staceans/blazr/graph/badge.svg)](https://app.codecov.io/gh/r-staceans/blazr)
-[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+[![Codecov test
+coverage](https://codecov.io/gh/r-staceans/blazr/graph/badge.svg)](https://app.codecov.io/gh/r-staceans/blazr)
+[![Lifecycle:
+experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
 <!-- badges: end -->
+
+⚠️ **This package is a work in progress and is not yet ready for use.**
+
+The goal of blazr is to provide R with a blazingly fast interface to
+multi-threading in Rust.
+
+## Installation
+
+Install the development version of `blazr` from GitHub with:
+
+``` r
+# install.packages("pak")
+pak::pak("r-staceans/blazr")
+```
+
+## Example
+
+This is just a dummy example:
+
+``` r
+library(blazr)
+
+blazr::to_upper("hello, world")
+#> [1] "HELLO, WORLD"
+```