Honk

A minimalistic, text-based blogging engine.

Features

• Posts,
• Comments,
• Tags,
• That’it.

Requirements, install & setup

You’ll need Sinatra and, optionnaly,
Thor and a formatter such as RedCloth,
Maruku,…

Thor is used for convenience scripts (regenerating the taglist, managing your
posts) so I strongly recommend that you install it. The formatter may be used to
ease the editing of your posts. Honk will treat the contents as raw HTML if you
don’t specify a formatter (see below).

Once you’ve got this, clone this repository or grab a tarball and extract it
where you want to install your blog. Run ruby honk.rb or thor honk:start to
start your blog.

Usage

Honk relies on two main files, plus your posts and the comments for your posts,
which will be automatically generated.

Index

The index.yml files contains a sequence of mappings in which each key is a
short name for your post, and the value is the path for your post (relative to
Honk’s root) or nil to automatically build the path.

--- !honk.yapok.org,2009/Index
- my_first_post: my_first_post.yml
- another_one: another_one.yml
- alias: this_post_is_aliased.yml
- magic: ~ # will map to magic.yml

The way Honk works allows you to write posts without publishing them. They will
be available only when you add them to the index. Be careful that it is a
sequence, which mean it’s ordered: the most recent post goes at the bottom of
this file.

Tags

Next, the tags.yml file is simply a mapping that associates each tag with a
list of posts.

Here’s an example tags.yml

--- !honk.yapok.org,2009/Tags
a_tag:
  - a_post
another_one:
  - a_post

Posts

Posts are stored in YAML files as well, the format is self-explanatory enough:

--- !honk.yapok.org,2009/Post
:title: A post about something
:tags:
  - miscellaneous
  - another tag
:timestamp: 2009-01-27T21:42:21+01:00
:commentable: yes
:contents: |-
  <p>This is my <strong>first post</strong></p>
  <p>As you can see I write raw HTML</p>

Remember that in order to publish a post, you have to add it to the index.yml
file!

Comments

Comments are stored in one file per post, so if you have a post stored in
my_post.yml, the comments file would be my_post.comments.yml. The format is
rather simple too:

--- !honk.yapok.org,2009/Comment
:author: Jonh Doe
:email: john@doe.com
:website: http://johndoe.com/
:timestamp: 2009-01-27T21:42:21+01:00
:contents: |-
  Wow dude, that post is awesome!

The comments file is a stream of comments, from the oldest to the latest.

Configuring and tweaking

The basic configuration is done through the Honk.setup block it lets you define
some basic parameters for your blog such as pagination. Just open the config.rb
and follow the instructions.

Configuration options

• paginate: defines how many posts are showed per page.
• root: tells honk where to find the posts, index and tags files, default is
  the same dir as you blog, but you can change this to put your content
  elsewhere.
• formatter: the name of the gem to require to enable formatting.
  Using a formatter automatically sets a default format_proc but you can still
  change that later.
• format_proc: a proc that returns your formatted post. The argument is
  the contents of the post being formatted.
• comment_filter: a proc that returns the filtered text for a comment. This is
  useful for escaping HTML, allowing formatting, etc.
• meta: defines metadata for your blog such as author’s name, email, a
  title…

If you want more tweaking, you can still hack the source, it’s open.

Theme & layout

Of course, Honk’s layout can be overriden. Just take a look at
public/master.css and views/.