diff --git a/README b/README
index e69de29..4ce5d88 100644
--- a/README
+++ b/README
@@ -0,0 +1,118 @@
+uml - untitled markup language
+==============================
+
+uml is a markup is a (mostly) line based markup langauge. it mostly exists to be 'rendered' or exported into other markup languages. as such it is the 'lowest common denominator' of all these markup languages. its features include
+
+- headers (#), subheaders (##), subsubheaders (###), ...
+- quotes (>)
+- links (=)
+- link descriptions (not implimented)
+- non-rendered comments (%)
+- lists (-/*)
+- codeblocks/preformatted text (not implimented)
+- tables (not implimented)
+- inline links (not implimented)
+
+files
+=====
+
+README - this document
+uml.py - tokenization prototype
+
+examples of markup
+==================
+
+header:
+# header 1
+subheader:
+## header 2
+subsubheader
+### header 3
+      .
+      .
+      .
+quotes:
+> it was the best of times, it was the worst of times...
+links:
+= https://http.cat
+link with description:
+= https://http.cat cute cats
+comment:
+% here's a comment that will not be rendered!
+lists:
+- one
+- two
+* three
+* four
+- five
+codeblocks:
+```
+#include <stdio.h>
+int main(void) { return 0; }
+```
+codeblock with description:
+```description
+#include <stdio.h>
+int main(void) { return 0; }
+```
+tables:
+| ticker | value | increase
+| TILD | 102.3 | +10.39
+| EVER | 403.1 | +493.2
+| SECO | 302.1 | -932.6
+| OL | 6092.1 | -4.3
+
+inline links:
+hello there, here's a [link](https://example.com)
+
+rendering considerations
+========================
+
+uml was designed for rendering into gemtext, gophermaps, simple html, and plain text, in addition to regular markdown.
+
+for rendering into gophermaps, plaintext, and gemtext, it is recommended that inline links be rendered using some sort of reference system:
+
++--------------| Input text |--+
+| Here's a line with [inline   |
+| links](https://example.com). |
++-------------| Output text |--+
+| Here's a line with inline    |
+| links [1].                   |
+|                              |
+| [1]: https://example.com     |
++------------------------------+
+
+tables can be rendered like so:
++--------------------------| Input text |--+
+| | roses | are | red                      |
+| | violets | are | blue                   |
+| | tables | are | cool                    |
++-------------------------| Output text |--+
+|                                          |
+| +----------------------+                 |
+| | roses   | are | red  |                 |
+| | violets | are | blue |                 |
+| | tables  | are | cool |                 |
+| +----------------------+                 |
+|                                          |
++------------------------------------------+
+
+uml.py usage
+============
+
+uml.py takes no arguments and just listens on stdin. it tokenizes the implimented parts of the markup language until an EOF is reached, in which case the program prints the results of the tokenization.
+
++----------------------| Input text |--+
+| # header                             |
+| ## subheader                         |
+| % comment                            |
++---------------------| Output text |--+
+| header h1                            |
+| subheader h2                         |
+| comment c                            |
++--------------------------------------+
+
+contact / bugs
+==============
+
+randomuser@tilde.club