13.15 iCalendar Export ¶

A large part of Org mode’s interoperability success is its ability to easily export to or import from external applications. The iCalendar export backend takes calendar data from Org files and exports to the standard iCalendar format.

By default, iCalendar export only includes headings that contain active timestamps or diary sexps¹⁴⁶.

The iCalendar export backend can also incorporate TODO entries based on the configuration of the org-icalendar-include-todo variable. The backend exports plain timestamps as ‘VEVENT’, TODO items as ‘VTODO’, and also create events from deadlines that are in non-TODO items.

The backend uses the deadlines and scheduling dates in Org TODO items for setting the start and due dates for the iCalendar TODO entry. Consult the org-icalendar-use-deadline, org-icalendar-use-scheduled, and org-icalendar-todo-unscheduled-start variables for more details.

For tags on the headline, the iCalendar export backend makes them into iCalendar categories. To tweak the inheritance of tags and TODO states, configure the variable org-icalendar-categories. To assign clock alarms based on time, configure the org-icalendar-alarm-time variable.

The iCalendar format standard requires globally unique identifier—or UID—for each entry. The iCalendar export backend creates UIDs during export. To save a copy of the UID in the Org file set the variable org-icalendar-store-UID. The backend looks for the ‘ID’ property of the entry for reusing the same UID for subsequent exports.

Since a single Org entry can result in multiple iCalendar entries—timestamp, deadline, scheduled item, or TODO item—Org adds prefixes to the UID, depending on which part of the Org entry triggered the creation of the iCalendar entry. Prefixing ensures UIDs remains unique, yet enable synchronization programs trace the connections.

C-c C-e c f (org-icalendar-export-to-ics) ¶

Create iCalendar entries from the current Org buffer and store them in the same directory, using a file extension ‘.ics’.

C-c C-e c a (org-icalendar-export-agenda-files) ¶

Create iCalendar entries from Org files in org-agenda-files and store in a separate iCalendar file for each Org file.

C-c C-e c c (org-icalendar-combine-agenda-files) ¶

Create a combined iCalendar file from Org files in org-agenda-files and write it to org-icalendar-combined-agenda-file file name.

The iCalendar export backend includes ‘SUMMARY’, ‘DESCRIPTION’, ‘LOCATION’, ‘TIMEZONE’ and ‘CLASS’ properties from the Org entries when exporting. To force the backend to inherit the ‘LOCATION’, ‘TIMEZONE’ and ‘CLASS’ properties, configure the org-use-property-inheritance variable.

‘SUMMARY’, ‘LOCATION’, and ‘DESCRIPTION’ properties can define multi-line summary, location, or description using ‘<PROPERTY>+’ syntax (see Property Syntax):

* Meeting at location with multi-line address
<2024-01-08 Mon 14:20-15:00>
:PROPERTIES:
:LOCATION:  Someplace
:LOCATION+: Some Street 5
:LOCATION+: 12345 Small Town
:END:

When Org entries do not have ‘SUMMARY’, ‘DESCRIPTION’, ‘LOCATION’ and ‘CLASS’ properties, the iCalendar export backend derives the summary from the headline, and derives the description from the body of the Org item. The org-icalendar-include-body variable limits the maximum number of characters of the content are turned into its description.

The ‘TIMEZONE’ property can be used to specify a per-entry time zone, and is applied to any entry with timestamp information. Time zones should be specified as per the IANA time zone database format, e.g., ‘Asia/Almaty’. Alternately, the property value can be ‘UTC’, to force UTC time for this entry only.

The ‘CLASS’ property can be used to specify a per-entry visibility class or access restrictions, and is applied to any entry with class information. The iCalendar standard defines three visibility classes:

‘PUBLIC’

The entry is publicly visible (this is the default).

‘CONFIDENTIAL’

Only a limited group of clients get access to the event.

‘PRIVATE’

The entry can be retrieved only by its owner.

The server should treat unknown class properties the same as ‘PRIVATE’.

The exported iCalendar file can advise clients how often to check for updates. This duration can be set globally with the org-icalendar-ttl variable, or on a per-document basis with the ‘ICAL-TTL’ keyword. This option should be set using the iCalendar notation for time durations; consult the docstring of org-icalendar-ttl for more details.

Exporting to iCalendar format depends in large part on the capabilities of the destination application. Some are more lenient than others. Consult the Org mode FAQ for advice on specific applications.