how to handle routes in Docpad

This should be really obvious but I just cant get my head around it

How do I add extra routes in Docpad??

Im looking for the Docpad equivalent to express.js's

app.post("*", function(res,req,next){
//Do stuff
}

As far as I can understand I need to create a plugin module for this? How do I tell Docpad to use my routes? Im guessing it has something to do with the extend-server event, do I put that as parameter in docpad.coffee?

How do I pass the req object to my route handler?

can I force docpad to always consider my routing first? kinda like middleware? can I pass a (processed) url back to docpads standard routing? how?

Are you looking for something like this:

server.get /list\/[a-zA-Z]+/, (req,res,next) ->
                document = docpad.getCollection('documents').findOne({relativeOutPath: 'index.html'});
                docpad.serveDocument({
                    document: document,
                    req: req,
                    res: res,
                    next: next,
                    statusCode: 200
                });

This is an event (server extend) in the docpad.coffee file. Its intercepting the request and testing it against a regex (could easily just be a plain url). The user will see the url they input but the index.html will be served.

Or closer to your case:

server.post "*", (req,res,next) ->
                #do stuff

inside docpad.coffee

events:

    # Server Extend
    # Used to add our own custom routes to the server before the docpad routes are added
    serverExtend: (opts) ->
        # Extract the server from the options
        {server} = opts
        docpad = @docpad

        # As we are now running in an event,
        # ensure we are using the latest copy of the docpad configuraiton
        # and fetch our urls from it
        latestConfig = docpad.getConfig()
        oldUrls = latestConfig.templateData.site.oldUrls or []
        newUrl = latestConfig.templateData.site.url

        server.post "*", (req,res,next) ->
          #do stuff