diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1bed445
--- /dev/null
+++ b/README.md
@@ -0,0 +1,31 @@
+# Goodtimer
+
+This is a simple countdown in plain html+css+javascript. You can either host it yourself (just serve the files in this repository with a web server) or use (https://goodtimer.lubiland.de)[https://goodtimer.lubiland.de].
+
+The target date is specified behind a hash (#) and in any [ECMAScript Date Time String Format](https://tc39.es/ecma262/#sec-date-time-string-format). When you omit the timezone it uses the local time of the browser.
+
+Here are some example URLs:
+
+https://goodtimer.lubiland.de/#2020-11-24T00:00+01:00  
+https://goodtimer.lubiland.de/#2020-11-24T00:00  
+https://goodtimer.lubiland.de/#2020-11-24  
+https://goodtimer.lubiland.de/#2020-11  
+https://goodtimer.lubiland.de/#2021  
+
+## Matrix widget
+
+Goodtimer is also usable as widget for [Matrix](https://matrix.org) clients. Either specify the URL as 'Custom Widget' within (Element)(https://element.io) or manually send something like this example event:
+
+type: im.vector.modular.widgets  
+state_key: shadowlands-release
+
+```json
+{
+	"type": "customwidget",
+	"url": "https://goodtimer.lubiland.de/#2020-11-24T00:00+01:00",
+	"name": "Shadowlands Release",
+	"data": {
+		"curl": "https://goodtimer.lubiland.de/"
+	}
+}
+```