diff --git a/docs/api.md b/docs/api.md
index aa18ce9..f352e7d 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,4 +1,4 @@
-# Magic-Wormhole
+# The Magic-Wormhole API
 
 This library provides a mechanism to securely transfer small amounts
 of data between two computers. Both machines must be connected to the
diff --git a/docs/conf.py b/docs/conf.py
index 8949501..cabec8d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -20,6 +20,11 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+from recommonmark.parser import CommonMarkParser
+
+source_parsers = {
+    ".md": CommonMarkParser,
+}
 
 # -- General configuration ------------------------------------------------
 
@@ -38,8 +43,8 @@ templates_path = ['_templates']
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = '.md'
+source_suffix = ['.rst', '.md']
+#source_suffix = '.md'
 
 # The master toctree document.
 master_doc = 'index'
diff --git a/docs/index.md b/docs/index.rst
similarity index 59%
rename from docs/index.md
rename to docs/index.rst
index cd320b8..5f9308b 100644
--- a/docs/index.md
+++ b/docs/index.rst
@@ -3,13 +3,24 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Magic-Wormhole's documentation!
-==========================================
+Magic-Wormhole: Get Things From One Computer To Another, Safely
+===============================================================
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   introduction
+   attacks
+   tor
+
+   api
+   transit
+   server-protocol
+   client-protocol
+   file-transfer-protocol
+
+   journal
 
 
 Indices and tables
diff --git a/docs/introduction.md b/docs/introduction.md
index 7e2c255..a1e7f30 100644
--- a/docs/introduction.md
+++ b/docs/introduction.md
@@ -1,4 +1,4 @@
-# Magic-Wormhole
+# Introduction
 
 The magic-wormhole (Python) distribution provides several things: an
 executable tool ("bin/wormhole"), an importable library (`import wormhole`),
diff --git a/docs/server-protocol.md b/docs/server-protocol.md
index 3afb967..345f617 100644
--- a/docs/server-protocol.md
+++ b/docs/server-protocol.md
@@ -220,7 +220,7 @@ any), and which ones provoke direct responses:
 * S->C pong {pong: int}
 * S->C error {error: str, orig:}
 
-# Persistence
+## Persistence
 
 The server stores all messages in a database, so it should not lose any
 information when it is restarted. The server will not send a direct
diff --git a/docs/transit.md b/docs/transit.md
index 4cbda37..2ca7872 100644
--- a/docs/transit.md
+++ b/docs/transit.md
@@ -1,4 +1,4 @@
-= Transit Protocol =
+# Transit Protocol
 
 The Transit protocol is responsible for establishing an encrypted
 bidirectional record stream between two programs. It must be given a "transit
@@ -19,7 +19,7 @@ The other side will attempt to connect to each of those ports, as well as
 listening on its own socket. After a few seconds without success, they will
 both connect to a relay server.
 
-== Roles ==
+## Roles
 
 The Transit protocol has pre-defined "Sender" and "Receiver" roles (unlike
 Wormhole, which is symmetric/nobody-goes-first). Each connection must have
@@ -32,7 +32,7 @@ each side..
 
 This may be relaxed in the future, much as Wormhole was.
 
-== Records ==
+## Records
 
 Transit establishes a **record-pipe**, so the two sides can send and receive
 whole records, rather than unframed bytes. This is a side-effect of the
@@ -62,7 +62,7 @@ dropped. If a record is lost (e.g. the receiver observers records #1,#2,#4,
 but not #3), the connection is dropped when the unexpected sequence number is
 received.
 
-== Handshake ==
+## Handshake
 
 The transit key is used to derive several secondary keys. Two of them are
 used as a "handshake", to distinguish correct Transit connections from other
@@ -111,7 +111,7 @@ two handshakes), then making new connections to play back the recorded
 handshakes, but this level of attacker could simply drop the user's packets
 directly.
 
-== Relay ==
+## Relay
 
 The **Transit Relay** is a host which offers TURN-like services for
 magic-wormhole instances. It uses a TCP-based protocol with a handshake to
@@ -139,7 +139,7 @@ attempting to use the relay. If it has no viable direct hints, it will start
 using the relay right away. This prefers direct connections, but doesn't
 introduce completely unnecessary stalls.
 
-== API ==
+## API
 
 First, create a Transit instance, giving it the connection information of the
 transit relay. The application must know whether it should use a Sender or a
@@ -196,7 +196,7 @@ turns). However the blocking API does not provide a way to send records while
 waiting for an inbound record. This *might* work with threads, but it has not
 been tested.
 
-== Twisted API ==
+## Twisted API
 
 The same facilities are available in the asynchronous Twisted environment.
 The difference is that some functions return Deferreds instead of immediate