Skip to content
Browse files

Update github_deploy instructions in the manual

Signed-off-by: Chris Warrick <>
  • Loading branch information
Kwpolska committed Dec 24, 2015
1 parent 3405df9 commit d2f5054e6914e403af30dba98478dc49223ed3eb
Showing with 53 additions and 16 deletions.
  1. +53 −16 stories/manual.txt
@@ -1102,25 +1102,62 @@ Deploying to GitHub

Nikola provides a separate command ``github_deploy`` to deploy your site to
GitHub pages. The command builds the site, commits the output to a gh-pages
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
<>`_ for this.

The branch to use for committing the sources can be changed using the
``GITHUB_DEPLOY_BRANCH`` option in your config. For a, this MUST be set to ``master``,
and the branch containing the sources must be changed to something
else, like ``deploy``, 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

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

* ``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 (
* ``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


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

1 comment on commit d2f5054


This comment has been minimized.

Copy link

@jean jean commented on d2f5054 Dec 24, 2015

Cool :-) This addresses all the issues I came across setting up my Hello world page.

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