diff --git a/README.md b/README.md
new file mode 100644
index 0000000..aa08854
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# Nomo, a simple templating library
+
+
+Nomo is pure Rust templating library meant to be unopinionated in which target
+language it is embedded.
+
+Here is an example `nomo` HTML snippet:
+
+```nomo
+<div id="notifications">
+    <ul>
+        {{ for notif in notifications }}
+            <li class="notification-{{= notif.level }}">{{= notif.text }}</li>
+        {{ end }}
+    </ul>
+</div>
+```
+
+It supports the following features:
+
+**If/Else Conditionals**
+
+```nomo
+{{ if user.level > 3 }}
+    ...
+{{ else if value == 1 }}
+    ...
+{{ else }}
+    ...
+{{ end }}
+```
+
+**For Loops**
+
+```nomo
+{{ for user in users }}
+  {{= user.name }}
+{{ end }}
+```
+
+**Whitespace Supression**
+
+```nomo
+Hello
+{{- if world == 2 -}}
+ Hi
+{{- end }}
+```
+
+will print `Hello Hi`.
+
+**Function Calls**
+
+```nomo
+{{= uppercase(user_name) }}
+```
+
+One can use function chaining for less nesting:
+
+```nomo
+{{= user_name | uppercase }}
+```
+
+The `|` operator has the lowest precedence of the operators.
+Functions can still be given arguments. It is always the last argument that is
+'applied' by the operator.
+
+```nomo
+{{= username? | or_default("Unknown") }}
+```
+
+**Undefined Chaining**
+
+Per default, trying to access a value that is not defined will cause an error.
+
+This can be changed with the `?` operator. This can be applied at any level:
+
+```nomo
+{{= user?.profile.description? }}
+```
+
+This will give an error if `user.profile` is not defined. If either `user` or
+`description` is missing, it simply does not render anything (akin to an empty
+string). However if there _is_ an user, it must have a profile value.