Skip to content

Instantly share code, notes, and snippets.

@balupton
Last active April 29, 2019 11:57
Show Gist options
  • Save balupton/5519403 to your computer and use it in GitHub Desktop.
Save balupton/5519403 to your computer and use it in GitHub Desktop.
DocPad: Use DocPad, GitHub & Prose as a Wiki

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

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

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

  3. 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

  4. 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.

@mikeumus
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment