skip to navigation
skip to content

weblog 0.9

Simple blog publisher. It reads structured text files and generates static HTML / RSS files. Weblog aims to be simple and robust.

Latest Version: 2.5

Abstract

Simple blog publisher. It reads structured text files and generates static HTML / RSS files. Weblog aims to be simple and robust.

In this document Weblog is the name of the software. The web log concept is referred as the more common term blog.

According to Wikipedia:

A blog (a portmanteau of web log) is a website where entries are written in chronological order and commonly displayed in reverse chronological order.

Pre-requirements

  • Python version 2.5+
  • Jinja version 1.1+.

Learn how to install Jinja at http://jinja.pocoo.org/documentation/installation.

Installation

Download Weblog’s latest version at http://henry.precheur.org/weblog/.

Extract it:

tar zxf weblog.tar.gz

It can be used right away using the helper script weblog_run.py.

Or install it using the supplied setup.py script. Run python setup.py --help to learn how to use it.

Alternatively if easy_install is present, simply type:

easy_install weblog

It fetches the latest version of Weblog and installs it.

Quick Start

In the following examples weblog/ represents Weblog’s installation directory.

If you downloaded the source tarball without installing Weblog; Use the helper script weblog_run.py instead of the weblog command:

$ python /path/to/weblog/weblog_run.py --help

Create a new directory named my_blog. The $ sign represents the shell prompt, do not type it!:

$ mkdir my_blog

Copy from the Weblog installation directory the file weblog.ini into my_blog:

$ cp weblog/examples/weblog.ini my_blog

weblog.ini is the configuration file of the blog. Check the configuration file section for more information. Do not worry about it now, no modification is required to get the following examples working.

Create a file named first_post.html in the my_blog directory:

title: First post
author: Me
date: 2007-08-25

Hello world!

Actually all the post filenames must end with .html.

Go in the my_blog directory and run the Weblog using the publish command:

$ cd my_blog/
$ weblog publish

It should create a directory named output containing the generated files. Look at the results by opening the file output/index.html in your web-browser.

The first 3 lines of the file first_post.html define the post’s parameters. These are standard RFC 2822 headers (the headers used in Emails). Only title is mandatory. date and author are optional. If you don’t fill these fields, the author is the one specified in weblog.ini, and the post’s date is the post file’s last modification date.

The line Hello world! is the actual content of the post. Note that a blank line is required between the headers and the content.

The content is an HTML block. Use the HTML syntax to format your post content. For example create a second file named second_post.html:

title: Second post
author: Me (again!)
date: 2007-08-26

<em>Second</em> <q>test</q> <strong>post</strong>!
<p>
&copy 2007 Me
</p>

Regenerate the blog files:

$ weblog publish

Reload the page in your browser. You should see a second post with some formating.

The default post file encoding is ASCII. To use a different encoding specify it via the field encoding:

title: Encoding test
date: 2007-11-5
encoding: latin-1

Here you can put some ISO-8856-1 text ...

Specify the default encoding in weblog.ini, to avoid setting the encoding field for every file.

While writing your blog post, don’t bother about the date field immediately. Weblog automatically sets the date to the filename’s last modification time.

A good practice though is to set the date when the post gets published. By doing so the date won’t get changed if the file gets copied. To set the date of a post, use the command date:

$ date
Mon Apr 14 00:10:44 PDT 2008

$ cat my_blog_post.html
title: My blog post

This is a blog post without any date.

$ weblog date my_blog_post.html
Setting date to 2008-04-14 00:12:22 in file my_blog_post.html

$ cat my_blog_post.html
title: My blog post
date: 2008-04-14 00:12:22

This is a blog post without any date.

$ weblog date my_blog_post 2008-5-15
Setting date to 2008-05-15 in file my_blog_post.html

$ cat my_blog_post.html
title: My blog post
date: 2008-05-15

This is a blog post without any date.

The date command accepts 3 formats as argument:

  • YEAR-MONTH-DAY (2008-01-31)
  • YEAR-MONTH-DAY HOUR:MINUTE (2008-01-31 16:45)
  • YEAR-MONTH-DAY HOUR:MINUTE:SECONDS (2008-01-31 16:45:14)

For conciseness the date command uses aliases to specify commonly used date:

  • now
  • today (like now but only set the date, not the time)
  • tomorrow (now + 24 hours)
  • next_day (like tomorrow but only sets the date, not the time)

Encoding and escaping

Weblog tries to make sure its output is always correct. Non-ASCII characters, are converted to HTML entities so you don’t have to worry about it. The output is never encoded into ISO-8856-1, UTF-8 or another non-ASCII encoding. Encoding conversions are not so simple in practice. By doing only one conversion to the simplest encoding possible, a lot of problems are solved.

The content of the post is not escaped. The title and the date of the post are escaped. The title Hello <em>World</em> is escaped. HTML tags appear, and no formating is applied to world. The original text “Hello <em>World</em>” appears instead of “Hello World”,

It is possible to override this by specifying raw as the encoding. Using the raw encoding nothing is escaped or converted, but you must make sure all characters are ASCII characters:

title: Non-escaped <em>title</em>
author: <q>Me</q> &lt;me@my_weblog.org&gt;
encoding: raw

If the raw encoding is used, all the characters must be ASCII characters. Otherwise an error is reported.

Attaching a file to a post

To attach files like images to a blog post, use the field files:

title: Attach a file
files: picture.png directory/file

<img src='picture.png' alt='a picture'>
<a href='directory/file'>a file</a>

It will copy picture.png and directory/file. If directory does not exist, it will be created.

How URI’s are handled

Relative links (<a href='test.html'>) are rewritten in the RSS file and in some HTML files. In the RSS file base_url is prepended to the link to make sure it always points to the correct URI.

Absolute links (<a href='http://example.com'>) are not rewritten. It should always point to the correct location regardless of the context.

Note that Weblog considers / as the root directory. If base_url is http://example.com/; test.html and /test.html are both rewritten to http://example.com/test.html.

Command line parameters

Usage: weblog [options]

Options:
-h, --help show this help message and exit
-s DIR, --source-dir=DIR
 The source directory where the blog posts and the file weblog.ini are located
-o DIR, --output-dir=DIR
 The directory where all the generated files are written. If it does not exist it is created.
-q, --quiet Do not output anything except critical error messages

Configuration file

All configuration options are in the weblog section. Learn more about the format of the configuration file: http://docs.python.org/lib/module-ConfigParser.html.

A sample configuration file:

[weblog]
title: Blog's title
url: http://example.com/
description: A sample blog.
source_dir: path/to/my/posts
output_dir: path/to/output/directory
encoding: latin-1
author: Me <me@example.com>

Fields description

title

The blog’s title. It appears at the top of the homepage and in the page’s title.

This field is mandatory.

url

The base URL of your blog. For example http://my-host.com/my-weblog/. It is used to generate the absolute URL’s to your blog.

This field is mandatory.

description

A short description of your blog. Like “My favorite books reviews”, or “Dr. Spock, publications about electronics”. Note that it is possible to use multiple lines:

description: My blog
  about
    configuration files.

The description is merged to a single line; My blog about configuration files..

This field is mandatory.

source_dir
The directory containing the file weblog.ini, the post files and possibly the templates directory. By default the current directory.
output_dir
The output directory. Generated files are put there. By default output.
encoding
The default post file encoding. Default ASCII. It is overridden by the encoding field in the post file.
author
The default author. It is overridden by the author field in the post file.
post_per_page
The number of post displayed per listing page. Default is 10.
rss_limit
The maximum number of post to be included in the RSS file. The most recent posts are the ones included. Default is 10.
html_head

Additional information for the <head> section. Useful to add custom CSS style sheets. Can be a string or a filename. If a file with this name exists in the source directory then it is read. Else it is considered as a string. The result is processed using Jinja. Use the variable top_dir to link to external files. It contains the path to the top directory of the blog.

Examples:

html_head=<style type='text/css'>body { font-family: sans-serif; }</style>

html_head={{ top_dir }}my_stylesheet.css
html_header
Additional content located just before the blog content. Can be a string or a filename. (See html_head above) Useful to add a logo or a search box at the top.
html_footer
Additional content located just after the blog content. Can be a string or a filename. (See html_head above) Useful to add … A footer!

Tips on Uploading

rsync is a useful tool to upload files generated by Weblog.

To make sure rsync does not change the last modification time of the files that did not change, use the following:

rsync --compress --checksum --recursive path/to/blog remote_host:public/dir/

Accurate last modification time makes efficient caching possible.

 
File Type Py Version Uploaded on Size
weblog-0.9.tar.gz (md5, pgp) Source 2008-07-23 18KB