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'),)