Creating a new blog

This section will guide you through the steps required to get a blohg-based blog up and running.

Make sure that you read all the content available here in order to know how to use blohg properly.

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'

Repository structure

The repository structure is pretty easy to understand:

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
Directory/File Description
config.yaml The main configuration file.
content/ The main content directory (for pages, posts and attachments).
content/post/ The posts directory. Any content stored here is handled as blog post, instead of page.
content/attachments/ The attachments directory. Any images or static files used in posts and pages should be here.
static/ The directory with static files used in the templates, like CSS files or images.
templates/ The directory with the Jinja2 templates.

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:

Configuration option Description Default value
POSTS_PER_PAGE Number of posts per page. Used by the posts pagination and the Atom feeds. 10
POSTS_PER_ATOM_FEED Number of posts listed on the Atom feed POSTS_PER_PAGE
AUTHOR The name of the main author of the blog. Used by the Atom feeds. 'Your Name Here'
TAGLINE A short tagline for the blog. 'Your cool tagline'
TITLE The title of the blog, without HTML tags. 'Your title'
TITLE_HTML The title of the blog, with HTML tags. 'Your HTML title'
CONTENT_DIR The directory of the repository where the content is stored. content
TEMPLATES_DIR The directory of the repository where the templates are stored. templates
STATIC_DIR The directory of the repository where the static files are stored. static
ATTACHMENT_DIR The directory of the repository where the attachments are stored. content/attachments
ROBOTS_TXT Enable robots.txt, to prevent search engines from indexing source files, a.k.a. don’t follow “View Source” hiperlinks. True
SHOW_RST_SOURCE Enable the view that shows the reStructured text source of your posts and pages. True
POST_EXT The extension of your post/page files. '.rst'
OPENGRAPH Enable the Open Graph meta tags block. True
EXTENSIONS List of enabled extensions. []
EXTENSIONS_DIR The directory of the repository where the extensions are stored. ext
RST_HEADER_LEVEL reStructuredText header level 3

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:

Variable Description
version A string with the current version.
is_post A function with one argument, that returns True if the given argument is a the path of a post.
current_path A string with the path of the current page/post.
active_page A string with the first piece of the current path, useful to highlight the menu link for the current page.
tags An iterable with all the available tags, ordered alphabetically.
config A dictionary with all the configuration options.

Built-in templates

These are the built-in templates, that can be overriden from the repository:

404.html

Template for the 404 error page. You don’t need to override it on your Mercurial repository if you don’t want to customize something.

_posts.html

Template with some Jinja2 blocks that can be used by your custom templates. If you don’t want to use the custom blocks just don’t call them from the templates, and they will be ignored. You don’t need to override this file in the repository.

These are the custom blocks available:

Type Block name Where to place
Disqus disqus_header inside the html header, in base.html.
disqus_post after the post contents, in posts.html.
disqus_footer at the end of base.html, before the </body> tag.
Pagination pagination at the end of posts.html, inside the main div. There’s a CSS class, called pagination, to help you when changing the style.
Open Graph opengraph_header inside the html header, in base.html

Disqus support depends on the a DISQUS configuration variable, that should contain the value of the Disqus identifier of your blog. To get it, create an account at http://disqus.com/.

Open Graph support depends on a OPENGRAPH boolean configuration variable, that defaults to True.

base.html

The main template file, it’s mandatory that this provided in the Mercurial repository. This template is inherited from by all others.

posts.html

Template used by the views that show partial/full content of pages and posts.

It inherites from _posts.html and can make use of its Jinja2 blocks.

Local variables available for this tempalte:

Variable Description
title A string with the page/post title.
posts A list with all the posts (Metadata objects).
full_content A boolean that enables display full content of posts and not just the abstracts.
pagination A dictionary with 2 items (num_pages: number of pages, and current current page), used by the pagination block.
tag A list of strings with tag identifiers, used by the view that list posts by tags.

post_list.html

Template for the page with the listing of blog posts, without content, just the name, the date and the link.

Local variables available for this template:

Variable Description
title A string with the page title (usually “Posts”).
posts A list with all the posts (Metadata objects).

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:

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

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:

For multiple combined tags, use URLs of this form:

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:

Property Value
title TITLE or the page/post title, if applicable.
description TAGLINE or the page/post first paragraph, if applicable. Can be overrided by a .. description: reStructuredText comment.
image Full URLs of all the images found in the page/post, if applicable. Each image will have its own meta tag.

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.