diff --git a/README b/README.md
similarity index 64%
rename from README
rename to README.md
index d7e1ec7..d6b7e08 100644
--- a/README
+++ b/README.md
@@ -1,23 +1,20 @@
-nbd-proxy
-=========
+# nbd-proxy
 
 Prototype javascript+websocket NBD server; this code demonstrates a javascript
 NBD implementation connected to the kernel nbd device over a websocket.
 
 There are two components here:
 
-  nbd-proxy: a little binary to initialise a nbd client, connected to a
-             unix domain socket, then proxy data between that socket and
-             stdio. This can be used with a websocket proxy to expose
-             that stdio as a websocket.
+nbd-proxy: a little binary to initialise a nbd client, connected to a unix
+domain socket, then proxy data between that socket and stdio. This can be used
+with a websocket proxy to expose that stdio as a websocket.
 
-  nbd.js:    a javascript implementation of a NBD server.
+nbd.js: a javascript implementation of a NBD server.
 
-Running
--------
+## Running
 
-You'll need a websocket proxy This connects the nbd-proxy
-component to a websocket endpoint.
+You'll need a websocket proxy This connects the nbd-proxy component to a
+websocket endpoint.
 
 For experimentation, I use the `websocketd` infrastrcture to expose the
 websocket endpoint, plus serve the static HTML+js client:
@@ -32,30 +29,28 @@
 Note that this type of invocation is very insecure, and intended just for
 experimentation. See the Security section below.
 
-For real deployments, you want your websocket-enabled service to run
-nbd-proxy, and connect its stdio to a websocket, running in binary mode. Your
-web interface will interact with this using an instance of the NBDServer object
-(defined in web/js/nbd.js):
+For real deployments, you want your websocket-enabled service to run nbd-proxy,
+and connect its stdio to a websocket, running in binary mode. Your web interface
+will interact with this using an instance of the NBDServer object (defined in
+web/js/nbd.js):
 
     var server = NBDServer(endpoint, file);
     server.start();
 
 - where endpoint is the websocket URL (ws://...) and file is a File object. See
-web/index.html for an example.
+  web/index.html for an example.
 
-Security
---------
+## Security
 
-This code allows potentially-untrusted clients to export arbitrary block
-device data to your kernel. Therefore, you should ensure that only trusted
-clients can connect as NBD servers.
+This code allows potentially-untrusted clients to export arbitrary block device
+data to your kernel. Therefore, you should ensure that only trusted clients can
+connect as NBD servers.
 
 There is no authentication or authorisation implemented in the nbd proxy. Your
 websocket proxy should implement proper authentication before nbd-proxy is
 connected to the websocket endpoint.
 
-State hook
-----------
+## State hook
 
 The nbd-proxy has a facility to run an program on state change. When a nbd
 session is established or shut down, the proxy will run the executable at