January 04, 2012

Blogging using tinkerer on bitbucket

Tinkerer is an blogging tool using Sphinx. It allows writing in reStructuredText format, docutils features like a code highlight and various Sphinx extensions.

Hosting on Bitbucket

Since reStrucutredText is just text files, easy to manage using Source Code Management tool such as git or mercurial.

Bitbucket is an hosting service of git/mercurial. It can serve static html files if these are under <username>.bitbucket.org repository.

This repository could be private. Repository is private but html files are visible from browsers. So I can hide my drafts from the world. Of course, bitbucket serve unlimited private repositories!

  1. Create a repository on Bitbucket
    • <username>.bitbucket.org (private repository)
  2. Create tinkerer post
% hg clone ssh://hg@bitbucket.org/<username>/<username>.bitbucket.org
% cd <username>.bitbucket.org
% tinker -s  # initial setting
% vi conf.py
  (Edit title and so on)
% tinker -p "first post"  # create an rst file
% vi 2012/01/04/first_post.rst
  (edit, edit, edit)
% tinker -b  # build html files

tinker -b create html files under blog/html directory.

  1. commit and push
% hg add .
% hg commit -m "add first post"
% hg push

That's it! Easy!

Tinkerer create index.html file at the setup. It includes refresh to the ./blog/html/index.html, then browser move to the right URL.

Use branch

The repository is private. However, If a direct URL is specified to get something such as conf.py, anyone can get it.

To avoid this, use branches such as

  • default branch
    • It containes only html files.
  • drafts branch
    • It contains all of files like conf.py and drafts.

Since Bitbucket only publish default branch, your conf.py and drafts are safe.

How to write blogs

Mainly, you should use drafts branch. Edit and build htmls. When you want to publish, change branch to "default" and merge drafts, commit and push to the bitbucket.

% hg update drafts
(edit edit edit)
% tinker -b
% hg commit  # commit the latest entry
% hg update default  # change branch to default
% hg merge drafts  # merge from drafts
% hg commit  # commit the merge
% hg push

Its' seems a little complicated, but not so bad.

Posted by r_rudi
Filed under: Sphinx
Tags: tinkerer, bitbucket