GitHub Pages Deployer Plugin for DocPad
Deploy to Github Pages easily via
docpad install ghpages
This plugin works with GitHub Pages for Projects (e.g.
gh-pages branch on
https://github.com/username/project) with no configuration or setup required.
docpad deploy-ghpages --env static to deploy the contents of your
out directory directly to your repository's
This plugin also works with GitHub Pages for Profiles and Organisations (e.g.
master branch on
https://github.com/username/username.github.io) via any of the following options:
Setup one repository called
username.github.io which will be your target repository, and one called
website which will be your source repository.
website repository, add the following to your docpad configuration file:
plugins: ghpages: deployRemote: 'target' deployBranch: 'master'
And run the following in terminal:
git remote add target https://github.com/username/username.github.io.git
Then when you run
docpad deploy-ghpages --env static inside your website repository, the generated
out directory will be pushed up to your target repository's
If you would like to have your source and generated site on the same repository, you can do this by the following.
Move the source of your website to the branch
source, and the following to your docpad configuration file:
plugins: ghpages: deployRemote: 'origin' deployBranch: 'master'
Then when you run
docpad deploy-ghpages --env static inside your website repository's
source branch, the generated
out directory will be pushed up to same repository's
Polluting the Root Directory
The final option is to not use this plugin and have the
out directory be your website's root directory, so instead of say
your-website/src/documents/index.html being outputted to
your-website/out/index.html, instead it will be outputted to
you-website/index.html. This is the way Jekyll works, however we don't recommend it as it is very messy and commits the out files into your repository.
To do this, add the following to your docpad configuration file:
If you're using GitHub Pages Custom Domains:
- Place your
src/files/CNAMEso it gets copied over to
out/CNAMEupon generation and consequently to the root of the
gh-pagesbranch upon deployment
- Use a DocPad version 6.48.1 or higher
Depending on circumstances, the github pages plugin might not work and you'll see an error. You can debug this by running the deploy with the
-d flag like so
docpad deploy-ghpages -d. That will tell you at which step the deploy failed.
If the deploy fails fetching the origin remote, it means that you do not have the remote "origin", you will need to add it, or update the
deployRemotesetting to reflect your desired remote.
If the deploy fails on the push to github pages, you may need to specify your username and password within the remote. You can do this by running:
node -e "console.log('https://'+encodeURI('USERNAME')+':'+encodeURI('PASSWORD')+'@github.com/REPO_OWNER/REPO_NAME.git')"
Replace the words in capitals with their actual values and press enter. This will then output the new remote URL, you then want to copy it and run
git remote rm originand
git remote add origin THE_NEW_URLand try the deploy again.
On OSX you may be able to avoid this step by running
git config --global credential.helper osxkeychainto tell git to save the passwords to the OSX keychain rather than asking for them every single time.
If you get EPERM or unlink errors, it means that DocPad does not have permission to clean up the git directory that it creates in the out folder. You must clean this up manually yourself by running
rm -Rf ./out/.git
These amazing people are maintaining this project:
- Benjamin Lupton email@example.com (https://github.com/balupton)
- Avi Deitcher (https://github.com/deitch)
- Sergey Lukin firstname.lastname@example.org (https://github.com/sergeylukin)
No sponsors yet! Will you be the first?
These amazing people have contributed code to this project:
- Avi Deitcher — view contributions
- Benjamin Lupton email@example.com — view contributions
- KyleAMathews — view contributions
- RobLoach — view contributions
- Sergey Lukin firstname.lastname@example.org — view contributions
Unless stated otherwise all works are:
and licensed under: