Deploying
Tinkerer generates a static website under blog/html. The files can be uploaded anywhere. A couple of options are GitHub Pages and Bitbucket.
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.
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:
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:
The URL you requested was not found.
====================================
.. comments::
Your own text.
Add an file 403.rst to the document root:
403 Permission Denied
=====================
.. comments::
Your own text.
And add these two pages to the master.rst file:
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 you can add custom JavaScript code by placing an file named page.html under _templates/page.html:
{% extends "!page.html" %}
{% block footer %}
{{ super() }}
{% include "../_static/piwik.js" %}
{% endblock %}
And the analytics code inside _static/piwik.js:
<!-- 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 Tinkerer Reference.
