Org Export
Table of Contents
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.
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
Footer
Copyright © 2020-2021 Derek Taylor (DistroTube)
This page is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License (CC-BY-ND 4.0).
The source code for distro.tube can be found on GitLab. User-submitted contributions to the site are welcome, as long as the contributor agrees to license their submission with the CC-BY-ND 4.0 license.