diff --git a/README.md b/README.md
deleted file mode 100644
index 3cc53ad..0000000
--- a/README.md
+++ /dev/null
@@ -1,43 +0,0 @@
-[](http://melpa.org/#/focus)
-# Focus
-
-Focus provides `focus-mode` that dims the text of surrounding sections, similar to [iA Writer's](https://ia.net/writer) Focus Mode.
-
-## Installation
-
-You can install Focus using elpa. It's available on [melpa](http://melpa.milkbox.net/):
-
- M-x package-install focus
-
-The package has only been tried on Emacs 24.4 and 24.5, but should work on Emacs 24 or higher.
-
-## Usage
-
-Enable the `focus-mode` with M-x focus-mode .
-
-Also, `focus-read-only-mode` is provided, which is a mode optimized for continuous reading. It inhibits change in the buffer, hides the cursor and provides bindings for moving between *things* (defined in [Thing At Point](http://emacswiki.org/emacs/ThingAtPoint)). One can toggle `focus-read-only-mode` with M-x focus-read-only-mode or C-c C-q if `focus-mode` is enabled.
-
-Some bindings for simple navigation and exiting `focus-read-only-mode` are provided.
-
-Keybinding | Description
--------------------|----------------------------
- n | Jump to next *thing*
- SPC | Jump to next *thing*
- p | Jump to previous *thing*
- S-SPC | Jump to previous *thing*
- i | Exit `focus-read-only-mode`
- q | Exit `focus-read-only-mode`
-
-## Configuring
-
-The amount of dimness can be customized by setting the `focus-dimness` variable, where a positive integer indicates a more dim color (i.e. more blended with the background color of your theme), and a negative integer indicates a less dim color.
-
-Focus uses the [Thing At Point](http://emacswiki.org/emacs/ThingAtPoint) library to choose what section should be in focus. By default, modes derived from `prog-mode` uses `defun`, and modes derived from `text-mode` uses `sentence`. This a customizable by setting the `focus-mode-to-thing` variable, which is a list containing pairs on the form `(mode . thing)`.
-
-### Example
-
-This is what it looks like:
-
-Light Theme (leuven) | Dark Theme (monokai)
-:---------------------------------------:|:---------------------------------------:
-
| 
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..5d39115
--- /dev/null
+++ b/README.org
@@ -0,0 +1,87 @@
+[[https://melpa.org/#/focus][file:https://melpa.org/packages/focus-badge.svg]]
+[[https://stable.melpa.org/#/focus][file:https://stable.melpa.org/packages/focus-badge.svg]]
+
+* Focus
+
+ [[./focus-demo.gif]]
+
+ This is Focus, a package that dims surrounding text. It works with any theme
+ and can be configured to focus in on different regions like sentences,
+ paragraphs or code-blocks.
+
+* Installation
+
+ It's available on [[https://melpa.org/#/focus][MELPA]] and [[https://stable.melpa.org/#/focus][MELPA Stable]]:
+
+ #+BEGIN_EXAMPLE
+ M-x package-install focus
+ #+END_EXAMPLE
+
+* Usage
+
+ Enable ~focus-mode~ with ~M-x focus-mode~.
+
+ A few interactive functions are provided:
+
+ | Function | Description |
+ |--------------------+--------------------------------------------------------------------------|
+ | focus-change-thing | Adjust the narrowness of the focused section for the current buffer |
+ | focus-pin | Pin the focused section to its current location or the region, if active |
+ | focus-unpin | Unpin the focused section |
+ | focus-next-thing | Move the point to the middle of the Nth next thing |
+ | focus-prev-thing | Move the point to the middle of the Nth previous thing |
+
+ Focus relies on [[https://www.emacswiki.org/emacs/ThingAtPoint][Thing At Point]], which can retrieve a /thing/ surrounding the
+ point. These /things/ may be a symbol, list, S-expression (sexp), function
+ definition (defun), sentence, line, page and others. Calling ~M-x
+ focus-change-thing~ allows you to interactively change the kind of region
+ which should be in focus.
+
+** Focus read-only mode
+
+ Enable ~focus-read-only-mode~ with ~M-x focus-read-only-mode~, which is
+ optimized for continuous reading. It inhibits changes in a buffer, hides the
+ cursor and provides bindings for moving between /things/.
+
+ Some bindings for simple navigation and exiting `focus-read-only-mode` are
+ provided.
+
+ | Keybinding | Description |
+ |------------+-----------------------------|
+ | ~n~ | Jump to next /thing/ |
+ | ~SPC~ | Jump to next /thing/ |
+ | ~p~ | Jump to previous /thing/ |
+ | ~S-SPC~ | Jump to previous /thing/ |
+ | ~i~ | Exit ~focus-read-only-mode~ |
+ | ~q~ | Exit ~focus-read-only-mode~ |
+
+* Customization
+
+ The choice of what /thing/ is suitable for a mode may be configured by
+ setting the variable ~focus-mode-to-thing~. The default is
+
+ #+BEGIN_EXAMPLE
+ '((prog-mode . defun) (text-mode . sentence))
+ #+END_EXAMPLE
+
+ For modes inheriting ~prog-mode~ (which are most programming modes), the
+ default is the function-body, and for modes inheriting ~text-mode~, the
+ default is a sentence.
+
+ For instance, adding the following to your ~.emacs~-file:
+
+ #+BEGIN_SRC emacs-lisp
+ (add-to-list 'focus-mode-to-thing '(python-mode . paragraph))
+ #+END_SRC
+
+ changes ~python-mode~ to focus in on code-blocks with no blank lines rather
+ than the entire function.
+
+ According to [[https://www.reddit.com/r/emacs/comments/b1vrar/lsp_support_for_focusel_using_lspmode/][this reddit post]], Focus plays nice with ~lsp-mode~.
+
+** Faces
+
+ Focus offers two faces, one for the focused- and unfocused area. By default,
+ the ~focus-focused~ is the empty face, meaning there is no change, and
+ ~focus-unfocused~ inherits the comment face (which is usually subtle). The
+ faces can easily be customized via ~M-x list-faces-display~.
diff --git a/demo-dark.gif b/demo-dark.gif
deleted file mode 100644
index 94c1c28..0000000
Binary files a/demo-dark.gif and /dev/null differ
diff --git a/demo-light.gif b/demo-light.gif
deleted file mode 100644
index 59a63ab..0000000
Binary files a/demo-light.gif and /dev/null differ
diff --git a/focus-demo.gif b/focus-demo.gif
new file mode 100644
index 0000000..4a10b92
Binary files /dev/null and b/focus-demo.gif differ