Recent Posts ¶

See all posts ordered by date

Setting up AWB - the AsciiDoc Website Builder

Ronald MacDonald <> v1.0, Fri Oct 28 18:17:00 EDT 2011

This site now uses AWB along with AsciiDoc to manage the site content. It’s a far cry from editing HTML or PHP directly and much less overhead than running a CMS. All in all, it’s perfect for static and non-interactive web sites.

Now that I’m happy with the way this is all working, I thought it would be sensible to upload all the resources I’ve used to put this together so that others may do the same. In some cases, it’s not been hugely easy to see how the templates or sources are applied by AWB when building a site and so, without having to go through the source as much as I did, it might be a little more straightforward for you to get up and running.

WarningI use OS X. That means that these instructions are tailored to their being executed on OS X rather than any other OS’s. This will not, however, preclude you from using AWB.


AWB uses AsciiDoc to build from the source files. Therefore, it would be logical to assume you need AsciiDoc. You may download it from - take a look at to see how to install AsciiDoc on your system.

Debian users may download AsciiDoc from the package repository:

apt-get install asciidoc

It is, however, quite likely that these sources lag somewhat behind the main releases so it is recommended that instead, you download and install from source.

You’ll also need python - which comes along with OS X - but for Windows users that means downloading Python for Windows.

Quick Start

I’ve created a demo AsciiDoc/AWB-based web site, which you may visit at On there, you may download the source packages for the demo site, giving you an idea as to how you might structure your directory layout.

Once you’ve got a hold of this file, extract it to a sensible location. On OS X, I keep my sites under ‘~/Sites’. To get AWB compiling your site correctly, you’ll also need to create the awb.conf configuration file. It’s kept under .config/awb/awb.conf.

Therefore, at a terminal window, enter the following (OS X)

cd && mkdir -p ~/.config/awb && touch ~/.config/awb/awb.conf
open .config/awb/awb.conf

This’ll have you ask what application to open the file with. If you select TextEdit, please make sure that you edit the file in ‘plain text’ mode, or it’ll add some gibberish to the file that’ll make it impossible for AWB to read properly.

In Linux (assuming you’re happier using vi)

mkdir -p ~/.config/awb && touch ~/.config/awb/awb.conf
vi ~/.config/awb/awb.conf

In the file awb.conf we’re then going to need the following:

siteroot: <PATH TO>/Sites/awbdemo
baseurl: http://<URL>
asciidoc options: -a icons -a theme=flask -f <PATH TO>/Sites/awbdemo/src/html5.conf
tidy: true

In the above example, you’ll need to change a few of the options:


Change the <PATH TO> to your local user directory. In other words - on OS X - open a terminal window and type pwd. Use whatever result you get back as your home path.


Set this to the address of your web site.

asciidoc options

Like in siteroot, change the <PATH TO> to the home folder of your profile.

Tidy Options

We’ll also need to customise the configuration file tidy-options, in the base of the web site demo’s source. The options are self-explanatory - refer to for additional options which you may apply to the output.


Tidy will only work if you’ve got tidy installed! If tidy -v in your console returns a ‘command not found’, it’s most likely not installed. On OS X (with Macports), just try sudo port install tidy.

Compiling the Site

AWB compiles the site in a make-style fashion - it only compiles files which have changed, or need to change (interdependencies - blog post links, etc).

Open a new Terminal window and get the site compiled as follows:

awb -c=./.config/awb awbdemo

Your new site will now sit in a directory called ‘html’.


AWB does not, alas, provide ~ expansion, so bear that in mind before you spend hours (like I did) wondering why it wasn’t able to find paths relative to your home directory.

System Setup (Apache, OS X)

OS X comes with Apache, which we’ll use. We’ll first need to edit the vhost, virtual hosting, definitions.

sudo vi /etc/apache2/extra/httpd-vhosts.conf

Then add the following after NameVirtualHost *:80 (in vi, use arrows to move and then press i to enable edit-mode: Command-V will work as usual to paste):

<VirtualHost *:80>
    ServerAdmin     <your@email.address>
    DocumentRoot    "<PATH TO>/Sites/awbdemo/html"
    ServerName      awbdemo.local
    ErrorLog        "/private/var/log/apache2/error_log"
    CustomLog       "/private/var/log/apache2/access_log" common

Then to escape, write and quit, hit <esc> followed by :wq. Done!

Local host resolve

To finalise configuration, we’ll also want to edit the /etc/hosts file, so as to be able to check that we’re referring to links correctly. You could use the usual OS X convention (finding your site at http://localhost~/<yourname>/Sites), but root-relative paths would break. So:

sudo vi /etc/hosts

And then, move down to the last line (CTRL+D or arrow keys to move), followed by o (the letter o) to create a new line in edit mode. Then enter the following:       awbdemo.local

Sweet. Now, as before, <esc>, :wq to write and quit.

Finally, we’ll want to start/restart the web server so as to be able to see what the whole shebang looks like: by going to System Preferences, hitting on sharing, all we have to do is to untick (if it’s already ticked) and then re-tick the box beside ‘Web Sharing’. With this, Apache2 will be restarted.

Web Sharing - Preferences

So - all we’ve left to do is view the site, which we can do by opening a browser window and entering ‘awbdemo.local’ as the address - that should be about it!

Email me and let me know how you get on!