diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e346929
--- /dev/null
+++ b/README.md
@@ -0,0 +1,21 @@
+# mdcat
+mdcat is a tiny portable linux binary to render markdown from a file (or stdin) to styled ansi for the terminal.
+## usage examples:
+```sh
+mdcat README.md | less -R # -R is required for less to support ansi styling
+```
+```sh
+printf '# header\n- list item 1\n- list item 2' | mdcat
+```
+## features
+mdcat isn't really a compliant markdown implementation - i made it to render a bit of styling in notes i write on the terminal.
+the following are currently supported:
+- bold with `**text**`
+- italic with `*text*`
+- underline with `_text_`
+- links with `[label](destination)`
+- headers with `# text`
+- lists with `- list item` or `1. list item` (but numbered lists dont render as numbered yet)
+- task lists with `- [x] list item` or `- [ ] list item` where a checkbox is ticked if the `x` is present.
+- horizontal rules with `***` which span the entire terminal width.
+- strikethrough with `~~text~~`
\ No newline at end of file