Documentation should be collaborative like a wiki, but GitHub wikis suck at controlled collaboration, so by extracting the documentation out to its own repo and using Continuous Deployment, we can have the best of both worlds.

Below is a script that I'm using to host cassini-generated documentation on Heroku. It uses cassini as a module to regenerate the HTML from the current markdown contents at startup; enabling continuous deployment of the documentation: Just commit/pull request/merge and push and let the deploy webhooks take care of the rest. (video coming soon?)

var express =require('express')

,pkg =require('./package.json')

,cassini =require('cassini')

,path =require('path')

,app = express()

;

var port =process.env.PORT ||5000;

app.use(express.compress())

.use(express.static('bin'))

.get('/',function(req,res){

res.redirect(301, pkg.version+'/');

})

.listen(port);

console.log('listening on port %s', port);

cassini.generate({

inputDir: path.normalize(__dirname+'/src/')

,outputDir: path.normalize(__dirname+'/bin/')

,verbose:true

});

I'm hosting documentation with exactly the above code, for free, on Heroku. Take a look at the package.json and Procfile that bring it all together. All that remains is a CI/CD service. (I'm using drone.io)