
The [calendars] section
***********************

The *[calendars]* is mandatory and must contain at least one
subsection. Every subsection must have a unique name (enclosed by two
square brackets). Each subection needs exactly one *path* setting,
everything else is optional. Here is a small example:

   [calendars]

     [[home]]
       path = ~/.calendars/home/
       color = dark green

     [[work]]
       path = ~/.calendars/work/
       readonly = True

path

   The path to an existing directory where this calendar is saved as a
   *vdir*. The directory is searched for events or birthdays (see
   "type") but the search is not recursive.

      type:
         string

      default:
         None

readonly

   setting this to *True*, will keep khal from making any changes to
   this calendar

      type:
         boolean

      default:
         False

type

   Set the type of this collection, the default is "calendar". If set
   to "birthdays" khal will expect a VCARD collection and extract
   birthdays from those VCARDS. "birthdays" also implies
   "readonly=True". If set to "calendar" only files with the ".ics"
   extension will be used, if set to "birthdays" only files with the
   ".vcf" extension will be used, if it is set to "discover" khal will
   use all subdirectories of "paths"'s that contain only ".ics" files.

      type:
         option, allowed values are *calendar*, *birthdays* and
         *discover*

      default:
         calendar

color

   khal will use this color for coloring this calendar's event. The
   following color names are supported: *black*, *white*, *brown*,
   *yellow*, *dark gray*, *dark green*, *dark blue*, *light gray*,
   *light green*, *light blue*, *dark magenta*, *dark cyan*, *dark
   red*, *light magenta*, *light cyan*, *light red*. Depending on your
   terminal emulator's settings, they might look different than what
   their name implies. In addition to the 16 named colors an index
   from the 256-color paltte or a 24-bit color code can be used, if
   your terminal supports this. The 256-color paltte index is simply a
   number between 0 and 255. The 24-bit color must be given as
   #RRGGBB, where RR, GG, BB is the hexadecimal value of the red,
   green and blue component, respectively. When using a 24-bit color,
   make sure to enclose the color value in ' or "! If the color is set
   to *auto* (the default), khal tries to read the file *color* from
   this calendar's vdir, if this fails the default_color (see below)
   is used. If color is set to '', the default_color is always used.

      type:
         color

      default:
         auto


The [sqlite] section
********************

path

   khal stores its internal caching database here, by default this
   will be in the *$XDG_DATA_HOME/khal/khal.db* (this will most likely
   be *~/.local/share/khal/khal.db*).

      type:
         string

      default:
         None


The [locale] section
********************

The most important options in the the **[locale]** section are
probably (long-)time and dateformat.

longdateformat

   khal will display and understand all dates in this format, it
   should contain a year (e.g. *%Y*) see timeformat for the format.

      type:
         string

      default:
         %d.%m.%Y

longdatetimeformat

   khal will display and understand all datetimes in this format, it
   should contain a year (e.g. *%Y*) see timeformat for the format.

      type:
         string

      default:
         %d.%m.%Y %H:%M

unicode_symbols

   by default khal uses some unicode symbols (as in 'non-ascii') as
   indicators for things like repeating events, if your font, encoding
   etc. does not support those symbols, set this to *False* (this will
   enable ascii based replacements).

      type:
         boolean

      default:
         True

weeknumbers

   Enable weeknumbers in *calendar* and *interactive* (ikhal) mode. As
   those are iso weeknumbers, they only work properly if
   *firstweekday* is set to 0

      type:
         weeknumbers

      default:
         off

firstweekday

   the day first day of the week, were Monday is 0 and Sunday is 6

      type:
         integer, allowed values are between 0 and 6

      default:
         0

datetimeformat

   khal will display and understand all datetimes in this format, see
   timeformat for the format.

      type:
         string

      default:
         %d.%m. %H:%M

default_timezone

   this timezone will be used for new events (when no timezone is
   specified) and when khal does not understand the timezone specified
   in the icalendar file. If no timezone is set, the timezone your
   computer is set to will be used.

      type:
         timezone

      default:
         None

local_timezone

   khal will show all times in this timezone If no timezone is set,
   the timezone your computer is set to will be used.

      type:
         timezone

      default:
         None

timeformat

   khal will display and understand all times in this format.

   The formatting string is interpreted as defined by Python's
   strftime, which is similar to the format specified in "man
   strftime".

      type:
         string

      default:
         %H:%M

encoding

   set this to the encoding of your terminal emulator

      type:
         string

      default:
         utf-8

dateformat

   khal will display and understand all dates in this format, see
   timeformat for the format

      type:
         string

      default:
         %d.%m.


The [keybindings] section
*************************

keybindings for **ikhal** are set here. You can bind more than one key
(combination) to a command by supplying a comma-separated list of
keys. For binding key combinations just add concatenate them (with a
space in between), e.g. **ctrl n**.

new

   create a new event on the selected date

      type:
         list

      default:
         n

mark

   go into highlight (visual) mode to choose a date range

      type:
         list

      default:
         v

save

   save the currently edited event and leave the event editor

      type:
         list

      default:
         meta enter

left

   move the cursor left (in the calendar browser)

      type:
         list

      default:
         left, h, backspace

up

   move the cursor up (in the calendar browser)

      type:
         list

      default:
         up, k

other

   in highlight mode go to the other end of the highlighted date range

      type:
         list

      default:
         o

delete

   delete the currently selected event

      type:
         list

      default:
         d

duplicate

   duplicate the currently selected event

      type:
         list

      default:
         p

search

   open a text field to start a search for events

      type:
         list

      default:
         /

view

   show details or edit (if details are already shown) the currently
   selected event

      type:
         list

      default:
         enter, tab

right

   move the cursor right (in the calendar browser)

      type:
         list

      default:
         right, l, space

down

   move the cursor down (in the calendar browser)

      type:
         list

      default:
         down, j

export

   export event as ICS

      type:
         list

      default:
         e

today

   focus the calendar browser on today

      type:
         list

      default:
         t


The [default] section
*********************

The default section begins with a **[default]** tag. Some default
values and behaviours are set here.

show_all_days

   By default, khal displays only dates with event in "agenda" view.
   Setting this to *True* will show all days in "agenda", even when
   there is no event

      type:
         boolean

      default:
         False

highlight_event_days

   If true, khal will highlight days with events. Options for
   highlighting are in [highlight_days] section.

      type:
         boolean

      default:
         False

days

   By default, khal show events for today and tomorrow. Setting this
   to a different value will show events of that amount of days by
   defaut.

      type:
         integer

      default:
         2

default_calendar

   The calendar to use if none is specified for some operation (e.g.
   if adding a new event). If this is not set, such operations requre
   an explicit value.

      type:
         string

      default:
         None

print_new

   After adding a new event, what should be printed to standard out?
   The whole event in text form, the path to where the event is now
   saved or nothing?

      type:
         option, allowed values are *event*, *path* and *False*

      default:
         False

default_command

   command to be executed if no command is given when executing khal

      type:
         option, allowed values are *calendar*, *agenda*,
         *interactive*, *printformats*, *printcalendars* and **

      default:
         calendar


The [view] section
******************

The view section contains config options that effect the visual
appearance when using ikhal

theme

   Choose a color theme for khal.

   This is very much work in progress. Help is really welcome! The two
   currently available color schemes (*dark* and *light*) are defined
   in *khal/ui/themes.py*, you can either help improve those or create
   a new one (see below). As ikhal uses urwid, have a look at urwid's
   documentation for how to set colors and/or at the existing schemes.
   If you cannot change the color of an element (or have any other
   problems) please open an issue on github.

   If you want to create your own color scheme, just copy the
   structure of the existing ones, give it a new and unique name and
   also add it as an option in *khal/settings/khal.spec* in the
   section *[default]* of the property *theme*.

      type:
         option, allowed values are *dark* and *light*

      default:
         dark

frame

   Whether to show a visible frame (with *box drawing* characters)
   around some (groups of) elements.

      type:
         boolean

      default:
         False

event_view_always_visible

   Set to true to always show the event view window when looking at
   the event list

      type:
         boolean

      default:
         False

bold_for_light_color

   Whether to use bold text for light colors or not. Non-bold light
   colors may not work on all terminals but allow using light
   background colors.

      type:
         boolean

      default:
         True

event_view_weighting

   This is the weighting that is applied to the event view window

      type:
         integer

      default:
         1


The [highlight_days] section
****************************

When highlight_event_days is enabled, this section specifies how is
the highlighting rendered.

default_color

   Default color for calendars without color - when se to '' it
   actually disables highlighting for events that should use the
   default color.

      type:
         color

      default:
color

   What color to use when highlighting - explicit color or use
   calendar color when set to ''

      type:
         color

      default:
method

   Highlighting method to use - foreground or background

      type:
         option, allowed values are *foreground*, *fg*, *background*
         and *bg*

      default:
         fg

multiple

   How to color days with events from multiple calendars - either
   explicit color or use calendars' colors when set to ''

      type:
         color

      default: