Setting up AWB - the AsciiDoc Website Builder

Dev

Update I don’t actually use AWB any more, I use Hugo. However, I’ve left this here in case anyone is still using AWB.

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.

NOTE I 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.

Components

AWB uses AsciiDoc to build from the source files. Therefore, it would be logical to assume you need AsciiDoc. You may download it from http://www.methods.co.nz - take a look at http://www.methods.co.nz/asciidoc/INSTALL.html 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 https://awbdemo.rmacd.com/. 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:

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

This’ll have you ask what application to open the file with. If you select TextEdit, 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 the file awb.conf we’re then going to need the following:

[awbdemo]
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:

  • siteroot: Change the <PATH TO> to your local user directory
  • baseurl: Set this to the address of your web site.
  • asciidoc options: Like with 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 http://tidy.sourceforge.net/docs/quickref.html for additional options which you may apply to the output.

NOTE On MacOS you can install tidy via Macports: 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’.

WARNING AWB does not, alas, provide ~ (tilde) 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:

<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
</VirtualHost>

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.