Skip to content
Permalink
Browse files

Document github_deploy usage

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
  • Loading branch information
Kwpolska committed Dec 24, 2015
1 parent edfbba3 commit 35bb6c80632bffb6c01786d438cf99e11f88e4ef
Showing with 52 additions and 15 deletions.
  1. +52 −15 docs/manual.txt
@@ -1158,21 +1158,58 @@ GitHub pages. The command builds the site, commits the output to a gh-pages
branch and pushes the output to GitHub. Nikola uses the `ghp-import command
<https://github.com/davisp/ghp-import>`_ for this.

The branch to use for committing the sources can be changed using the
``GITHUB_DEPLOY_BRANCH`` option in your config. For a
user.github.io/organization.github.io, this MUST be set to ``master``,
and the branch containing the sources must be changed to something
else, like ``src``, using the ``GITHUB_SOURCE_BRANCH`` option. The
remote name to which the changes are pushed is ``origin`` by default,
and can be changed using the ``GITHUB_REMOTE_NAME`` option. You also,
obviously, need to have ``git`` on your PATH, and should be able to
push to the repository specified as the remote.

This command performs the following actions, when it is run:

1. Builds the site
2. Commit the output folder to the ``GITHUB_DEPLOY_BRANCH`` to this branch.
3. Push the branch to the remote specified in ``GITHUB_REMOTE_NAME``!
In order to use this feature, you need to configure a few things first. Make
sure you have ``nikola`` and ``git`` installed on your PATH.

1. Initialize a Nikola site, if you haven’t already.
2. Initialize a git repository in your Nikola source directory by running:

.. code:: text

git init .
git remote add origin git@github.com:user/repository.git

3. Setup branches and remotes in ``conf.py``:

* ``GITHUB_DEPLOY_BRANCH`` is the branch where Nikola-generated HTML files
will be deployed. It should be ``gh-pages`` for project pages and
``master`` for user pages (user.github.io).
* ``GITHUB_SOURCE_BRANCH`` is the branch where your Nikola site source will be
deployed. We default to ``master``, but user pages should use ``src`` or
something else.
* ``GITHUB_REMOTE_NAME`` is the remote to which changes are pushed.

4. Create a ``.gitignore`` file. We recommend adding at least the following entries:

.. code:: text

cache
.doit.db
__pycache__
output

5. Switch to your source branch (if necessary) and commit to your source branch:

.. code:: text

git checkout -b src
git add .
git commit -am "Initial commit"

6. Run ``nikola github_deploy``. This will build the site, commit the output
folder to your deploy branch, and push to GitHub. Your website should be up
and running within a few minutes.
7. You should push your source branch to GitHub, too — this way, you have a
backup in case of catastrophic disk failure, and you can work on your
website from around the world.

.. code:: text

git push -u origin src

If you want to use a custom domain, create your ``CNAME`` file in
``files/CNAME`` on the source branch. Nikola will copy it to the
output directory.

Comments and Annotations
------------------------

0 comments on commit 35bb6c8

Please sign in to comment.
You can’t perform that action at this time.