diff --git a/Makefile b/Makefile
index 776afcb..1a7e97b 100644
--- a/Makefile
+++ b/Makefile
@@ -21,6 +21,14 @@ compile: $(OBJS)
 test:
 	$(CASK) exec $(EMACSBATCH) -L . -l sudo-edit-test.el -f ert-run-tests-batch-and-exit
 
+README.md: make-readme-markdown.el sudo-edit.el
+	$(CASK) exec $(EMACSBATCH) --script $< <sudo-edit.el >$@ 2>/dev/null
+
+make-readme-markdown.el:
+	$(WGET) -q -O $@ "https://raw.github.com/mgalgs/make-readme-markdown/master/make-readme-markdown.el"
+
+.INTERMEDIATE: make-readme-markdown.el
+
 clean: clean-elc
 
 clean-elc:
diff --git a/README.md b/README.md
index 113af5d..8c5ab81 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,72 @@
-sudo-edit
-=========
+<a href="https://github.com/nflath/sudo-edit"><img src="https://www.gnu.org/software/emacs/images/emacs.png" alt="Emacs Logo" width="80" height="80" align="right"></a>
+## sudo-edit.el
+*Open files as another user*
 
-Utilities for opening files with sudo
+---
+[![MELPA](http://melpa.org/packages/sudo-edit-badge.svg)](http://melpa.org/#/sudo-edit)
+[![MELPA Stable](http://stable.melpa.org/packages/sudo-edit-badge.svg)](http://stable.melpa.org/#/sudo-edit)
+
+This package allows to open files as another user, by default "root":
+
+    M-x sudo-edit
+
+Suggested keybinding:
+
+    (global-set-key (kbd "C-c C-r") 'sudo-edit)
+
+Installation:
+
+To use this mode, put the following in your init.el:
+
+    (require 'sudo-edit)
+
+
+
+### Customization Documentation
+
+#### `sudo-edit-user`
+
+Default user to edit a file with `sudo-edit`.
+
+#### `sudo-edit-local-method`
+
+Tramp method to use with `sudo-edit` for local files.
+
+#### `sudo-edit-remote-method`
+
+Tramp method to use with `sudo-edit` for remote files.
+
+### Function and Macro Documentation
+
+#### `(sudo-edit-set-header)`
+
+*Display a warning in header line of the current buffer.
+This function is suitable to add to `find-file-hook` and `dired-file-hook`.
+
+#### `(sudo-edit-tramp-get-parameter VEC PARAM)`
+
+Return from tramp VEC a parameter PARAM.
+
+#### `(sudo-edit-out-of-band-ssh-p FILENAME)`
+
+Check if tramp FILENAME is a out-of-band method and use ssh.
+
+#### `(sudo-edit-filename FILENAME USER)`
+
+Return a tramp edit name for a FILENAME as USER.
+
+#### `(sudo-edit &optional ARG)`
+
+Edit currently visited file as another user, by default `sudo-edit-user`.
+With a prefix ARG prompt for a file to visit.  Will also prompt
+for a file to visit if current buffer is not visiting a file.
+
+#### `(sudo-edit-find-file FILENAME)`
+
+Edit FILENAME as another user, by default `sudo-edit-user`.
+
+-----
+<div style="padding-top:15px;color: #d0d0d0;">
+Markdown README file generated by
+<a href="https://github.com/mgalgs/make-readme-markdown">make-readme-markdown.el</a>
+</div>
diff --git a/sudo-edit.el b/sudo-edit.el
index 4202114..5735465 100644
--- a/sudo-edit.el
+++ b/sudo-edit.el
@@ -31,7 +31,7 @@
 
 ;; This package allows to open files as another user, by default "root":
 ;;
-;;     `sudo-edit'
+;;     M-x sudo-edit
 ;;
 ;; Suggested keybinding:
 ;;