10.7 Exporting Agenda Views

If you are away from your computer, it can be very useful to have a printed version of some agenda views to carry around. Org mode can export custom agenda views as plain text, HTML¹¹⁵, Postscript, PDF¹¹⁶, and iCalendar files. If you want to do this only occasionally, use the command

C-x C-w     (org-agenda-write)

Write the agenda view to a file. Depending on the extension of the selected file name, the view will be exported as HTML (extension .html or .htm), Postscript (extension .ps), iCalendar (extension .ics), or plain text (any other extension). Use the variable org-agenda-exporter-settings to set options for ps-print and for htmlize to be used during export, for example

(setq org-agenda-exporter-settings
      '((ps-number-of-columns 2)
        (ps-landscape-mode t)
        (org-agenda-add-entry-text-maxlines 5)
        (htmlize-output-type 'css)))

If you need to export certain agenda views frequently, you can associate any custom agenda command with a list of output file names ¹¹⁷. Here is an example that first defines custom commands for the agenda and the global TODO list, together with a number of files to which to export them. Then we define two block agenda commands and specify file names for them as well. File names can be relative to the current working directory, or absolute.

(setq org-agenda-custom-commands
      '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
        ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
        ("h" "Agenda and Home-related tasks"
         ((agenda "")
          (tags-todo "home")
          (tags "garden"))
         nil
         ("~/views/home.html"))
        ("o" "Agenda and Office-related tasks"
         ((agenda)
          (tags-todo "work")
          (tags "office"))
         nil
         ("~/views/office.ps" "~/calendars/office.ics"))))

The extension of the file name determines the type of export. If it is .html, Org mode will use the htmlize.el package to convert the buffer to HTML and save it to this file name. If the extension is .ps, ps-print-buffer-with-faces is used to produce Postscript output. If the extension is .ics, iCalendar export is run export over all files that were used to construct the agenda, and limit the export to entries listed in the agenda. Any other extension produces a plain ASCII file.

The export files are not created when you use one of those commands interactively because this might use too much overhead. Instead, there is a special command to produce all specified files in one step:

C-c a e     (org-store-agenda-views)

Export all agenda views that have export file names associated with them.

You can use the options section of the custom agenda commands to also set options for the export commands. For example:

(setq org-agenda-custom-commands
      '(("X" agenda ""
         ((ps-number-of-columns 2)
          (ps-landscape-mode t)
          (org-agenda-prefix-format " [ ] ")
          (org-agenda-with-colors nil)
          (org-agenda-remove-tags t))
         ("theagenda.ps"))))

This command sets two options for the Postscript exporter, to make it print in two columns in landscape format—the resulting page can be cut in two and then used in a paper agenda. The remaining settings modify the agenda prefix to omit category and scheduling information, and instead include a checkbox to check off items. We also remove the tags to make the lines compact, and we don’t want to use colors for the black-and-white printer. Settings specified in org-agenda-exporter-settings will also apply, but the settings in org-agenda-custom-commands take precedence.

From the command line you may also use

emacs -eval (org-batch-store-agenda-views) -kill

or, if you need to modify some parameters¹¹⁸

emacs -eval '(org-batch-store-agenda-views                      \
              org-agenda-span (quote month)                     \
              org-agenda-start-day "2007-11-01"                 \
              org-agenda-include-diary nil                      \
              org-agenda-files (quote ("~/org/project.org")))'  \
      -kill

which will create the agenda views restricted to the file ~/org/project.org, without diary entries and with a 30-day extent.

You can also extract agenda information in a way that allows further processing by other programs. See Extracting agenda information, for more information.