Improve Publishing to GitHub section of the doc

docs/tips.rst

@@ -6,47 +6,80 @@ Here are some tips about Pelican that you might find useful.
 Publishing to GitHub
 ====================
 
-GitHub comes with an interesting "pages" feature: you can upload things there
-and it will be available directly from their servers. As Pelican is a static
-file generator, we can take advantage of this.
-
-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
+`GitHub Pages <https://help.github.com/categories/20/articles>`_ offer an easy
+and convenient way to publish Pelican sites. There are `two types of GitHub
+Pages <https://help.github.com/articles/user-organization-and-project-pages>`_:
+*Project Pages* and *User Pages*. Pelican sites can be published as both
+Project Pages and User 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
-Pelican and upload the output to GitHub::
+The excellent `ghp-import <https://github.com/davisp/ghp-import>`_, which can
+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
     $ 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
-commit, your blog is up-to-date on GitHub!
+.. note::
 
-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'),)