Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/madx/honk

my blogging engine - sinatra + yaml
https://github.com/madx/honk

Last synced: 2 days ago
JSON representation

my blogging engine - sinatra + yaml

Awesome Lists containing this project

README 

        
h1. Honk



A minimalistic, text-based blogging engine.



h2. Features



* Posts,

* Comments,

* Tags,

* That'it.



h2. Requirements, install & setup



You'll need "Sinatra":http://github.com/sinatra/sinatra and, optionnaly,

"Thor":http://github.com/wycats/thor.



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@ to start your blog.



You can run @thor script:bootstrap@ to build the default files and start 

editing them right away!



h2. Usage 



Honk relies on two main files, plus your posts and the comments for your posts,

which will be automatically generated.



h3. 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 @~@ 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

- more_magic: foo_~.yml # will map to foo_more_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.



h3. 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




h3. 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: |-

  
This is my first post


  
As you can see I write raw HTML





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

file!



h3. 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: [email protected]

: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.



h2. 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.



h3. 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.

* @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.



h3. Theme & layout



Of course, Honk's layout can be overriden. Just take a look at

@public/master.css@ and @views/@.