To start using awb you need to set up at least one website in your user awb configuration file. awb uses the XDG specification, so the awb configuration directory will typically be located at ~/.config/awb/. The global configuration file is named awb.conf inside this directory. It could look something like this:
[mywebsite] siteroot: /home/me/mywebsite baseurl: http://my.web.site asciidoc options: -d book -b html4 tidy: true
This simply defines a website known to awb as "mywebsite". The options are:
- The root directory of the awb website. The AsciiDoc source lives in siteroot/src, and the html output goes to siteroot/html. Temporary files are also created and deleted here during processing.
- The url of the root of the website. This is used for generating sitemap.xml. Note that there is no trailing slash.
- asciidoc options
- Options to be passed to AsciiDoc. I use this to specify a custom html4.conf file in addition to the options shown in the example.
- true/false (default: false) — whether to use HTML tidy on the output. If this is set true, you must also have a tidy-options file in siteroot/src. See http://tidy.sourceforge.net/docs/quickref.html for details of what to put in this file.
Building your site
Once you have a website configured and some source files written, simply issue the command
% awb mywebsite
awb will only rebuild HTML files that have become out of date.
If, for some reason, not awb doesn’t rebuild all the files that it should, you can use the -r option to force all files to be rebuilt. It might also be a good idea to file a bug report.
awb has three more options:
- “dry run”, in which awb will scan your site and pretend to build it without actually doing anything. This could be useful to see which files will be rebuilt, for example.
- Specifies a configuration directory to use, instead of the default XDG directory. This is useful for sending in bug reports, for example.
- “list” all the sites defined in the configuration file.