diff --git a/docs/vars.md b/docs/vars.md
new file mode 100644
index 0000000..0ec98ce
--- /dev/null
+++ b/docs/vars.md
@@ -0,0 +1,32 @@
+# Required variables
+These variables are required by some roles. Example values included.
+
+```
+timezone: 'Europe/Helsinki'
+domain: 'example.tld'
+email: 'admin@domain.tld'
+```
+
+# Default variables
+These variables have default values (shown below) which can be overridden.
+
+```
+install_packages:
+  - vim
+  - git
+  - etckeeper
+  - net-tools
+  - nmap
+  - ncdu
+  - fish
+  - parted
+```
+
+# Optional variables
+These variables are not required and not defined by default. Example values included.
+
+```
+delete_packages:
+  - nano
+  - curl
+```
diff --git a/docs/vars/optional.yaml b/docs/vars/optional.yaml
deleted file mode 100644
index fed4449..0000000
--- a/docs/vars/optional.yaml
+++ /dev/null
@@ -1,15 +0,0 @@
----
-
-install_packages:
-  - vim
-  - git
-  - etckeeper
-  - net-tools
-  - nmap
-  - ncdu
-  - fish
-  - parted
-
-delete_packages:
-  - nano
-  - curl
diff --git a/docs/vars/required.yaml b/docs/vars/required.yaml
deleted file mode 100644
index 108464a..0000000
--- a/docs/vars/required.yaml
+++ /dev/null
@@ -1,5 +0,0 @@
----
-
-timezone: 'Europe/Helsinki'
-domain: 'example.tld'
-email: 'admin@domain.tld'