balupton/README.md

## README.md

      
    Raw
  

              README.md
            
          
    Use DocPad, GitHub and Prose as a Wiki

This guide will walk you through how you can use a GitHub repository to house your wiki content, have DocPad render it, and automatically update on changes. It's also really nice as we get to benefit from the github project workflow for our wiki, that is issues, pull requests, etc.
We use this workflow heavily by linking the DocPad Website and the DocPad Documentation repositories allowing us to have users edit and submit pull requests for improvements to our documentation, and once merged, the website regenerates automatically.
1. Create a new repository for your Wiki Content

If you already have an existing existing project wiki - like this one - that you would like to push the contents of to your new repository, you can do the following:
git clone https://github.com/bevry/docpad.wiki.git old
cd old
git remote add new https://github.com/bevry/docpad-documentation.git
git push new master
cd ..
rm -Rf old

Update the remote URLs with what you need.
2. Install the RepoCloner plugin to your DocPad Website

Follow the installation instructions to get it to clone out your new repository.
3. Setup the GitHub Post Receive Hook so our DocPad Website automatically regenerates when the wiki changes


Go to this page on your new wiki repository: https://github.com/bevry/docpad-documentation/settings/hooks


Add a webhook to the location: http://YOUR-WEBSITE/regenerate?key=ANY-RANDOM-KEY-YOU-LIKE


Add our webhook key to our host environment. On heroku you do this like so: heroku config:set WEBHOOK_KEY=THE-RANDOM-KEY-YOU-CHOSE


Add the following to your DocPad Configuration File
# DocPad Events
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,express} = opts
		docpad = @docpad
		request = require('request')

		# DocPad Regenerate Hook
		# Automatically regenerate when new changes are pushed to our documentation
		server.all '/regenerate', (req,res) ->
			if req.query?.key is process.env.WEBHOOK_KEY
				docpad.log('info', 'Regenerating for documentation change')
				docpad.action('generate')
				res.send(200, 'regenerated')
			else
				res.send(400, 'key is incorrect')


4. Add an edit link to your page

<a href="<%- 'https://github.com/bevry/docpad-documentation/edit/master/' + @document.relativePath.replace('docs/','') %>">
	Edit and improve this page via GitHub!
</a>
- or -
<a href="<%- 'http://prose.io/#bevry/docpad-documentation/edit/master/' + @document.relativePath.replace('docs/','') %>">
	Edit and improve this page via Prose!
</a>
Replace docs/ with whatever directory you're cloning the repository to.