Configuration is written in YAML and resides by default in ~/.amazing/config.yml. This behavior can be altered with the -c or --config switch, as in amazing --config /path/to/config.yml.

1. Layout
2. Example
3. Widget configuration
4. Format configuration

h2. Layout

include:
  - <path>
awesome:
  <screen>: 
    <identifier>:
      type: [<WidgetName>|<widget_name>]
      interval: <seconds>
      format: <ruby code>
      <custom option>: <value>

Note: scripts in ~/.amazing/widgets/ will be included automatically unless the --no-auto-include switch is employed.

h2. Example

awesome:
  0:
    pb_bat:
      type: battery
      interval: 10
    tb_time:
      type: clock
      interval: 1
      time_format: %T
    tb_mail:
      type: maildir
      format: '"#@count new message#{@count != 1 : "s" : ""}"'
      directories:
        - Mail/**/new
        - Mail/inbox/cur

h2. Widget configuration

Each widget type has its own options and “fields”. Fields are variables that can be used in the format option to customize what is displayed in the widget. These options and fields can be found out by issuing amazing with the -w or --list-widgets switch, which will output something like this:

% amazing -w mpd

Mpd - MPD Information

 DEPENDENCY | DESCRIPTION
------------------------------------
 socket     | Ruby standard library

 OPTION   | DESCRIPTION             | DEFAULT
--------------------------------------------------
 hostname | MPD server hostname     | "localhost"
 password | Authentication password | nil
 port     | MPD server port number  | 6600

 FIELD       | DESCRIPTION                                   | DEFAULT
-----------------------------------------------------------------------
 @album      | Song album                                    | nil
 @artist     | Song artist                                   | nil
 @date       | Song date from ID3 tag                        | nil
 @file       | Filename of current song                      | nil
 @genre      | Song genre                                    | nil
 @id         | Song ID in playlist                           | nil
 @length     | Song length                                   | nil
 @percentage | Finished percentage of current song           | 0.0
 @position   | Song position                                 | nil
 @random     | True if playlist is on random                 | nil
 @repeat     | True if playlist is on repeat                 | nil
 @shortfile  | Filename without directory path and extension | nil
 @state      | Play state, :playing, :paused or :stopped     | nil
 @title      | Song title                                    | nil
 @volume     | Volume of MPD mixer                           | 0

Also useful is the -t or --test-widget switch.

% amazing -t mpd
@default    = "Tripswitch - Tachyon"
@album      = "Circuit Breaker"
@artist     = "Tripswitch"
@date       = "2005"
@file       = "Electronic/Tripswitch/Tripswitch_-_Circuit_Breaker-2005-PsyCZ/05-tripswitch_-_tachyon-psycz.mp3"
@genre      = "Ambient"
@id         = 37
@length     = "2:37"
@percentage = 11.4649681528662
@position   = "0:18"
@random     = false
@repeat     = true
@shortfile  = "05-tripswitch_-_tachyon-psycz"
@state      = :playing
@title      = "Tachyon"
@volume     = 0

h2. Format configuration

The format option is actually a Ruby program ran within an instance of the widget type. What this means is you have the full power of Ruby, but don’t have to make it more complex than you want to. Here are some examples:

format: '"#@field1 / #@field2"'

Without the single quotes, the double quotes are interpreted by the YAML parser as enforcing the string type.

format: if @free > 1024 then "#{@free / 1024} GB" else "#@free MB" end

format: @free > 1024 ? "#{@free / 1024} GB" : "#@free MB"

format: |
  if @free > 1024
    "#{@free / 1024} GB"
  else
    "#@free MB"
  end