Created Extending Caddy (markdown)

Extending-Caddy.md

@@ -0,0 +1,56 @@
+**[Join us on Slack](https://gophers.slack.com/messages/caddy/)** to chat with other Caddy developers! ([Request an invite](http://bit.ly/go-slack-signup), then join the #caddy channel.)
+
+
+Caddy can be extended to add missing functionality or integrate with third-party services. This makes Caddy not only a powerful web server, but also a platform from which web services can be consumed. For example, a monitoring company might want to make a middleware for Caddy so that site monitoring is built right into customers' web servers.
+
+We've made it easy for anyone who knows [Go](https://golang.org) to extend Caddy. (And if you don't know Go, it's a simple language to [learn](https://tour.golang.org).)
+
+## Steps for extending Caddy
+
+1. Create a Go package with a Setup function and, if writing middleware, an HTTP handler. [Example](https://github.com/abiosoft/hello-caddy/blob/master/hello.go).
+2. Test your code with the [caddydev](https://github.com/caddyserver/caddydev) tool, which runs Caddy with your package built in.
+3. To share your extension, [register it](https://github.com/caddyserver/buildsrv/blob/master/CONTRIBUTING.md) so it will appear on the Download page of the Caddy website.
+
+To be fair, you should probably open an issue to state your intention to extend Caddy before starting. That will help prevent overlapping efforts and keep the project in-line with its goals.
+
+## 1. Create a Go package
+
+Your package will either be a service or a middleware (or both). Services start a goroutine when the server starts, allowing it to run during the lifetime of the server. On the other hand, middleware injects an HTTP handler into the middleware chain to handle requests.
+
+Either way, your package will need a function called `Setup` with a signature like this:
+
+```go
+func Setup(c *setup.Controller) (middleware.Middleware, error) {
+    // ...
+}
+```
+
+Using the `Controller` that is passed in, you can parse Caddyfile input and start goroutines at startup and do other useful things. If your package is only a service you may simply return nil for both values.
+
+If your package is a middleware, you must return a function that returns a handler, like so:
+
+```go
+func Setup(c *setup.Controller) (middleware.Middleware, error) {
+	return func(next middleware.Handler) middleware.Handler {
+		// ...
+	}, nil
+}
+```
+
+For more information about how to use the Controller, read the [godoc for setup.Controller](http://godoc.org/github.com/mholt/caddy/config/setup#Controller). For help on how to make your HTTP handler, see the article [Writing Middleware](https://github.com/mholt/caddy/wiki/Writing-Middleware).
+
+
+## 2. Test your code with caddydev
+
+Right, so you've written your code. Does it work? Write tests. Do the tests pass? Good. Time to plug it into Caddy. Use [caddydev](https://github.com/caddyserver/caddydev) to make this easy. Just install the tool, then `cd` into your package folder and run `caddydev directive` (where `directive` is the directive word you intend to use). This automatically places your middleware at the end of the chain, but you can use the `-after` option to specify where in the chain you want it to go.
+
+That will run Caddy with your middleware. Try it! (Don't forget to use it in your Caddyfile!)
+
+
+## 3. Add it to the Caddy website
+
+Finally, you're ready to put it on the Caddy website for others to use. Just review the [terms and stuff for registering your add-on](https://github.com/caddyserver/buildsrv/blob/master/CONTRIBUTING.md) and then follow the simple instructions there. All it takes is a one-line pull request.
+
+Accepted registrations will be available to all downloaders, which means that anyone downloading Caddy from the website or automated environments will have the option of using your new feature.
+
+Now go make awesome things!