Blorg Manual

Table of Contents

Next: , Previous: (dir), Up: (dir)

Blorg Manual

This manual is for Blorg (version 0.71).

Copyright © 2006 Bastien Guerry

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF's Back-Cover Text is: “You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.”

--- The Detailed Node Listing ---

Quickstart

Blorg File

Templates

Post Template

Next: , Previous: Top, Up: Top

1 Quickstart

Blorg is a tool that helps you to produce a blog based on an org-mode file. If you're here, there are good chances that you've heard about Org-mode. If you don't, please check Org-mode before : http://staff.science.uva.nl/~dominik/Tools/org/

Note that blorg has been developped under GNU Emacs. It should work fine under XEmacs, but it has not been thoroughly tested yet.

Next: , Previous: Quickstart, Up: Quickstart

1.1 Another blog engine?

Blorg is another blog publishing tool. There are already many of them in the wild, so why would you prefer this one?

Next: , Previous: Another blog engine?, Up: Quickstart

1.2 Install blorg

Get blorg.el: http://www.cognition.ens.fr/~guerry/u/blorg.el

Then make sure blorg.el is in your load-path and require it somewhere in your configuration.

For example, if blorg.el is in the ~/elisp/ directory, the following lines should do the trick: 

     (add-to-list 'load-path "~/elisp/")
     (require 'blorg)

Next: , Previous: Install blorg, Up: Quickstart

1.3 Example

Blorg files are just like any other org file except that they understand a few specific keywords.

Here is a minimalistic example of what an blorg file looks like. Copy this example somewhere and try C-c " (blorg-publish). 

     #+TITLE:       The title of my blog
     #+BLOG_URL:    http://www.server.org/~me/
     #+PUBLISH_DIR: /home/me/public_html/
     
     * DONE This is my first entry                   :misc:
       CLOSED: [2006-11-03 ven 16:57]
     
     Hello world!

Please make sure to adapt this example to your environment before trying it! Let's explain the structure of this example a bit.

#+TITLE:
#+BLOG_URL:
#+PUBLISH_DIR:
These keywords respectively define the title of the blog, the full URL of the blog (as publicly available from the web) and the server directory where to upload files.

See The header for further details about available keywords in blorg.

* DONE This is my first entry :misc:
The title of the first blog post. Only first-level headlines marked as DONE are considered as suitable for publication. Headlines containing other TODO keywords are simply ignored.

For a full description of all available variables in the header, see The header.

:misc: is what org-mode defines as a tag. it will be used by blorg to publish two files: misc.html will contain all posts that are tagged as misc and misc.xml will contain a feed for this tag.

CLOSED: [2006-11-03 ven 16:57]
Creation date of the post. Creation date is the date when you first locally finished or updated the post. Note that this is not always the same as the publication date, since publication date is the date when you actually upload the files on the server.

For this CLOSED: string to be automatically called when finishing a blog entry, turn on org-log-done.

Next: , Previous: Example, Up: Quickstart

1.4 Publishing process

blorg-publish

Calling blorg-publish (C-c ") parse the blorg file and export it as a blog.

By default, blorg does not re-publish a post page if this page already exists on the server. You can force the upload of all post pages by prefixing blorg-publish: C-u C-c ".

Giving a numeric argument will force the index to display the given number of posts and force the upload of all post page. C-u 4 C-c " makes blorg list 4 posts in the index page.

Rendering steps

Blorg first parses the header and the content of the blorg file. Then the file is rendered as a blog. The content of the blog is processed in this order.

  1. Check whether the `upload' and `images' directories do exist and create them if not.
  2. Render the index page. Create an atom or rss feed for this page if index is an element of blorg-publish-feed.
  3. Render the tag page(s). Create an atom or rss feed for each tag page if tag is an element of blorg-publish-feed.
  4. Render month page(s). No feed is published for month pages, for it doesn't make sense. Maybe force re-publishing of all month pages, depending on whether blorg-publish is prefixed or not.
  5. Render post page(s).

Previous: Publishing process, Up: Quickstart

1.5 Configuration

There are mainly three ways of configuring blorg.

  1. Use the traditionnal Customize interface (M-x customize-group RET blorg).
  2. Use separate emacs-lisp file for the whole system: see blorg-config-file.
  3. Use a separate emacs-lisp config file for a specific blorg file by giving a value to the #+CONFIG_FILE keyword.

Next: , Previous: Quickstart, Up: Top

2 Blorg File

This section describes the file structure. More precisely it goes through available keywords that you can put in the header and it describes how blorg handles text formatting.

Next: , Previous: Blorg File, Up: Blorg File

2.1 The header

In org-mode, the header is defined by the first lines of the file, each line containing a keyword. This section describes all available keywords in blorg. Each keyword locally assigns a value to the corresponding variable. If you want to modify those variables globally, customize blorg-default-options.

Keywords marked with * are not known by org-mode (but the * is not part of the keyword.)

#+TITLE, #+BLOG_URL*, #+PUBLISH_DIR*
These keywords are mandatory. They respectively define the title of the blog, the full URL of the blog (as publicly available from the web) and the server directory where to upload files.
#+AUTHOR, #+EMAIL, #+LANGUAGE
These keywords have the same meaning in org-mode and in blorg. They are not mandatory, but they represent the core information you generally have to provide for a blog.

#+AUTHOR defaults to user-mail-address.

#+EMAIL defaults to user-full-name.

#+LANGAGE defaults to the first two characters of the LANG environment variable.

#+ENCODING*
Defines the encoding of the buffer and the resulting encoding of HTML pages.
#+UPLOAD_DIR*, #+IMAGES_DIR*
Defines the relative upload and images directories. The default for these is upload/ and images/.
#+FEED_TYPE*, #+HTML_CSS*, #+XML_CSS*
#+FEED_TYPE can be either atom or rss, depending on weither you prefer Atom 1.0 or RSS 2.0 as the format for your XML feeds.

#+HTML_CSS defines the CSS stylesheet for the HTML files.

#+XML_CSS defines the CSS stylesheet for the XML feed. This is now quite obsolete since many browsers (e.g. Firefox) now have a special handling of XML feeds.

#+SUBTITLE*, #+HOMEPAGE*, #+KEYWORDS*
The subtitle might be useful in some occasions. See Templates to see how and when. The homepage is the homepage of the author, if available.

#+KEYWORDS are the keywords that will take inside the <meta name="keywords" /> of the HTML output.

#+CREATED*
Define the date creation of the blog.
#+DONE_STRING*
Usually, the last element of org-todo-keywords is DONE. blorg will use it as the default keywork for headlines that are suitable for publication. If #+SEQ_TODO is defined, this will override org-todo-keywords.

If #+DONE_STRING is defined, it will be used as a special string marking publishable headlines.

Be aware that if you use a #+DONE_STRINE that is different from the traditionnal DONE keyword, you will get trouble logging headlines with CLOSED: string.

Defines the number of posts to process when exporting the index and the tags pages.

Other keywords like #+STARTUP, #+LINK, #+TBLFM, #+SEQ_TODO, #+CATEGORY, #+TAGS have no special meaning in blorg.

Previous: The header, Up: Blorg File

2.2 Text Formatting Rules

Usual text formatting will be exported without complain.

Next: , Previous: Blorg File, Up: Top

3 Templates

This section describes the templates mechanism as it is implemented in blorg. Templates allow you to make the HTML output of blorg look the way you want.

Next: , Previous: Templates, Up: Templates

3.1 Blog Structure

Here's an overall view of the blog structure :

Next: , Previous: Blog Structure, Up: Templates

3.2 HTML Structure

Here is the default hierarchy for the HTML page. `Included tag' describes the first tag to appear in the element (if any). `In template' says whether the corresponding HTML element is by default included in templates.

`*' means it's included in all templates. `!page' means it's not included in the `page' template. `!*' means it's not included in any template.

HTML element included tag in templates
HTML - *
.BODY - *


..HEAD - *
...DIV id:content - *


....DIV id:blog-title <h1 /> *
....DIV id:blog-author <h3 /> *
....DIV id:tags-cloud <a /> !post
....DIV id:prev-posts <ul /> !post
....DIV id:archives <ul /> !post


....DIV class:post - *
......DIV class:post-title - *
......DIV class:post-infos - *
.......P class:author - *
.......P class:date - *
.......P class:tags - *
......DIV class:post-echos - !*
......DIV class:post-content - *
.......A class:read-more - !post

In the next two sections, we get a closer look at two templates: the index template and the post template, respectively defined by blorg-index-template and blorg-post-template.

Next: , Previous: HTML Structure, Up: Templates

3.3 Index page

Each template is a mix of HTML code and emacs-lisp expressions.

Here is blorg-index-template: 

     <body>
     <div id="content">
     
     <div id="blog-title">
       <h1><a href="(blorg-insert-index-url)"> \
       (blorg-insert-page-title)</a></h1>
     </div>
     
     <div id="blog-author">
       <h3><a href="(blorg-insert-mailto-email)"> \
       (blorg-insert-author)</a></h3>
     </div>
     
     (blorg-insert-previous-posts)
     (blorg-insert-tags-as-cloud)
     (blorg-insert-archives)
     (blorg-insert-content)
     
     </div>
     </body>

Depending on the template, you have a set of available elisp expressions that you can insert in the template. Check the docstring of each template variable to get the list of available expression.

Here is the list of available elisp defuns you can insert in the index template: 

     (blorg-insert-index-url)       : the URL of the index page
     (blorg-insert-homepage)        : the URL of the author's homepage
     (blorg-insert-page-title)      : the page title
     (blorg-insert-page-subtitle)   : the page subtitle
     (blorg-insert-mailto-email)    : mailto:your@email.com
     (blorg-insert-email)           : your@email.com
     (blorg-insert-author)          : author's name
     (blorg-insert-previous-posts)  : a list of previous posts
     (blorg-insert-tags-as-cloud)   : a cloud of tags
     (blorg-insert-tags-as-list)    : a list of tags
     (blorg-insert-archives)        : a list of archived months
     (blorg-insert-content)         : the main content

Previous: Index page, Up: Templates

3.4 Post Template

The post template defines the display of a post in a page.

Attention: we're not talking about the way each post-page is structured (which is defined by blorg-post-page-template) but the way each post appears in a [index/month/tag/post]-page.

Here is the default template for posts: 

     <div class="post">
     
     <div class="post-title">
       <h2><a href="(blorg-insert-post-url)"> \
       (blorg-insert-post-title)</a></h2>
     </div>
     
     <div class="post-infos">
      (blorg-insert-post-author)
      (blorg-insert-post-dates)
      (blorg-insert-post-tags)
     </div>
     
     <div class="post-content">
      (blorg-insert-post-content)
     </div>
     
     </div>

Here is the list of available elisp defuns you can insert in the post template: 

     (blorg-insert-post-url)     : the URL of the post
     (blorg-insert-post-title)   : the title of the post
     (blorg-insert-post-author)  : the author of the post
     (blorg-insert-post-dates)   : the publication dates
     (blorg-insert-post-tags)    : the tags for this post
     (blorg-insert-post-echos)   : the "Submit this post" links
     (blorg-insert-post-content) : the main content of the post

Please note that this list slightly differs from that of the index template. The list of potential elements is not exactly the same for each template.

Next: , Previous: Post Template, Up: Post Template

3.4.1 Templates in templates

The funny thing is that even in the post template, there are more (hidden) templates. For example, the display of blorg-insert-post-author is controlled by blorg-post-author-template. See blorg-post-dates-template and blorg-post-tags-template.

Next: , Previous: Templates in templates, Up: Post Template

3.4.2 Full post display

Let's say that you want the full post to be displayed in every page but in the index. You can do this by setting blorg-put-full-post. This option is a list of symbols among index, post, tag and month. The default is '(index) so that only post pages display the full content of posts.

Previous: Full post display, Up: Post Template

3.4.3 Similar options

Here is a list of other options working the same way:

All these options override the display of a post as set in blorg-post-template. And in fact, you might say they are redundant since the structure of the post is already defined in this template. But

  1. it's easier and faster to edit such options than to edit the whole template;
  2. separate options let you distinguish between the templates (that globally apply to the system) and the file-specific options. You can add file-specific options in a separate config file. The name of this file is set by org-bloggging-config-file and/or in the header with the keword #+CONFIG_FILE.

Next: , Previous: Templates, Up: Top

4 Options

Previous: Options, Up: Top

Index