Setting up AWB - the AsciiDoc Website Builder
Ronald MacDonald <ronald@rmacd.com> 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.
I use OS X. That means that these instructions are tailored to their being executed on OS X rather than any other OS’s.
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 recently created a demo AsciiDoc/AWB-based web site, which you may visit at 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’, logically enough. 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:
[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. In other words - on OS X - open a terminal window and type pwd. Use whatever result you get back as your home path. |
| baseurl |
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. |
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.
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
</VirtualHost>
Then to escape, write and quit, hit <esc> followed by :wq. Done!
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:
127.0.0.1 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.
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!