Deploying
=========

Tinkerer generates a static website under ``blog/html``. The files can be
uploaded anywhere. A couple of options are `GitHub Pages <pages.github.com>`_
and `Bitbucket <http://www.bitbucket.org>`_.

Hosting on GitHub
-----------------

Create a repository named ``$(USERNAME).github.io`` where ``$(USERNAME)`` is
your GitHub username, for example ``johndoe.github.io``. If you create such a
repository, when accessing ``http://johndoe.github.io``, GitHub will
automatically serve the ``index.html`` found under the root of the repository.

You can also easily create websites for individual projects, by creating a
``gh-pages`` branch and placing the blog there. More information on GitHub
`here <https://help.github.com/categories/20/articles>`_.

Please note that you must create an empty ``.nojekyll`` file in the project
root. By default, GitHub Pages runs Jekyll on the files (not needed for
Tinkerer), unless ``.nojekyll`` is present. This causes some issues as Jekyll
ignores files and folders which start with an underscore, like Tinkerer static
folder (``_static``).

Hosting on Bitbucket
--------------------

Create a repository named ``$(USERNAME).bitbucket.org`` where ``$(USERNAME)``
is your Bitbucket username, for example ``johndoe.bitbucket.org``. If you
create such a repository, when accessing ``http://johndoe.bitbucket.org``,
Bitbucket will automatically serve the ``index.html`` found under the root of
the repository. The repository name **must** include ``.bitbucket.org``, so in
the example above the actual repository URL would be
``http://bitbucket.org/johndoe/johndoe.bitbucket.org/``.

Deployment options
------------------

You have two options: you can either deploy only the built html or you can
deploy everything, including sources, ``conf.py``, html etc.

Upload HTML only
~~~~~~~~~~~~~~~~

Commit the content of your blog's ``blog/html`` directory to the repository.
The ``index.html`` file generated by Tinkerer is the front page of your blog.

.. note::
    Make sure to update the ``website`` variable in ``conf.py`` to
    ``http://johndoe.bitbucket.org/`` so the RSS feed can properly link your
    posts.

Upload both HTML and sources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Commit your whole blog to the repository, including files in the root directory
and source. Tinkerer generates an ``index.html`` file in the blog's root which
redirects to ``blog/html/index.html`` to enable this scenario.

.. note::
    Make sure to update the ``website`` variable in ``conf.py`` to
    ``http://johndoe.bitbucket.org/blog/html/`` so the RSS feed can properly
    link your posts. Note the trailing ``blog/html`` - the website variable
    must point to the root of your blog's *build* directory, not root
    directory.

Copying extra files to the html output directory
------------------------------------------------

Files placed in an folder named ``_copy`` will be
automatically copied to the html output directory.

This could be useful for an ``.htaccess`` file,
an ``robots.txt`` file or an extra ``favicon.ico``
etc.

Creating custom 404 and 403 error pages
---------------------------------------

If your webserver supports ``.htaccess`` files you can create these pages by placing
an ``.htaccess`` file under ``_copy/.htaccess`` with the following content:

.. code-block:: bash

  ErrorDocument 404 http://www.yoursite.com/404.html
  ErrorDocument 403 http://www.yoursite.com/403.html
  Options -Indexes

Add an file ``404.rst`` to the document root:

.. code-block:: rst

  The URL you requested was not found.
  ====================================

  .. comments::

  Your own text.

Add an file ``403.rst`` to the document root:

.. code-block:: rst

  403 Permission Denied
  =====================

  .. comments::

  Your own text.

And add these two pages to the ``master.rst`` file:

.. code-block:: rst

  Sitemap
  =======

  .. toctree::
    :hidden:

    404.rst
    403.rst

  .. toctree::
    :maxdepth: 1

    2012/04/21/a_blog_post
    pages/about

Adding custom analytics code
----------------------------

If you don't want to use Google Analytics and for example `Piwik <http://piwik.org/>`_
you can add custom JavaScript code by placing an file named ``page.html`` under
``_templates/page.html``:

.. code-block:: html

  {% extends "!page.html" %}

  {% block footer %}
      {{ super() }}
      {% include "../_static/piwik.js" %}
  {% endblock %}

And the analytics code inside ``_static/piwik.js``:

.. code-block:: html

  <!-- Piwik -->
  <script type="text/javascript">
  var pkBaseURL = (("https:" == document.location.protocol) ? "https://piwik.yoursite.com/piwik/" : "http://piwik.yoursite.com/piwik/");
  document.write(unescape("%3Cscript src='" + pkBaseURL + "piwik.js' type='text/javascript'%3E%3C/script%3E"));
  </script><script type="text/javascript">
  try {
  var piwikTracker = Piwik.getTracker(pkBaseURL + "piwik.php", 1);
  piwikTracker.trackPageView();
  piwikTracker.enableLinkTracking();
  } catch( err ) {}
  </script><noscript><p><img src="http://piwik.yoursite.com/piwik/piwik.php?idsite=1" style="border:0" alt="" /></p></noscript>
  <!-- End Piwik Tracking Code -->

Back to :ref:`tinkerer_reference`.
