diff --git a/.gitignore b/.gitignore
index 607b6192..22393bf1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 .DS_Store
 .vscode
+mypy_report
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
diff --git a/Makefile b/Makefile
index ac157467..47db2603 100644
--- a/Makefile
+++ b/Makefile
@@ -1,2 +1,6 @@
 test:
 	pytest --cov-report term-missing --cov=rich tests/ -v
+typecheck:
+	mypy -p rich --python-version 3.7 --ignore-missing-imports --warn-unreachable
+typecheck-report:
+	mypy -p rich --python-version 3.7 --ignore-missing-imports --warn-unreachable --html-report mypy_report
diff --git a/README.md b/README.md
index 85e6ff19..1d2c944c 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,73 @@
-# WIP
+# Rich
+
+Rich is a Python library for _rich_ text and advanced formatting to the terminal. Rich provided an easy to use API for colored text (up to 16.7million colors) with bold / italic / underline etc. and a number of more sophisticated formatting options, such as syntax / regex highlighting, emoji, tables, and markdown rendering.
+
+Rich is also a _framework_ in that it implements a simple protocol which you may use to make custom objects renderable with advanced terminal formatting.
+
+## Installing
+
+Rich may be installed with pip or your favorite PyPi package manager.
+
+```
+pip install rich
+```
+
+## Basic Usage
+
+The first step to using the rich console is to import and construct the `Console` object.
+
+```python
+from rich.console import Console
+
+console = Console()
+```
+
+Most applications will require one `Console` instance. The easiest way to manage your console instance would be to construct an instance at the module level and import it where needed.
+
+The Console object has a `print` method which has an intentionally similar interface to the builtin `print` function. Here's an example of use:
+
+```
+console.print("Hello", "World!")
+```
+
+As you might expect, this will print `"Hello World!"` to the terminal. The only difference from the `print` function is that the output is word-wrapped by default (Rich auto-detects the width of the terminal).
+
+There are a few ways of adding color and style to your output. You can set a style for the entire output, by adding a `style` keyword argument. Here's an example:
+
+```
+console.print("Hello", "World!", style="bold red")
+```
+
+The output will be something like the following:
+
+<code>
+        <pre style="font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"><span style="color: #800000; font-weight: bold">Hello World! 
+</span></pre>
+    </code>
+
+That's fine for styling a line of text at a time. For more finely grained styling, Rich renders a special markup which is similar in syntax to [bbcode](https://en.wikipedia.org/wiki/BBCode). Here's an example:
+
+```python
+console.print("Where there is a [b]Will[/b] there is a [i]way[/i].")
+```
+
+<code>
+        <pre style="font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">
+Where there is a <span style="font-weight: bold">Will</span> there is a <span style="font-style: italic">way</span>. 
+</pre>
+    </code>
+
+## Emoji
+
+Rich supports a simple way of inserting emoji in to terminal output, by using the name of the emoji between two colons. Here's an example:
+
+```python
+console.print(":smiley: :vampire: :pile_of_poo: :thumbs_up: :raccoon:")
+```
+
+<code>
+        <pre style="font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">😃 🧛 💩 👍 🦝 
+</pre>
+    </code>
+
+Please use this feature wisely.
diff --git a/rich/color.py b/rich/color.py
index 6c12d72b..45143d6f 100644
--- a/rich/color.py
+++ b/rich/color.py
@@ -261,7 +261,7 @@ class Color(NamedTuple):
     number: Optional[int] = None
     triplet: Optional[ColorTriplet] = None
 
-    def __str__(self):
+    def __str__(self) -> str:
         """Render the color to the terminal."""
         attrs = self.get_ansi_codes(foreground=True)
         return (
diff --git a/rich/console.py b/rich/console.py
index dd478875..f77a0994 100644
--- a/rich/console.py
+++ b/rich/console.py
@@ -578,8 +578,8 @@ class Console:
                 render_str = renderable
                 if emoji:
                     render_str = _emoji_replace(render_str)
-                render_str = self.render_str(render_str)
-                append_text(highlight(render_str) if highlight else render_str)
+                render_text = self.render_str(render_str)
+                append_text(highlight(render_text) if highlight else render_text)
             elif isinstance(renderable, Text):
                 append_text(renderable)
             elif isinstance(renderable, (int, float, bool, bytes, type(None))):
diff --git a/rich/emoji.py b/rich/emoji.py
index 4ad68857..c4134596 100644
--- a/rich/emoji.py
+++ b/rich/emoji.py
@@ -59,7 +59,7 @@ class Emoji:
 if __name__ == "__main__":  # pragma: no cover
     from .console import Console
 
-    c = Console(markup=None)
+    c = Console(markup=False)
 
     e = Emoji("thumbs_up")
     print(repr(e))
diff --git a/rich/style.py b/rich/style.py
index c487a3b6..40c48415 100644
--- a/rich/style.py
+++ b/rich/style.py
@@ -104,11 +104,11 @@ class Style:
             append(self._bgcolor.name)
         return " ".join(attributes) or "none"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         """Render a named style differently from an anonymous style."""
         return f'<style "{self}">'
 
-    def __eq__(self, other) -> bool:
+    def __eq__(self, other: Any) -> bool:
         if not isinstance(other, Style):
             return NotImplemented
         return (