Periklis Ntanasis:
Master's Touch

fade out

Hello World AsciiBlog :)

AsciiBlog is a blog engine based on Asciidoc. It generates a blog in plain html. The idea is to have a blog in plain html generated just as the Asciidoc homepage.

Just a moment! That’s asciidoc already! So what’s so special about AsciiBlog?

All the magic is just some shell and bash scripts that automate the hole procedure. Everything else is just Asciidoc.

Bellow I will explain you the logic behind Asciiblog, the workflow of the blogging process and I’ll point out some features that are missing and I would like to implement in the future.

As you will see it is very premature at the moment (just version 0.1) but it works (this blog is actually a proof of concept) and it is another option out there.

Introduction

Before I continue I’ll remind you that Asciiblog is just Asciidoc so every page (that includes the posts) that is generated was previously written in Asciidoc markdown.

Here it is the directory hierarchy of Asciiblog.

Hierarchy
archive/
bin/
images/
javascripts/
layouts/
mainsite/
styles/
website/

Let’s see it in more detail.

Archive

Archive contains the posts written in Asciidoc markdown.

To create a new post we invoke the new-post.sh script from within bin directory. A new empty text file then is created. The file name is <unix time>.txt except if the script is invoked like new-post.sh some-name. Then the new file will be named <some-name>.txt.

Every post resides in archive/YEAR/MONTH/DAY/<some-name>.html. The directories YEAR/MONTH/DAY/ are created automatically by the new-post.sh script.

Bin

Bin contains all the Asciiblog magic. Currently there are 6 scripts.

archive.sh

Creates a nice directory/post listing, instead of the default webserver directory/file listing, that look like that:

build-website.sh

It generates the pages that aren’t posts. These pages are located in mainsite directory. Every page should be included separetely just like that:

main="$(dirname "$0")/../mainsite"
pageroot="$(dirname "$0")/../website"
...
$ASCIIDOC_HTML -a index-only -o"$pageroot/index.html" "$main/index.txt"
$ASCIIDOC_HTML -d "book" -o"$pageroot/archive.html" "$main/archive.txt"
$ASCIIDOC_HTML -o"$pageroot/about.html" "$main/about.txt"

This script should be changed accordingly.

createrss.sh

Creates the RSS feed archive.rss in the website home directory. This RSS file contains the post titles and the publication dates.

new-post.sh

I have talked about that in the archive.sh section sooner.

post-it.sh

This script has to be invoked from within the post directory.

Let’s say this post I am writting right now is located in archive/2011/08/03/asciiblog.html. I should publish it like

myBlog/archive/2011/08/03$../../../../bin/post-it.sh asciiblog.txt

That command will add an entry for the new post in mainsite/archive.txt and then will generate the post and the new archive page.

If it’s invoked with the -r attribute the archive.txt won’t be updated and regenerated. This is helpfull when editing a post and want to republish it without adding a new entry to archive.txt.

rsswriter.sh

This script contains functions that help the rss file creation.

Images

It contains the website images.

Javascripts

It contains the javascript that is included in the static html.

Layouts

It contains the layouts. Layout is the html that is placed previously and after every generated page.

There are 3 different layouts, one for the mainsite pages, one for the blog posts and one for the archive.sh script. That layouts are actually the same template except that the url’s are different.

Mainsite

It contains the pages that aren’t posts.

Styles

It contains the css files.

Website

It contains the hole generated website.

Workflow

Now I’ll explain how you can build a website like this one with Asciiblog.

First of all you have to modify the layouts and styles. There you will include your website design (html and css).

After that write something nice that will be the pages that aren’t posts and place them in the mainsite directory. Then modify the build-website.sh script accordingly and run it.

The next step is to run the new-post.sh script that creates a new file, write a cool post and then run the post-it.sh script to generate it.

Run the archive.sh to create the directory/post listing and then the createrss.sh to update the archive.rss.

Tah-dah! Now you have your website build and ready!

Conclusion

The procedure is working but it isn’t very smooth at the moment. Asciiblog promotes the blogging like coding way of blogging. It isn’t supposed to be mainstream but it’s far enough from being as easy to use as I would like to be, so there is plenty of room for improvement.

Features that are missing and things that must be done

  • Tags

  • Post deletion

  • Post comments - that can be done right now with disqus or something like that but I have to spent a little more thinking about that.

  • Cleanup the scripts

  • Use global configuration file for the scripts

  • Add the scripts to the executables search path to call them without defining the full path

Comments

fade out