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')
<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.
Thanks for this Wiki Ben. I also did a guide on using prose with DocPad from a beginner's perceptive here as a Google Doc: http://goo.gl/OoPLwC