Writing blog pages/posts¶

blohg uses the standard reStructuredText syntax for pages and posts, with some additional directives.

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.

Warning

Make sure the date of your server is properly setup. Run NTP would be a good idea. :)

Warning

If your Mercurial repository is public (e.g. you have a hgweb instance running), people will be able to see the reStructuredText source before the publishing 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.

Directive `attachment-image`¶

Identical to the image directive, but loads the image directly from your content/attachments directory.

Usage example:

.. attachment-image:: mercurial.png

Directive `attachment-figure`¶

Identical to the figure directive, but loads the image directly from your content/attachments directory.

Usage example:

.. attachment-figure:: mercurial.png

Interpreted Text Role `attachment`¶

Interpreted Text Role that generates a link to the attachment (reference node). You can add a custom label for link after ‘|’.

Usage example:

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.

Directive `youtube`¶

reStructuredText directive that creates an embed object to display a video from YouTube.

Usage example:

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

Directive `vimeo`¶

reStructuredText directive that creates an embed object to display a video from Vimeo.

Usage example:

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

Directive `code`¶

reStructuredText directive that creates a pre tag suitable for decoration with http://alexgorbatchev.com/SyntaxHighlighter/

Usage example:

.. 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>

Directive `sourcecode`¶

reStructuredText directive that does syntax highlight using Pygments.

Usage example:

.. sourcecode:: python
   :linenos:

    print "Hello, World!"

The linenos option enables the line numbering.

To be able to use this directive you should generate a CSS file with the style definitions, using the pygmentize script, shipped with Pygments.

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

Where friendly will be your Pygments style of choice.

This file should be included in the main template, usually base.html:

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

This directive is based on rst-directive.py, created by the Pygments authors.

Directive `math`¶

reStructuredText directive that creates an image HTML object to display a LaTeX equation, using Google Chart API.

Usage example:

.. math::

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

Directive `include`¶

reStructuredText directive that reads a reStructuredText-formatted text file and parses it in the current document’s context at the point of the directive. The directive argument is the path to the file to be included, relative to the repository root.

This directive replaces the include directive, provided by docutils, that can be harmful when running on shared environments.

Usage example:

.. include:: somefile.txt

More detailed documentation can be viewed in the Docutils’ documentation.

This directive, unlike default implementation, will include files stored in the Mercurial repository.

The directive include-hg is an alias for this directive.

reStructuredText variables declared as comments in the included files are going to be ignored.

Directive `subpages`¶

reStructuredText directive that creates a bullet-list with the subpages of the current page, or of a given page.

Usage example:

.. subpages::

Or:

.. subpages:: projects

Supposing that you have a directory called content/projects and some reStructuredText files on it. Subdirectories are also allowed.

It is also possible to change the way the bullet-list is sorted, using the options sort-by and sort-order:

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

Available options for sort-by are slug (default option), title and date, and for sort-order are asc (default option) and desc.

This directive will only show the files from the root of the directory. It’s not recursive.

Interpreted Text Role `page`¶

Interpreted Text Role that generates a link to the given page. The text displayed is by default the title of the linked page. You can replace it with a custom title using this syntax: :page:`Link title <linked-page>`.

Usage example:

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.

Writing blog pages/posts¶

Tagging posts¶

Overriding the creation date¶

Scheduling the post/page for a future date¶

Overriding the post/page author¶

Post aliases¶

Adding attachments¶

Directive attachment-image¶

Directive attachment-figure¶

Interpreted Text Role attachment¶

Additional reStructuredText directives/interpreted text roles¶

Directive youtube¶

Directive vimeo¶

Directive code¶

Directive sourcecode¶

Directive math¶

Directive include¶

Directive subpages¶

Interpreted Text Role page¶

Previewing your post/page¶

Commiting your post/page¶

Directive `attachment-image`¶

Directive `attachment-figure`¶

Interpreted Text Role `attachment`¶

Directive `youtube`¶

Directive `vimeo`¶

Directive `code`¶

Directive `sourcecode`¶

Directive `math`¶

Directive `include`¶

Directive `subpages`¶

Interpreted Text Role `page`¶