Tips

Here are some tips about Pelican that you might find useful.

Publishing to GitHub

GitHub Pages offer an easy and convenient way to publish Pelican sites. There are two types of GitHub Pages: Project Pages and User Pages. Pelican sites can be published as both Project Pages and User Pages.

Project Pages

To publish a Pelican site as Project Pages you need to push the content of the output dir generated by Pelican to a repository’s gh-pages branch on GitHub.

The excellent ghp-import, which can be installed with easy_install or pip, makes this process really easy.

For example, if the sources of your Pelican site are contained in a GitHub repository, and if you want to publish your Pelican site as Project Pages of this repository, you can then use the following:

$ pelican content -o output pelicanconf.py
$ ghp-import output
$ git push origin gh-pages

The ghp-import output command updates the local gh-pages branch with the content of the output directory (creating the branch if it doesn’t already exist). The git push origin gh-pages command updates the remote gh-pages branch, effectively publishing the Pelican site.

Note

The github target of the Makefile created by the pelican-quickstart command publishes the Pelican site as Project Pages as described above.

User Pages

To publish a Pelican site as User Pages you need to push the content of the output dir generated by Pelican to the master branch of your <username>.github.com repository on GitHub.

Again, you can take advantage of ghp-import:

$ pelican content -o output pelicanconf.py
$ ghp-import output
$ git push git@github.com:elemoine/elemoine.github.com.git gh-pages:master

The git push command pushes the local gh-pages branch (freshly updated by the ghp-import command) to the elemoine.github.com repository’s master branch on GitHub.

Note

To publish your Pelican site as User Pages feel free to adjust the the github target of the Makefile.

Extra Tips

Tip #1:

To automatically update your Pelican site on each commit you can create a post-commit hook. For example, you can add the following to .git/hooks/post-commit:

pelican pelican content -o output pelicanconf.py && ghp-import output && git push origin gh-pages

Tip #2:

To use a custom domain with GitHub Pages you need to have a CNAME file at the root of your pages. For that you will add CNAME file to your content, dir and use the FILES_TO_COPY setting variable to tell Pelican to copy that file to the output dir. For example:

FILES_TO_COPY = (('extra/CNAME', 'CNAME'),)