github/pelican
1
0
Fork 1
mirror of https://github.com/getpelican/pelican.git synced 2025-10-15 20:28:56 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #658 from elemoine/github

Browse source 
Improve Publishing to GitHub doc section
This commit is contained in:
Bruno Binet 2013-01-11 07:12:34 -08:00
commit e5be4b7e40
1 changed files with 62 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

97
docs/tips.rst
View file

@ -6,47 +6,80 @@ Here are some tips about Pelican that you might find useful.
Publishing to GitHub Publishing to GitHub
==================== ====================
GitHub comes with an interesting "pages" feature: you can upload things there `GitHub Pages <https://help.github.com/categories/20/articles>`_ offer an easy
and it will be available directly from their servers. As Pelican is a static and convenient way to publish Pelican sites. There are `two types of GitHub
file generator, we can take advantage of this. Pages <https://help.github.com/articles/user-organization-and-project-pages>`_:
*Project Pages* and *User Pages*. Pelican sites can be published as both
User Pages Project Pages and User Pages.
----------
GitHub allows you to create user pages in the form of ``username.github.com``.
Whatever is created in the master branch will be published. For this purpose,
just the output generated by Pelican needs to pushed to GitHub.
So given a repository containing your articles, just run Pelican over the posts
and deploy the master branch to GitHub::
$ pelican -s pelican.conf.py ./path/to/posts -o /path/to/output
Now add all the files in the output directory generated by Pelican::
$ git add /path/to/output/*
$ git commit -am "Your Message"
$ git push origin master
Project Pages Project Pages
------------- -------------
For creating Project pages, a branch called ``gh-pages`` is used for publishing.
The excellent `ghp-import <https://github.com/davisp/ghp-import>`_ makes this
really easy, which can be installed via::
$ pip install ghp-import 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.
Then, given a repository containing your articles, you would simply run The excellent `ghp-import <https://github.com/davisp/ghp-import>`_, which can
Pelican and upload the output to GitHub:: be installed with ``easy_install`` or ``pip``, makes this process really easy.
$ pelican -s pelican.conf.py . 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 $ ghp-import output
$ git push origin gh-pages $ git push origin gh-pages
And that's it. 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.
If you want, you can put that directly into a post-commit hook, so each time you .. note::
commit, your blog is up-to-date on GitHub!
Put the following into ``.git/hooks/post-commit``:: The ``github`` target of the Makefile created by the ``pelican-quickstart``
command publishes the Pelican site as Project Pages as described above.
pelican -s pelican.conf.py . && ghp-import output && git push origin gh-pages 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
<https://help.github.com/articles/setting-up-a-custom-domain-with-pages>`_ 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'),)