2 files changed, 29 insertions, 25 deletions
diff --git a/middleware.md b/middleware.md
index 711d9c4ad..cef243198 100644
--- a/middleware.md
+++ b/middleware.md
@@ -1,4 +1,6 @@
-# Writing middleware
+# Middleware
+
+## Writing Middleware
 
 From the Caddy docs:
 
@@ -26,3 +28,29 @@ So CoreDNS treats:
 
 as special and will then assume nothing has written to the client. In all other cases it is assumes
 something has been written to the client (by the middleware).
+
+## Hooking it up
+
+TODO(miek): text here on how to hook up middleware.
+
+# Documentation
+
+Each middleware should have a README.md explaining what the middleware does and how it is
+configured. The file should have the following layout:
+
+* Title: use the middleware's name
+* Subsection titled: "Syntax"
+* Subsection titled: "Examples"
+
+More sections are of course possible.
+
+## Style
+
+We use the Unix manual page style:
+
+* The name of middleware in the running text should be italic: *middleware*.
+* all CAPITAL: user supplied argument, in the running text references this use strong text: `**`:
+  **EXAMPLE**.
+* Optional text: in block quotes: `[optional]`.
+* Use three dots to indicate multiple options are allowed: `arg...`.
+* Item used literal: `literal`.
diff --git a/middleware/middleware.md b/middleware/middleware.md
deleted file mode 100644
index 928829397..000000000
--- a/middleware/middleware.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Middleware
-
-
-# Documentation
-
-Each middleware should have a README.md explaining what the middleware does and how it is
-configured. The file should have the following layout:
-
-* Title: use the middleware's name
-* Subsection titled: "Syntax"
-* Subsection titled: "Examples"
-
-More sections are of course possible.
-
-## Style
-
-We use the Unix manual page style:
-
-* The name of middleware in the running text should be italic: *middleware*.
-* all CAPITAL: user supplied argument, in the running text references this use strong text: `**`:
-  **EXAMPLE**.
-* Optional text: in block quotes: `[optional]`.
-* Use three dots to indicate multiple options are allowed: `arg...`.
-* Item used literal: `literal`.