diff --git a/.Rbuildignore b/.Rbuildignore
index efcf2a49..af9e1444 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -24,3 +24,4 @@ ubuntu_17_installation.sh
 ^\.github$
 ^data-raw$
 ^.covrignore$
+^vignettes/tmap-getstarted.Rmd$
diff --git a/.gitignore b/.gitignore
index 9c749c77..2732aca5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,3 +39,4 @@ vignettes/*.md
 docs
 /doc/
 /Meta/
+inst/doc
diff --git a/vignettes/.gitignore b/vignettes/.gitignore
new file mode 100644
index 00000000..097b2416
--- /dev/null
+++ b/vignettes/.gitignore
@@ -0,0 +1,2 @@
+*.html
+*.R
diff --git a/vignettes/tmap-getstarted.Rmd b/vignettes/tmap-getstarted.Rmd
new file mode 100644
index 00000000..6f879cab
--- /dev/null
+++ b/vignettes/tmap-getstarted.Rmd
@@ -0,0 +1,215 @@
+---
+title: "tmap: get started!"
+output: 
+  rmarkdown::html_vignette:
+    toc: true
+vignette: >
+  %\VignetteIndexEntry{tmap: get started!}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\usepackage[utf8]{inputenc}
+---
+
+```{r, echo = FALSE, message = FALSE}
+knitr::opts_chunk$set(collapse = T, fig.width=6, fig.height=3)
+```
+
+With the tmap package, thematic maps can be generated with great flexibility.
+The syntax for creating plots is similar to that of `ggplot2`, but tailored to maps.
+This vignette is for those who want to get started with tmap within a couple of minutes.
+
+For more context on R's geographic capabilities we recommend the online version of the book [Geocomputation with R](https://r.geocompx.org/). The [Making maps with R](https://r.geocompx.org/adv-map) chapter of the book provides many more context and abundant code examples of map making with `tmap` and other packages. Other good resources are the vignettes of the [`sf` package](https://CRAN.R-project.org/package=sf/vignettes/sf1.html).
+
+
+### Hello World!
+
+A good place to start is to create a map of the world.
+After [installing](https://github.com/r-tmap/tmap#installation) tmap, the following lines of code should create the map shown below:
+
+```{r}
+library(tmap)
+
+tm_shape(World) +
+    tm_polygons("HPI")
+```
+
+The object `World` is a spatial object of class `sf` from the [sf package](https://CRAN.R-project.org/package=sf); it is a `data.frame` with a special column that contains a geometry for each row, in this case polygons. 
+In order to plot it in tmap, you first need to specify it with `tm_shape()`.
+Layers can be added with the `+` operator, in this case `tm_polygons()`.
+There are many layer functions in tmap, which can easily be found in the documentation by their `tm_` prefix.
+See also `?'tmap-element'`.
+
+### Interactive maps
+
+Each map can be plotted as a static image or viewed interactively using `"plot"` and `"view"` modes, respectively.
+The mode can be set with the function `tmap_mode`, and toggling between the modes can be done with the 'switch' `ttm()` (which stands for toggle thematic map.
+
+```{r}
+tmap_mode("view")
+
+tm_shape(World) +
+    tm_polygons("HPI")
+```
+
+### Multiple shapes and layers
+
+A shape is a spatial object (with a class from `sf`, `stars`, or `terra`).
+Multiple shapes and also multiple layers per shape can be plotted:
+
+```{r}
+
+tmap_mode("plot")
+tm_shape(land) +
+    tm_raster("elevation", palette = terrain.colors(10)) +
+tm_shape(World) +
+    tm_borders("white", lwd = .5) +
+    tm_text("iso_a3", size = "AREA") +
+tm_shape(metro) +
+    tm_symbols(col = "red", size = "pop2020", scale = .5) +
+tm_legend(show = FALSE)
+```
+
+### Facets
+
+Facets can be created in three ways:
+
+1. By assigning multiple variable names to one aesthetic (in this example the first argument of `tm_polygons()`:
+
+```{r}
+tmap_mode("view")
+tm_shape(World) +
+    tm_polygons(c("HPI", "economy")) +
+    tm_facets(sync = TRUE, ncol = 2)
+```
+
+2. By splitting the spatial data with the `by` argument of `tm_facets`: 
+
+```{r}
+tmap_mode("plot")
+
+NLD_muni$perc_men <- NLD_muni$pop_men / NLD_muni$population * 100
+
+tm_shape(NLD_muni) +
+    tm_polygons("perc_men", palette = "RdYlBu") +
+    tm_facets(by = "province")
+```
+
+3. By using the `tmap_arrange` function:
+
+```{r}
+tmap_mode("plot")
+
+tm1 <- tm_shape(NLD_muni) + tm_polygons("population", convert2density = TRUE)
+tm2 <- tm_shape(NLD_muni) + tm_bubbles(size = "population")
+
+tmap_arrange(tm1, tm2)
+```
+
+### Basemaps and overlay tile maps
+
+Tiled basemaps can be added with the layer function `tm_basemap`.
+Semi-transparent overlay maps (for example annotation labels) can be added with `tm_tiles`.
+
+```{r}
+tmap_mode("view")
+tm_basemap("Stamen.Watercolor") +
+tm_shape(metro) + tm_bubbles(size = "pop2020", col = "red") +
+tm_tiles("Stamen.TonerLabels")
+```
+
+
+See a [preview of the available tilemaps](https://leaflet-extras.github.io/leaflet-providers/preview/). 
+This list is also accessible in R: `leaflet::providers`.
+
+### Options and styles
+
+The functions `tm_layout()` and `tm_view()` are used to specify the map layout and the interactive aspects respectively.
+These functions can be used in the same way as the layer functions, e.g.
+
+```{r}
+tmap_mode("plot")
+
+tm_shape(World) +
+    tm_polygons("HPI") +
+tm_layout(bg.color = "skyblue", inner.margins = c(0, .02, .02, .02))
+```
+
+These options, as well as a couple of others, can also be set within with `tmap_options`, which works in the same way as the base R function `options`.
+The main advantage is that these options are set globally, so they do not have to be specified in each map, for the duration of the session.
+
+```{r}
+tmap_options(bg.color = "black", legend.text.color = "white")
+
+tm_shape(World) +
+    tm_polygons("HPI", legend.title = "Happy Planet Index")
+```
+
+A style is a certain configuration of the tmap options. 
+
+```{r}
+tmap_style("classic")
+
+tm_shape(World) +
+    tm_polygons("HPI", legend.title = "Happy Planet Index")
+```
+
+```{r}
+# see what options have been changed
+tmap_options_diff()
+
+# reset the options to the default values
+tmap_options_reset()
+```
+
+New styles can be created; see `?tmap_options`.
+
+### Exporting maps
+
+```{r}
+tm <- tm_shape(World) +
+    tm_polygons("HPI", legend.title = "Happy Planet Index")
+
+tm
+
+ttmp()
+if (FALSE) {
+  ## save an image ("plot" mode)
+  tmap_save(tm, filename = "world_map.png")
+
+## save as stand-alone HTML file ("view" mode)
+tmap_save(tm, filename = "world_map.html")
+}
+
+```
+
+### Shiny integration
+
+It is possible to use tmap in shiny:
+
+```{r, eval = FALSE}
+# in UI part:
+tmapOutput("my_tmap")
+
+# in server part
+output$my_tmap = renderTmap({
+    tm_shape(World) + tm_polygons("HPI", legend.title = "Happy Planet Index")
+})
+```
+
+See `?renderTmap` for a working example.
+
+### Quick thematic map
+
+Maps can also be made with one function call.
+This function is `qtm`:
+
+```{r}
+qtm(World, fill = "HPI", fill.palette = "RdYlGn")
+```
+
+### Tips 'n Tricks
+
+Run:
+
+```{r}
+tmap_tip()
+```