diff --git a/FORMULA.dom0 b/FORMULA.dom0
index 8efd0fc..ae55859 100644
--- a/FORMULA.dom0
+++ b/FORMULA.dom0
@@ -6,7 +6,7 @@ version:            4.0.12
 release:            1
 name:               virtual-machines-formula
 top_level_dir:      qvm
-formula-files:      README.rst LICENSE qvm
+formula-files:      README.md LICENSE qvm
 pillar-files:       pillar/qvm
 formula_dir:        $(MGMT_DEFAULT_FORMULA_DIR)/$(MGMT_SALTENV)/$(MGMT_NAME)
 pillar_dir:         $(MGMT_DEFAULT_PILLAR_DIR)/$(MGMT_SALTENV)/$(MGMT_TOP_LEVEL_DIR)
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cb7346d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,8 @@
+Virtual Machine Formulae
+========================
+
+Downloads, installs and, configures VMs. Uses pillar data to define
+default VM names and configuration details. For more information,
+including a list of available states, please see the full documentation:
+
+https://www.qubes-os.org/doc/salt/#virtual-machine-formulae
diff --git a/README.rst b/README.rst
deleted file mode 100644
index d618870..0000000
--- a/README.rst
+++ /dev/null
@@ -1,99 +0,0 @@
-========================
-Virtual Machines Formula
-========================
-
-Downloads, installs and configures template as well as creating and
-configuring virtual-machine AppVM's.
-
-Uses pillar data to define default VM names and configuration details.  Default
-settings can be overridden in pillar data located at:
-    ``/srv/pillar/base/qvm/init.sls``
-
-Available states
-================
-
-.. contents::
-    :local:
-
-``qvm.sys-net``
----------------
-System NetVM
-
-``qvm.sys-usb``
----------------
-System UsbVM
-
-``qvm.sys-net-with-usb``
----------------
-System UsbVM bundled into NetVM. Do not enable together with ``qvm.sys-usb``.
-
-``qvm.usb-keyboard``
---------------------
-
-Enable USB keyboard together with UsbVM, including for early system boot (for
-LUKS passhprase). This state implicitly create UsbVM (``qvm.sys-usb``
-state), if not already done.
-
-``qvm.sys-firewall``
---------------------
-System firewall ProxyVM
-
-``qvm.sys-whonix``
-------------------
-Whonix gateway ProxyVM
-
-``qvm.personal``
-----------------
-Personal AppVM
-
-``qvm.work``
-------------
-Work AppVM
-
-``qvm.untrusted``
------------------
-Untrusted AppVM
-
-``qvm.vault``
--------------
-Vault AppVM with no NetVM enabled.
-
-``qvm.default-dispvm``
--------------
-Default Disposable VM template - fedora-26-dvm AppVM
-
-``qvm.anon-whonix``
--------------------
-Whonix workstation AppVM.
-
-``qvm.whonix-ws-dvm``
--------------------
-Whonix workstation AppVM for Whonix Disposable VMs.
-
-``qvm.updates-via-whonix``
--------------------
-Setup UpdatesProxy to route all templates updates through Tor (sys-whonix here).
-
-``qvm.template-fedora-21``
---------------------------
-Fedora-21 TemplateVM
-
-``qvm.template-fedora-21-minimal``
-----------------------------------
-Fedora-21 minimal TemplateVM
-
-``qvm.template-debian-7``
--------------------------
-Debian 7 (wheezy) TemplateVM
-
-``qvm.template-debian-8``
--------------------------
-Debian 8 (jessie) TemplateVM
-
-``qvm.template-whonix-gw``
---------------------------
-Whonix Gateway TemplateVM
-
-``qvm.template-whonix-ws``
---------------------------
-Whonix Workstation TemplateVM
diff --git a/rpm_spec/qubes-mgmt-salt-dom0-virtual-machines-dom0.spec.in b/rpm_spec/qubes-mgmt-salt-dom0-virtual-machines-dom0.spec.in
index 7a48a10..aeb5567 100644
--- a/rpm_spec/qubes-mgmt-salt-dom0-virtual-machines-dom0.spec.in
+++ b/rpm_spec/qubes-mgmt-salt-dom0-virtual-machines-dom0.spec.in
@@ -45,9 +45,9 @@ fi
 
 %files
 %defattr(-,root,root)
-%doc LICENSE README.rst
+%doc LICENSE README.md
 %attr(750, root, root) %dir /srv/formulas/base/virtual-machines-formula
-/srv/formulas/base/virtual-machines-formula/README.rst
+/srv/formulas/base/virtual-machines-formula/README.md
 /srv/formulas/base/virtual-machines-formula/LICENSE
 /srv/formulas/base/virtual-machines-formula/qvm/anon-whonix.sls
 /srv/formulas/base/virtual-machines-formula/qvm/anon-whonix.top