Org Export

Table of Contents

Home DTOS Knowledge Base Community Contribute Support DT’s Work

Exporting Org Files

At some point you might want to print your notes, publish them on the web, or share them with people not using Org. Org can convert and export documents to a variety of other formats while retaining as much structure and markup as possible.

The libraries responsible for translating Org files to other formats are called back-ends. Org ships with support for the following back-ends:

  • ascii (ASCII format)
  • beamer (LaTeX Beamer format)
  • html (HTML format)
  • icalendar (iCalendar format)
  • latex (LaTeX format)
  • md (Markdown format)
  • odt (OpenDocument Text format)
  • org (Org format)
  • texinfo (Texinfo format)
  • man (Man page format)

Users can install libraries for additional formats from the Emacs packaging system. For easy discovery, these packages have a common naming scheme: ox-NAME, where NAME is a format. For example, ox-hugo for the Hugo markdown back-end. Type M-x package-install and search for ’ox-’ to see some of the packages available.

Org only loads back-ends for the following formats by default: ASCII, HTML, iCalendar, LaTeX, and ODT. Additional back-ends can be loaded in either of two ways: by configuring the org-export-backends variable, or by requiring libraries in the Emacs init file. For example, to load the Markdown back-end, add this to your Emacs config:

(require ’ox-md)

Export Settings

Export options can be set: globally with variables; for an individual file by making variables buffer-local with in-buffer settings; by setting individual keywords or specifying them in compact form with the ‘OPTIONS’ keyword; or for a tree by setting properties. Options set at a specific level override options set at a more general level.

The export keywords available for every back-end, and their equivalent global variables, include:

AUTHOR

The document author (user-full-name).

CREATOR

Entity responsible for output generation (org-export-creator-string).

DATE

A date or a time-stamp.

EMAIL

The email address (user-mail-address).

LANGUAGE

Language to use for translating certain strings (org-export-default-language). With ‘#+LANGUAGE: fr’, for example, Org translates ‘Table of contents’ to the French ‘Table des matières’124.

SELECT_TAGS

The default value is ‘(“export”)’. When a tree is tagged with ‘export’ (org-export-select-tags), Org selects that tree and its sub-trees for export. Org excludes trees with ‘noexport’ tags, see below. When selectively exporting files with ‘export’ tags set, Org does not export any text that appears before the first headline.

EXCLUDE_TAGS

The default value is ‘(“noexport”)’. When a tree is tagged with ‘noexport’ (org-export-exclude-tags), Org excludes that tree and its sub-trees from export. Entries tagged with ‘noexport’ are unconditionally excluded from the export, even if they have an ‘export’ tag. Even if a sub-tree is not exported, Org executes any code blocks contained there.

TITLE

Org displays this title. For long titles, use multiple ‘#+TITLE’ lines.

EXPORT_FILE_NAME

The name of the output file to be generated. Otherwise, Org generates the file name based on the buffer name and the extension based on the back-end format.

The Export Dispatcher

The export dispatcher is the main interface for Org’s exports. A hierarchical menu presents the currently configured export formats. Options are shown as easy toggle switches on the same screen. The keybinding for org-export is:

  • ’C-c C-e’ in standard GNU Emacs
  • ’SPACE m e’ in DOOM Emacs

The DESCRIPTION Tag

I used a DESCRIPTION tag in the header of this org file, but DESCRIPTION was not one of the export keywords listed above. The above list was export keywords available in all back-ends. The DESCRIPTION tag isn’t available in every back-end, but is used when converting to HTML. Let’s ’SPC m e h o’ to convert this document to HTML. Then, view the source of the HTML and look for the description meta tag.

The OPTIONS Tag

Useful for specifying some export settings. A couple of common ones would be:

  • toc:nil
  • num:nil

Example: #+OPTIONS: num:nil

The HTML_HEAD Tag

This is used to add lines to an HTML document’s head. We could use this to link to CSS files, Javascript, Google fonts, etc.

Example: #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="/home/dt/Org/css/styles.css"

Org HTML Themes

Org-HMTL themes is an open source framework for providing you with a list of very nice (cross-browser) themes for all your Org documents. Use them to style your docs, and your colleagues will come up to tell you that you are a genius!

The two themes currently available are:

  • Bigblow
  • ReadTheOrg

Author: Derek Taylor

Created: 2021-08-27 Fri 15:34