diff --git a/.Rbuildignore b/.Rbuildignore
index d821302..428fd47 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -2,3 +2,4 @@
 ^renv\.lock$
 ^.*\.Rproj$
 ^\.Rproj\.user$
+^README\.Rmd$
diff --git a/README.Rmd b/README.Rmd
new file mode 100644
index 0000000..9f08e0e
--- /dev/null
+++ b/README.Rmd
@@ -0,0 +1,55 @@
+---
+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%"
+)
+```
+
+# repositoryr
+
+<!-- badges: start -->
+<!-- badges: end -->
+
+The goal of repositoryr is to provide a step by step guide to creating a R package repository.
+
+## Installation
+
+You can install the development version of repositoryr from [GitHub](https://github.com/) with:
+
+``` r
+# install.packages("pak")
+pak::pak("ImperialCollegeLondon/repositoryr")
+```
+
+## Example
+
+This is a basic example which shows you how to solve a common problem:
+
+```{r example}
+library(repositoryr)
+## basic example code
+```
+
+What is special about using `README.Rmd` instead of just `README.md`? You can include R chunks like so:
+
+```{r cars}
+summary(cars)
+```
+
+You'll still need to render `README.Rmd` regularly, to keep `README.md` up-to-date. `devtools::build_readme()` is handy for this.
+
+You can also embed plots, for example:
+
+```{r pressure, echo = FALSE}
+plot(pressure)
+```
+
+In that case, don't forget to commit and push the resulting figure files, so they display on GitHub and CRAN.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3408bd7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+# repositoryr
+
+<!-- badges: start -->
+<!-- badges: end -->
+
+The goal of repositoryr is to provide a step by step guide to creating a
+R package repository.
+
+## Installation
+
+You can install the development version of repositoryr from
+[GitHub](https://github.com/) with:
+
+``` r
+# install.packages("pak")
+pak::pak("ImperialCollegeLondon/repositoryr")
+```
+
+## Example
+
+This is a basic example which shows you how to solve a common problem:
+
+``` r
+library(repositoryr)
+## basic example code
+```
+
+What is special about using `README.Rmd` instead of just `README.md`?
+You can include R chunks like so:
+
+``` r
+summary(cars)
+#>      speed           dist       
+#>  Min.   : 4.0   Min.   :  2.00  
+#>  1st Qu.:12.0   1st Qu.: 26.00  
+#>  Median :15.0   Median : 36.00  
+#>  Mean   :15.4   Mean   : 42.98  
+#>  3rd Qu.:19.0   3rd Qu.: 56.00  
+#>  Max.   :25.0   Max.   :120.00
+```
+
+You’ll still need to render `README.Rmd` regularly, to keep `README.md`
+up-to-date. `devtools::build_readme()` is handy for this.
+
+You can also embed plots, for example:
+
+<img src="man/figures/README-pressure-1.png" width="100%" />
+
+In that case, don’t forget to commit and push the resulting figure
+files, so they display on GitHub and CRAN.
diff --git a/man/figures/README-pressure-1.png b/man/figures/README-pressure-1.png
new file mode 100644
index 0000000..c092055
Binary files /dev/null and b/man/figures/README-pressure-1.png differ