Content¶
After the headers comes the content of post. You can write posts using 2 syntaxes:
- Raw HTML syntax
- Markdown
The type of the post is determined by the post’s file extension.
- .html for HTML
- .txt for Markdown
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.
A good practice is to set the date when the post gets published. By doing so the date won’t get changed if the file gets copied or modified. 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
Some random content.
$ 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
Some random content.
$ 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.
Without any argument the date is set the local time. Most of the time, you will only need this command:
$ weblog date path/to/my/post.txt
The date command accepts 3 formats as optional 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)
This way you can set a specific publication date for a post.
Headers define everything that is not part of the post content: They are standard RFC 2822 headers (the headers used in Emails). Only title is mandatory.
- Title: title
- Author: author
- File’s encoding: encoding (see Encoding)
- Files attached to the post: files (see Attaching a file to a post)
- Slug: slug (See Post’s URL)
A blank line must follow headers.
After the headers comes the content of post. You can write posts using 2 syntaxes:
- Raw HTML syntax
- Markdown
The type of the post is determined by the post’s file extension.
- .html for HTML
- .txt for Markdown
The URL of a post is determined by its date and its Slug. For example:
title: test
date: 2009-11-5
Example
The URL will be http://.../2009/11/5/test.html. It is constructed this way:
<Year>/<Month>/<Day>/<Slug>.html
<Slug> is a label given to the post. By default, it is determined from the post’s title, by replacing spaces with underscores. If the title is “Hello World”, the slug will be Hello_World. You can change a post’s Slug via the header slug:
title: My fancy blog post
date: 2009-11-1
slug: fancy
Example
Here the URL will be http://.../2009/11/1/fancy.html.
Weblog applies Postel’s law:
Be conservative in what you do; be liberal in what you accept from others.
It accepts files with different encoding as input but always output HTML files using ASCII encoding, non-ASCII characters being converted to HTML entities.
The Atom feed is always encoded in UTF-8.
You have 3 ways of specifying the input encoding:
The operation system’s locale or system’s encoding.
config.py, via the field encoding. This encoding becomes the default encoding for the post files and the configuration file config.py. It overrides the system’s encoding.
The post’s header encoding, example for UTF-8:
encoding: UTF-8or latin-1:
encoding: latin-1This override the encoding specified in config.py.
To get a list of supported encodings check Python’s documentation
Weblog escapes strings to make sure everything displays smoothly. If you don’t know what escaping is, you can probably skip this section.
Everything is escaped except:
- The content of a post if its syntax is HTML
- HTML head, header, and footer
Which means the title Me & You is converted to Me & you in HTML and Atom files.
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.
You can specify multiple files like this:
files: image1.png image2.png
Space characters act as the separators. This means that filenames cannot contain spaces.
Sometime, URL’s have to be changed to make sure they point to the correct location.
Relative links (<a href='test.html'>) are rewritten in HTML files to make sure it always point to the root of the output directory.
Absolute links (<a href='http://example.com'>) are not rewritten. It 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.
To customize Weblog’s appearance you need to change the templates used to generate the pages. To learn how to modify the templates, check Jinja 2 documentation, also a basic knowledge of HTML and CSS is needed.
You can find the templates in weblog/templates in your Weblog’s installation directory. Copy the files you want to modify into the templates directory inside of your source directory:
$ mkdir source/directory/templates
$ cp /path/to/weblog/templates/base.html source/directory/templates
base.html is probably the file you want to modify to customize Weblog’s global appearance. All other templates extend it.
index.html is the main page and archives.html is the archive page, listing all the posts on your blog.
post.html is used to generate individual post’s page.
There is also a template named feed.atom you should not modify this one. It is used to generate the Atom feed.
CSS is hard. The CSS syntax tend to be confusing for beginners. The numerous browser incompatibilities makes the designer’s work even more complicated. Here is a list of useful resources regarding this subject:
Usage: weblog [option] command
| -h, --help | show this help message and exit |
| -s DIR, --source_dir=DIR | |
| The source directory where the blog posts are located. [default: ‘.’] | |
| -o DIR, --output_dir=DIR | |
| The directory where all the generated files are written. If it does not exist it is created.[default: ‘output’] | |
| -c FILE, --conf=FILE | |
| The configuration file to use. If the file is not present in the current directory, the source directory is searched. [default: ‘config.py’] | |
| -q, --quiet | Do not output anything except critical error messages |
Weblog’s configuration file is a Python script. If you don’t know Python, don’t worry, the syntax is straightforward and you need very little knowledge to get started with Weblog.
Example config.py:
title = "Blog's title"
url = "http://example.com"
description = "A sample blog"
author = "Me <me@example.org>"
encoding = "latin-1"
post_per_page = 10
source_dir = "path/to/my/posts"
output_dir = "path/to/output/directory"
To learn more about Python’s syntax read the Python tutorial.
All fields are optionals except url which is needed to generate Atom feed correctly. If the field is not present, you will just get a warning. This way you can start using Weblog without even having a configuration file.
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.
It should be present, otherwise Atom feed wont work correctly.
The directory containing the post files and the templates directory. You can organize the files by creating subfolders in the source directory. Weblog visits and load files in all the subdirectories of source_dir, execpt the one listed by ignore_dirs.
By default the current directory.
A list of directories to ignore when visiting source_dir. The directory templates is always ignored and therefor you don’t need to add it to ignore_dirs.
By default empty.
The default post file’s encoding. It is overridden by the encoding field in the post file.
By default it is the operating system’s encoding.
If you are using Microsoft or Mac OS X, you don’t need to use this. If you are using an Unix based system, you might need to specify the filesystem’s encoding to have proper filenames, for example if your operating system encoding is not the same as your filesystem.
By default it is the operating system’s encoding.
The default author. It is overridden by the author field in the post file. It can contain an Email address:
author = "An Example <an@example.org>"
The number of post displayed on the listing page:
post_per_page = 42
Default is 10.
The maximum number of posts to be included in the Feed file. Default is 10.
Note: rss_limit has been renamed to feed_limit.
Additional files to be copied. Typically used to copy CSS style sheets and/or pictures. It is a list of string:
extra_files = ("style.css", "logo.png")
Files are copied into output_dir. The path is not preserved: style/weblog.css gets copied into output_dir/weblog.css; not into output_dir/style/weblog.css. This behavior is likely to change in the future.
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 modification time makes efficient caching possible.
Don’t hesitate to ask questions about Weblog:
http://groups.google.com/group/weblog-users or weblog-users@googlegroups.com
To report a bug, request a feature:
http://bitbucket.org/henry/weblog/issues/