blohg, a Mercurial-based blogging engine¶

Motivation¶

Everybody knows that we have a large number of blogging engines lying around the blogosphere, but there are not a many choices for programmers, who are used to working daily with source-code editors and version control systems and may be more productive when blogging using these tools, instead of the fancy WYSIWYG editors and administration interfaces.

Actually this isn’t the first project trying to implement a VCS-based blogging engine, but most of the existing projects aren’t tied to a VCS and are just using text files that can be versioned with a VCS, without taking full advantage of the VCS’s revision history.

This project uses Mercurial as the VCS, reStructuredText as the markup language and Jinja2 as the template engine. All of these are pretty popular within the Python ecosystem and easy to use.

Basic concepts¶

Here are some of the basic concepts needed to understand how blohg works: In addition, you should know how Mercurial works, the reStructuredText syntax and the Jinja2 syntax.

Main features¶

These are some of the cool features of blohg:

• Support for static pages and posts.
• Support for tags for posts.
• Support for aliases, making it easy to migrate from some other blogging engine.
• Support for building a static version of the blog, to host it in restricted environments.
• Post/page metadata grabbed from the Mercurial repository.
• Plenty of reStructuredText directives available, to make the blogging experience as smooth as possible.
• Easily customizable by Jinja2 templates.
• Can be used as a full-featured CMS.
• Support for pagination for posts.
• Atom feeds for posts and tags.

Manually¶

Download the latest tarball from PyPI, extract it and run:

# python setup.py install

Using pip¶

To install blohg using pip, type:

# pip install blohg

If you want to use Git repositories, install a recent version of libgit2 (yeah, setuptools/distutils don’t know how to handle non-python dependencies. see the official documentation for instructions about how to install it on your operating system), and type:

# pip install blohg[git]

You should be careful about the version of libgit2 installed on your system. The major and minor versions of pygit2 should match the major and minor versions of libgit2, e.g. if the required version of pygit2 is 0.19.1, you need libgit2-0.19.*.

Gentoo Linux¶

There’s a Gentoo ebuild available in the main tree. Install it using:

# emerge -av www-apps/blohg

Initializing the repository¶

blohg will install a script called blohg for you. This script is able to create a new Mercurial (or Git) repository, using the default template and/or run the development server. It will be your main tool to interact with blohg.

To create a new repository, type:

$ blohg initrepo --repo-path my_blohg

Where my_blohg is the directory where the new repository will be created.

Make sure that the directory doesn’t exist, or is empty, before try to initialize the repository.

If you want to use Git instead of Mercurial, type:

$ blohg initrepo --repo-path my_blohg --git

When the repository is created, do the initial commit:

$ hg commit -Am 'initial commit'

Or for Git:

$ git add .
$ git commit -m 'initial commit'

my_blohg/
|-- config.yaml
|-- content
|   |-- about.rst
|   |-- attachments
|   |   `-- mercurial.png
|   `-- post
|       |-- example-post.rst
|       `-- lorem-ipsum.rst
|-- static
|   `-- screen.css
`-- templates
    |-- base.html
    |-- post_list.html
    `-- posts.html

Configuration options¶

You can heavily change the behavior of blohg by changing some configuration options.

These are the built-in configuration options for the config.yaml file:

The default values are used if the given configuration key is ommited (or commented out) from the config.yaml file.

Customizing your templates¶

If you look at the my_blohg directory you’ll see a templates directory. It stores some Jinja2 templates that are used by blohg.

Take a look at the Jinja2 documentation to learn how it works. The default templates provided by blohg initrepo are a good start point.

These are the blohg built-in variables globally available for your templates:

Static files¶

The static/ directory will store your static files, like CSS and images. You should avoid storing big files inside the Mercurial repository.

Dealing with search engines¶

blohg will disallow search engines from index your source files (/source/ path), creating a robots.txt file in the root of your blohg instance. If you isn’t running blohg from the root of your domain, you should make the requests pointing to /robots.txt redirect to /path-to-your-blohg/robots.txt in your webserver configuration.

If you don’t want this robots.txt file, you can just add the following content to your config.yaml file:

ROBOTS_TXT: False

Hiding reStructuredText sources¶

blohg enables a /source/ endpoint by default, that shows the reStructuredText source for any post/page of the blog. You can disable it by setting the SHOW_RST_SOURCE configuration parameter to False. It will raise a 404 error.

Using blohg as a CMS¶

You can use blohg to manage your “static” website, without the concept of blog posts. Actually the default setup of blohg is already pretty much like a CMS, but the initial page is a list of posts (or abstracts of posts), and you don’t want it if you don’t have blog posts at all.

You can use a static page as the initial page. You just need to save the text file as content/index.rst on your repository.

You can also use a static initial page for your blog, if you want, but you’ll need to create a menu link pointing to the page with the list of posts. You can use the views.posts endpoint to build it:

<a href="{{ url_for('views.posts') }}">Posts</a>

Listing posts by tag¶

Each tag will have its own HTML page with all the posts:

• http://example.org/tag/foo/
• http://example.org/tag/bar/

It is also possible to combine multiple tags and get a HTML page:

• http://example.org/tag/foo/bar/

Atom feeds¶

blohg generates an Atom feed for all the posts and/or tags.

To include all the posts (actually just the POSTS_PER_ATOM_FEED last posts), use the following URL:

http://example.org/atom/

For each tag, use URLs of this form:

• http://example.org/atom/foo/
• http://example.org/atom/bar/

For multiple combined tags, use URLs of this form:

• http://example.org/atom/foo/bar/

Facebook/Google+ integration¶

We provide Facebook/Google+ integration using Open Graph HTML meta-tags.

There’s a Jinja2 block available, that will add all the needed property tags for you. See _posts.html.

These are the property tags that will be created:

If you don’t want to use the default block, just remove the block call from your base.html template and write your own tags there. Use the default block, from _posts.html, as reference.

Tagging posts¶

blohg implements the concept of tags for posts. Tags are defined as a comma-separated list inside a reStructuredText comment in the post source:

.. tags: my,cool,tags

Put this comment wherever you want inside the post.

Overriding the creation date¶

blohg retrieves the creation date of each page and post from the Mercurial repository, using the date of the first commit of the source file on it. If you want to override this date, just insire the UNIX timestamp of the desired date inside a reStructuredText comment:

.. date: 1304124215

A more readable timestamp format is also allowed (YYYY-MM-DD HH:MM:SS):

.. date: 2011-04-30 00:43:35

Timestamps should be in UTC.

This is useful if you want to migrate content from another blog.

Scheduling the post/page for a future date¶

If you want to have a post/page published in a future date automatically, you can add the same reStructuredText comment of the previous section, but with the timestamp of the future date. The page/post will not be listed until that date.

Overriding the post/page author¶

blohg retrieves the author of each post/page from the Mercurial repository, as it does with the creation date. This data can be used in templates through the variables post.author_name and post.author_email. To override this data, add a reStructuredText comment like this:

.. author: John <john@example.com>

Post aliases¶

When migrating from another blogging system or URL structure, you can have blohg redirect your readers to the new URL’s by providing your posts with URL aliases. If you need this, insert a reStructuredText comment with a comma separated list of the aliases for the post like this:

.. aliases: /my-old-post-location/,/another-old-location/

By default, blohg will issue a 302 (temporary) redirection. If you want, you can have blohg issue a 301 (permanent) redirection instead like this:

.. aliases: 301:/my-old-post-location/,/another-old-location/

The 301: prefix is per URL and must be repeated for every URL you wish to 301 redirect.

Adding attachments¶

You may want to add some images and attach some files to your posts/pages. To atach a file, just put it in the directory content/attachments of your Mercurial repository and use one of the custom reStructuredText directives and roles below in your post/page.

.. attachment-image:: mercurial.png

.. attachment-figure:: mercurial.png

This is the attachment link: :attachment:`mercurial.png`
This is the attachment link: :attachment:`mercurial.png|link to file`

Additional reStructuredText directives/interpreted text roles¶

These are additional custom directives, that add some interesting functionality to the standard reStructuredText syntax.

.. youtube:: erPnyi90cIc
   :align: center
   :height: 344
   :width: 425

.. vimeo:: 2539741
   :align: center
   :height: 344
   :width: 425

.. code:: python

    print "Hello, World!"

.. raw:: html

    <script type="text/javascript" src="http://alexgorbatchev.com/pub/sh/current/scripts/shCore.js"></script>
    <script type="text/javascript" src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushPython.js"></script>
    <link type="text/css" rel="stylesheet" href="http://alexgorbatchev.com/pub/sh/current/styles/shCoreDefault.css"/>
    <script type="text/javascript">SyntaxHighlighter.defaults.toolbar=false; SyntaxHighlighter.all();</script>

.. sourcecode:: python
   :linenos:

    print "Hello, World!"

$ pygmentize -S friendly -f html > static/pygments.css

<link type="text/css" media="screen" rel="stylesheet" href="{{
    url_for('static', filename='pygments.css') }}" />

.. math::

    \\frac{x^2}{1+x}

.. include:: somefile.txt

.. subpages::

.. subpages:: projects

.. subpages::
   :sort-by: slug
   :sort-order: desc

This is the :page:`posts/my-first-blog-post`
This is my :page:`Introduction Post <posts/my-first-blog-post>`

Previewing your post/page¶

After writing your post/page you will want to preview it in your browser. You should use the blohg script to run the development server:

$ blohg runserver --repo-path my_blohg

Supposing that your Mercurial repository is the my_blohg directory.

If the blohg script is running on the debug mode, which is the default, it will load all the uncommited content available on your local copy.

If you disable the debug mode (--no-debug option), it will only load the content that was already commited. This is the default behavior of the application when running on the production server.

For help with the script options, type:

$ blohg runserver -h

Commiting your post/page¶

After finishing your post and previewing it in your browser, commit your reStructuredText to the repo as usual.

Using a WSGI app¶

At this point you should have a Mercurial repository with your blog ready to be deployed.

Copy it to your remote server as usual. e.g. using ssh:

$ hg clone my_blohg ssh://user@yourdomain.tld/path/to/my_blohg/

Supposing that your Mercurial repository is my_blohg.

Don’t forget to add the remote path to your local my_blohg/.hg/hgrc [paths] section.

The blohg deployment process is similar to any other Flask-powered application. Take a look at the Flask deployment documentation:

http://flask.pocoo.org/docs/deploying/

To create your Flask app object, use the following code:

from blohg import create_app
application = create_app('/path/to/my_blohg')

There’s a sample blohg.wsgi file (for Apache mod_wsgi) available here:

https://github.com/rafaelmartins/blohg/blob/master/share/blohg.wsgi

Using static pages¶

You can use the freeze command to generate a static version of your blog. This will create a build directory with the content of your blog as static pages. This way, you can put those pages (via ftp, rsync, hg, ...) on a static hosting provider.

--serve¶

This option will serve your generated pages as a local web server. This can be used to check that all links works fine, or that all content has been generated.

--noindex¶

This option will generate your post as html files rather than as directories containing a index.html file.

Simple extension example¶

Save the code bellow as blohg_hello.py, somewhere in your python path:

# -*- coding: utf-8 -*-

from blohg.ext import BlohgBlueprint, BlohgExtension

ext = BlohgExtension(__name__)
hello = BlohgBlueprint('hello', __name__, url_prefix='/hello')

@hello.route('/')
def home():
    return 'Hello world!'


@ext.setup_extension
def setup_extension(app):
    app.register_blueprint(hello)

Add the following content to your config.yaml file:

EXTENSIONS:
    - hello

And run your development server:

$ blohg runserver

If everything is ok, you should see a “Hello World”, if you point your browser at http://127.0.0.1:5000/hello/.

Running extensions from repository¶

If you want to run an extension from the repository, you should create an ext (configurable using the EXTENSIONS_DIR variable in your configuration file) directory at the root of the repository and place the extensions there. The extension setup is the same as explained above.

Extensions shipped inside the repository are called “embedded extensions”, and you need to enable them explicitly in your WSGI script, to avoid security issues. Replace the create_app call with something like this:

application = create_app('/path/to/your/repository', embedded_extensions=True)

From <=0.5.1¶

blohg 0.6 introduces support to Flask 0.7, that comes with some backwards incompatibilities.

You’ll need to run the flask-07-upgrade.py script inside your blog repository to fix your templates, as described in the Flask documentation:

http://flask.pocoo.org/docs/upgrading/#version-0-7

From <=0.9.2¶

blohg 0.10 introduces Facebook/Google+ integration using the Open Graph protocol.

See _posts.html, or just add the following content to your base.html template, inside of the <head> and </head> tags:

<!-- begin opengraph header -->
{% block opengraph_header %}{% endblock %}
<!-- end opengraph header -->

blohg 0.10 uses jinja2.Markup to return HTML content from the models, deprecating the usage of the safe filter. You may want to fix your templates:

--- a/templates/posts.html
+++ b/templates/posts.html
@@ -21,9 +21,9 @@

 <!-- begin html parsed by docutils -->
 {% if full_content -%}
-    {{ post.full_html|safe }}
+    {{ post.full_html }}
 {% else -%}
-    {{ post.abstract_html|safe }}
+    {{ post.abstract_html }}
 {%- endif %}
 <!-- end html parsed by docutils -->

The directive .. include:: was patched and will just have access to files from the Mercurial repository for now. This change improves the security, avoiding the access of files from the host filesystem, and makes it possible to include files inside the repository. Please remove any calls of this directive that were using files outside the repository.

Authors¶

blohg is written and maintained by Rafael G. Martins and various contributors: