Support via Liberapay

Creating letters with KOMA-Script scrlttr2 and Org-mode

This tutorial describes the necessary steps to produce beautiful letters using the Org-mode LaTeX exporter and the KOMA-Script scrlttr2 letter class.

Quick start guide


The code in this tutorial depends on the following:

  • org-mode version 8.0 or greater (part of Emacs 24.4);
  • a LaTeX installation including KOMA-Script, e.g., TeX Live.

Note: The information in this tutorial depends on functionality that has not yet been released and it not part of Emacs. You can either use the latest development version from the Org-mode git repository or download a current version of the KOMA-Script letter exporter and install it in your load-path, e.g. contrib/lisp in the Org-tree or ~/.emacs.d/lisp. It is also strongly recommended to read the comments at the beginning of the file for information or changes that have not yet been documented here.

Minimal configuration of the KOMA-Script letter exporter

To use the KOMA-Script letter exporter, you have to add it to Emacs's load path, activate it, and optionally configure a LaTeX class for the LaTeX exporter (the KOMA-Script letter exporter uses the LaTeX exporter internally).

  1. Add the path containing ox-koma-letter.el to the Emacs load-path. For example, add the following to your Emacs configuration:

    (add-to-list 'load-path "/path/to/org-mode/lisp")
  2. Activate the KOMA-Script letter exporter by adding the following to your Emacs configuration:

    (eval-after-load 'ox '(require 'ox-koma-letter))
  3. The KOMA-Script exporter comes with minimal latex class default-koma-letter that is enabled by default. You may add your own customized class, my-letter, as follows:

    (eval-after-load 'ox-koma-letter
         (add-to-list 'org-latex-classes
         (setq org-koma-letter-default-class "my-letter")))

    A more complicated example is presented in the commentary section of ox-koma-script.el.

    Note that you may have to add the LaTeX Babel package to you preamble, e.g., as

    (eval-after-load 'ox-latex
      '(add-to-list 'org-latex-packages-alist '("AUTO" "babel" t) t))

    For more information about this step, refer to the documentation of the variables org-latex-classes, org-latex-default-packages-alist, and org-latex-packages-alist.

A simple letter example

Printed below is a minimal Org file that can be exported as a KOMA-Script letter. In this file, press C-c C-e to bring up the exporter dispatcher and then press k o to export the Org file to a PDF file. For your convenience, you can download the KOMA letter example and you can also download the example PDF letter.

* Preamble                                                         :noexport:

#+TITLE:  Mis-shapen chaos of well-seeming forms!
#+DATE: 1580
#+AUTHOR: Romeo

# This file is released by its authors and contributors under the GNU
# Free Documentation license v1.3 or later, code examples are released
# under the GNU General Public License v3 or later.

#+SUBJECT: Or: org-mode and KOMA-Script letters
#+PLACE: Verona, Italy

#+LCO: DINmtext
# NOTE: Check the KOMA-Script manual to find a LCO that fits the
#       envelope standards of your country.

# NOTE: Change the order of the backletter, use smart quotes and
#       include backaddress
#+OPTIONS: after-closing-order:(my_after_signature ps cc encl)
#+options: ':t backaddress:t subject:centered

# Remove the first header
#+LATEX_HEADER: \setkomavar{firsthead}{}

* To-address of the lovely Juliet                                        :to:
# NOTE: Explicit newlines are not necessary in TO and FROM
House of Capulet

* From                                                                 :from:
House of Montague
* Location                                                         :location:
#+LATEX_HEADER: \usepackage{tikz}
\tikz \draw (0,0) --+ (0,-1)
       arc [radius=1, start angle=-180, end angle=0]
       --+ (0,1) -- cycle
       node [below=1.5em,midway] {\bfseries M};

* Dear Juliet,
# NOTE: Your letter is the first non-special heading.  The title of
# this heading may used as an opening.

Then plainly know my heart's dear love is set
On the fair daughter of rich Capulet:
As mine on hers, so hers is set on mine;
And all combin'd, save what thou must combine
By holy marriage: when, and where, and how
We met, we woo'd, and made exchange of vow,
I'll tell thee as we pass; but this I pray,
That thou consent to marry us to-day.

* Yours truly,                                                      :closing:
Romeo of House Montague
* some arbitrary LaTeX code                              :my_after_signature:
% this special heading was added dynamically.
* PS                                                                     :ps:
PS: "PS" is not typeset automatically by KOMA-Script

@@latex:\noindent@@ PPS: This is a feature!
* CC                                                                     :cc:
Paris and Lawrence.
* ENCL                                                                 :encl:
See also The Tragedy of Romeo and Juliet
* some more arbitrary LaTeX code                               :after_letter:
% here we can place random LaTeX code, e.g. including PDFs via the pdfpages package.

Since no LaTeX_CLASS has been specified the default class will be used. The first block of lines specify title, subject and date. PLACE specify the closing sentence and the place from which the letter is send.

The address of the receiver is specified in the special heading with the :to: tag. Note that the headline text is arbitrary and ignored.

The main letter is the first non-special heading1. Notice that the text of this headline also serves as the opening of the letter. The closing of the letter is set via the closing special heading. Note that closing statement is the headline title and the signature is the content.

Finally, the 'backmatter' printed after the signature are defined in the tree special heading with the tags ps, cc and encl. With the OPTION after-closing-order we can reorder the ordering of the 'backmatter'. The content of the after_letter heading is inserted after \end{letter}. This is useful executing arbitrary latex commands. For instance, we may want to include PDFs via the pdfpages package.

ox-koma-letter.el also supports an alternative syntax that relies less on headings as illustrated by the example in this Org-file and the corresponding pdf.

When composing new letters it may be useful to start with template by typing C-c C-e # and choosing koma-letter.

Learning more about KOMA-Script Letter

org-koma-letter.el exports a LaTeX document utilizing the scrlttr2 class of KOMA-Script. The document class is described in great details in chapter 4 of the KOMA-Script manual. If you have TeXLive you can open the manual with the command texdoc KOMA-Script and with MiKTeX one might call mthelp KOMA-Script.

Elements such as the address-field is automatically typeset using user-provided metadata, or variables, such as address, sender name etc. A full list of variables are available in table 4.1 and an illustration of placement of variables is shown in figure 4.9, both the in KOMA-Script manual. A subset of these are supported directly by ox-koma-letter.el.

Placement of elements is typically defined by a LCO file. If, for instance, the DIN LCO file is loaded, letters are typeset to fit German DIN envelopes. See table 4.18 in the KOMA-Script manual for default classes.

You can customize the look of your letter by writing your own LCO files and including them with the #+LCO: keyword. See Setting letter metadata in LCO files.

Configuration guide

In addition to the actual content a typical letter also contains additional information, such as the sender's and recipient's addresses, a date, and so on. From now on we refer to this additional data as letter metadata.

A special group of letter metadata controls the appearance of the letter, such as the presence of foldmarks or a back address. These are called letter options.

Setting letter metadata and letter options

Letter metadata can be configured in one of four ways, listed below from the most specific to the most general:

  1. using Org option lines, as show in the simple letter example above,
  2. by using separate Org LaTeX classes,
  3. by setting Emacs variables, or
  4. in a KOMA-Script Letter Class Option file (LCO file).

We cover these in turn.

Multiple LaTeX Classes

It is possible to define multiple LaTeX classes for different types of letters using the method used above. For example one could add a special Org LaTeX class, say foo-copr, for sending letters to the stakeholders of Foo Corp, that loads the Foo Logo, specifies the footer and so forth. The class is then loaded by inserting #+LATEX_CLASS: foo-corp.

Setting letter metadata in Org option lines

A simple way to set letter metadata on-the-fly is by using Org option lines as used in the simple letter example above where we used both special headings and keywords.

Some letter options are set using an #+OPTIONS: line in the same manner as other Org mode export options.

A list of KOMA letter metadata settings is provided below.

Metadata set in the file takes the highest priority. Thus, you can set default letter metadata using Emacs variables or in an LCO file (see below). Then, you can tweak your letter options in the file itself.

If you write a letter as a subtree of an Org heading, you must use Org properties inside a :PROPERTIES: drawer and prefix every option property with the string EXPORT_. See the chapter Export options in the Org manual for details.

Setting letter metadata in Emacs variables

Letter metadata can also be set using Emacs variables, e.g., in your init-file. For example, the Emacs Lisp snippet below sets the letter's closing line and the location.

(setq org-koma-letter-closing "See you soon,"
      org-koma-letter-from-address "Verona")

A list of KOMA letter metadata settings is provided below.

Setting letter metadata in LCO files

A third way, letter metadata can be set in so-called letter class option files (LCO files). LCO files are regular TeX files which are included in the TeX source of the letter. Consequently, one has access to the entirety of KOMA-Script options in LCO files and can also include other LaTeX code. For more information about LCO files, see the KOMA-Script documentation.

LCO files are set by the #+LCO: LCO1 LCO2 option line or the Emacs variable org-koma-letter-class-option-file. KOMA-Script comes with a variety of pre-made LCO files, such as DIN for German letters, NF for French letters, or UScommercial9 for US-American letters.

Letter metadata set in LCO files overwrites letter metadata set in Emacs variables but not letter metadata set in the Org file.

LCO files are convenient as modules that can be loaded to access particular setups across letters. Examples include the sender's address, the first footer and header, banking information, or the inclusion of a scanned signature. A particularly useful LaTeX command is \ifkomavarempty{KOMAVAR}{TRUE}{FALSE} that can be used to condition the printed output depending on whether KOMAVAR is set or not. See the example under \setkomavar{frombank} in the KOMA-Script manual (currently page 183).

The following LCO file, called DefaultAddress.lco, sets the default address. It can loaded using the Org option line #+LCO: DefaultAddress (without the .lco extension).

% Default letter configuration file

% Default address
\setkomavar{fromname}{Jane Doe}
\setkomavar{fromaddress}{Some Street 1\\12345 Some City}
\setkomavar{fromphone}{(555) 526-3363}

The following LCO file, called Banking.lco, configures a footer with banking information. To load it together with the default address defined above one can use the Org option line #+LCO: DefaultAddress Banking.

% Banking information configuration file

% Banking information in the footer
\setkomavar{frombank}{Jane Doe\\Account number: 12\,345\,678\\Somebank\\Bank code number: 876\,543\,21}

Custom LCO files must be placed in a directory where LaTeX will find them. On GNU/Linux, this defaults to ~/texmf/tex/latex. On OS X, use ~/Library/texmf/tex/latex. In TeX Live, these paths can be configured using the following command:

tlmgr conf texmf TEXMFHOME ~/some/path

You can test whether foo.lco is recognized by TeX Live by running the command kpsewhich foo.lco. After adding a file to the TeX Live path you may have to run mktexlsr.

List of KOMA-Script letter metadata settings

This section tries to list all Org option lines, Emacs variables, and the corresponding ox-koma-letter variables or options that control the behavior of the KOMA-Script letter exporter.

To get a complete list of variables please use the Customize interface, e.g. by typing

M-x custromize-group org-export-koma-letter

List of ox-koma-letter letter metadata

The following letter metadata can be set by respective Org option lines. In general, they correspond to a LaTeX command such as:

\setkomavar{<KOMA variable>}{<value>}
Option line Emacs variable KOMA-Script variable Description
#+LCO: org-koma-letter-class-option-file   The default LCO file.
#+FROM_LOGO org-koma-letter-from-logo fromlogo The sender's logo.
#+TITLE:   title The title of the letter.
#+SUBJECT:   subject The subject of the letter
#+DATE:   date The time-stamp of the letter.
#+LOCATION: org-koma-letter-location   The space opposite the to address
#+PLACE: org-koma-letter-place place The place of the letter.
#+AUTHOR: org-koma-letter-sender fromname The sender's name.
#+FROM_ADDRESS: org-koma-letter-from-address fromaddress The sender's address.2
#+PHONE_NUMBER: org-koma-letter-phone fromphone The sender's phone number.
#+URL org-koma-letter-url fromurl The sender's URL, e. g., the URL of her homepage
#+EMAIL: org-koma-letter-email fromemail The sender's email.
#+TO_ADDRESS:     The recipient's address.3
#+OPENING: org-koma-letter-opening   The opening line of the letter.4
#+CLOSING: org-koma-letter-closing   The closing line of the letter.5
#+SIGNATURE: org-koma-letter-signature signature The sender's signature.
#+LATEX_CLASS: org-koma-letter-default-class   Corresponds to org-latex-default-class

List of ox-koma-letter options

The following letter options can be set in an #+OPTIONS: line. In general, they correspond to a LaTeX command such as:

\KOMAoption{<KOMA option>}{<value>}
Option Emacs variable KOMA-Script option Description
after-closing-order org-koma-letter-special-tags-after-closing   Order or special headlines such as ps, cc, and encl
after-letter-order org-koma-letter-special-tags-after-letter   Order or special headlines such as after_letter
backaddress org-koma-letter-use-backaddress backaddress Print the sender's address in a line above the recipient's address.
phone org-koma-letter-use-phone fromphone Print the sender's phone.
url org-koma-letter-use-url fromurl Print the sender's URL
email org-koma-letter-use-email fromemail Print the sender's email.
foldmarks org-koma-letter-use-foldmarks foldmarks If and how foldmarks are printed.
subject org-koma-letter-subject-format subject If and how to print the letter's subject line.
place org-koma-letter-use-place   Print the letter's place stamp.
from-logo org-koma-letter-use-from-logo fromlogo Insert the sender's logo.

List of ox-koma-letter special headings

Special headings may be used to input metadata in ox-koma-letter documents. A special heading is simply a heading with a recognized tag. Their usages were illustrated in the example above. Special headings tags are defined in the variables org-koma-letter-special-tags-in-letter, org-koma-letter-special-tags-after-closing, and org-koma-letter-special-tags-after-letter. Note that these can also be dynamically set via the options after-closing-order and after-letter-order. Currently the following special headings are recognized.

Tag KOMA-Script Description
to \begin{letter}{to} To-address. Alternative to #+TO_ADDRESS:.
from fromaddress From-address. Alternative to +FROM_ADDRESS:.
closing closing and signature headings title and signature. Alternative to #+CLOSING: and #+SIGNATURE:
after_closing   Content is inserted after \closing{.}.
ps \ps{} Wrap content in a ps-macro.
cc \cc{} Wrap content in a cc-macro.
encl \encl{} Wrap content in a encl macro.
after_letter   Content is inserted after \end{letter}.



A special headings in ox-koma-letter is a heading with a recognized tag. These headings are treated specially.


If the letter is exported below an Org headline, the default subject contains the Org headline text.


The options lines #+FROM_ADDRESS:, #+TO_ADDRESS:, can be used multiple times and may also be specified using headlines cf. the example above.


The options lines #+OPENING: and #+CLOSING: cannot be set in an LCO file.


See the KOMA script documentation for a list of accepted values.

Documentation from the website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.