
Publishing Articles and Books with Org Mode Export

Peter Prevos |
2868 words | 14 minutes
Share this content
Emacs Org mode is an ideal tool for writing without distractions because working with plain text allows you to focus on content instead of design. While writing articles and books in plain text is pleasant and productive, it is not ideal for sharing your work. The Org mode exports your work to PDF leveraging LaTeX, to a website, to a word processor document, an ebook and many more formats. This article explains how to export your work as a journal article, a print-ready book PDF, or an ebook.
Emacs Writing Studio
A comprehensive guide for writers seeking to streamline their workflow using Emacs. The book covers everything from organising ideas and writing distraction-free to publishing in multiple formats. It’s perfect for both beginners and experienced Emacs users, offering practical tips and a tailored configuration to enhance your writing process.
The source files of the book and EWS configuration are also freely available on GitHub.
Org mode export principles
The basic principle of exporting Org mode files to the desired format is that the system converts the text to the relevant format and then connects it to a document class, CSS style sheet or other type of template. Your text file can also link to a local or global bibliography to manage citations. Org mode has built-in export facilities for LaTeX (PDF), HTML and ODT (LibreOffice) and some other formats. Using external packages you can also export to other formats, such as ePub.

In principle you don't need to know HTML or LaTeX, but it will certainly help with fine tuning the output.
The Org mode export function
Org mode includes a powerful export module to convert your files to various formats. Start the export module with the org-export-dispatch
function, which you can run with the default C-c C-e
keyboard shortcut. The dispatch provides a range of options. The first letter you type determines the export format, and subsequent letters the specific options. Using q
exists the export dispatcher.
The Org mode manual describes a myriad of configuration options to fine-tune the look and feel of the exported file. This article describes the basics of the export functionality for PDF files, word processor formats and ebooks.
Export filename
By default, Org mode saves the result of the export process in the same folder as the source document. The exported file has the same name as the source file but with a different extension.
Exporting Denote Org mode files can create a filename conflict because you are effectively creating two files with the same identifier, so ideally you should change the name of the exported file.
You can change this behaviour by adding #+export_file_name: <filename>
to the header. The filename can be any string without file extension. You can save the exported file in another folder, but this might cause errors for certain formats.
Basic settings
Before delving into the specific export formats, some housekeeping sets the defaults on how a document is exported. There are various settings to control how Org mode exports your document, which you add to the front matter of your file, or set them as global variable for all exports. Some generic export variables are:
#+title:
Document title.#+author:
Author name (defaults touser-full-name
).#+date:
Date of publication (You can set the format of the export with theorg-export-date-timestamp-format
variable).
The snippet below ignores drawers (which can be used for writing notes and other functions) and todo keywords in the export. This configuration also ignores broken links, does not produce a table of contents and turns straight quotation marks into more aesthetic curly ones.
;; Org Export Settings
(use-package org
:custom
(org-export-with-drawers nil)
(org-export-with-todo-keywords nil)
(org-export-with-broken-links t)
(org-export-with-toc nil)
(org-export-with-smart-quotes t)
(org-export-date-timestamp-format "%d %B %Y"))
You can override these settings for specific documents with header arguments, as shown below. The d
is for drawers and the mystical looking \\='
for smart quotes. The line below shows drawers and todo markers in the export. This configuration marks broken links, shows two levels of the table of contents and quotation marks are not converted.
#+options: d:t todo:t broken-links:mark toc:2 \\=':nil
Section 13.2 of the Org mode manual explains the various export settings in more detail. Each option can be set as a variable in your configuration or as a line in your Org mode header to fine tune export settings for individual files.
Excluding content from export
Not everything you write should be exported, as suggested in the export defaults in the previous section. The article on writing with Org mode explains how to add comments and notes drawers into your file. Comments with #
and are not exported by default. The ews-org-insert-notes-drawer
command inserts or appends a drawer in the current document section. The Emacs Writing Studio configuration does not export drawers, so your notes remain private.
Furthermore, can also exclude a section of your writing from export by adding the :noexport:
tag. You add a tag to a heading by keying C-c C-q
when the cursor is on or inside the heading. You enter the tag in the minibuffer and you can use completion to find existing tags. The tag appears on the right side of the heading name between colon markers.
Tags in Org mode provide flexible functionality to manage large files or categorise action lists. Org mode has extensive capabilities to use tags, which are not further used in Emacs Writing Studio.
Bibliographic references
Org mode has a built-in citation manager that can use BibTeX / BibLaTeX or CSL files to reference bibliographic items such as articles and books.
The article on managing BibTeX files explains how to create a bibliography. You can create a default bibliography, that is accessible to all Org mode files and specify specific bibliography files for each Org mode file.
When exporting to LaTeX, citations are managed by the external software. When exporting to any other format you need to specify how Org mode manages citations. The default settings in Org mode provide basic citation support.
This website by Tecosaur provides an in-depth description of how to manage citations in Org mode, much better than I can explain it.
Word Processor Export
The export function in Org Mode can export to the ODT format, which is compatible with MS Word, out of the box. The ODT export back-end relies on the zip
program to create the final output
If you have LibreOffice installed, you can also create a docx
file to make it easier for MS Word users to share in the joy of reading your writing. When you set this option, the export process will result in both an odt
and a docx
file. This behaviour is not the default in Emacs Writing Studio, so you must add this yourself if you prefer exporting in the Microsoft format. Alternatively, you can also use this variable to export to PDF.
;; Not included in EWS
;; Export ODT to MS-Word
(setq-default org-odt-preferred-output-format "docx")
;; Export ODT to PDF
(setq-default org-odt-preferred-output-format "pdf")
It is possible to set this option specific to the file you are exporting by adding these three lines somewhere in your Org mode file:
# local variables:
# org-odt-preferred-output-format: "pdf"
# end:
When Org mode exports the file, these lines are evaluated but not exported as they are treated as comments.
You can use specific export settings in the front matter:
#+subtitle:
The document subtitle.#+description:
and#+keywords
are added to the exported file(s) metadata.#+odt_styles_file:
Add the path to an LibreOffice style file (ott
format)
Creating a LibreOffice style file is straightforward:
- Create a LibreOffice file to your liking using the Styles menu (press
F11
), - Modify each style to your liking.
- Test the document.
- Save as
ott
file.
A LibreOffice file is essentially a zip
file with an embedded set of xml
files. Org mode extracts the styles.xml
file embedded in your template file. You cannot use this method for templates (pre-configured content).
You can fine-tune how Org exports to OpenOffice to a great extent. For a detailed discussion on odt
Export, read the online Org mode manual.
LaTeX export
LaTeX is a powerful typesetting system (pronounced “LAY-tek” or “LAH-tek”), especially for writing scientific and technical documents. LaTeX can convert your text into a beautifully designed PDF file for publishing an article, ebook or physical book. Many publishers of technical literature have LaTeX templates to comply with their style guide.
You don’t necessarily need any knowledge of LaTeX to export to PDF. Still, it will certainly help if you like to fine-tune the design of your document. The basic syntax of LaTeX is easy to explain. Let's assume you have a straightforward Org mode file that looks like this:
#+title: Example document
#+author: Peter Prevos
#+latex_class: book
Minimum example for a LaTeX document.
The Latex equivalent of this example is:
\documentclass{article}
\title{Example document}
\author{Peter Prevos}
\begin{document}
\maketitle
Minimum example for a LaTeX document.
\end{document}
The LaTeX software can convert this document to a wonderfully formatted article due to the document class, which defines the typography and layout.
Writing documents directly in LaTeX can be confusing because you need to know its markup language, and your text is littered with backslashes, curly braces, and other syntactical distractions. Being productive as a writer requires focusing on the text’s content instead of how it looks. Org mode is the perfect LaTeX editor because it frees you from distractions and integrates perfectly with LaTeX.
To enable exporting Org mode files to PDF, you need to have LaTeX installed on your system. How to install LaTeX depends on your operating system, and your favourite search engine will point you in the right direction.
Keying C-c C-e
to open the export dispatch, then l p
creates and opens a PDF file. Other options are available to export the buffer to LaTeX or to save a PDF file without opening it.
To make the magic work, Org Mode converts your file to a tex
file, after which the LaTeX software converts it to PDF. The system works out of the box without any configuration. With some configuration you can produce PDF files that are perfect for producing printed books.
Text elements
Org mode converts headers to relevant LaTeX headers, and text becomes a paragraph. The relationship between the heading level in your Org file and LaTeX depends on the configuration, explained below.
Tables and images
Org mode converts images and tables to LaTeX floats. You can add specific attributes to these floats by using #+attr_latex:
, as shown in the image example below:
#+caption: This is an example image caption.
#+attr_latex: :width 5cm :options angle=90 :placement h
[[directory/filename.png]]
Various parameters are available to determine how your table or image looks in the final output. The Org mode manual provides a detailed overview in section 3.10.
LaTeX snippets
You can write simple LaTeX commands directly into your org file. For example, \newpage
will add a page break. You can also place equations using dollar signs, for instance $e^{i\pi} + 1 = 0$
results in $e^{i\pi} + 1 = 0$.
The org-latex-preview
function (C-c C-x C-l
) shows a preview of any LaTeX equations within the open buffer. The chapter on Ricing Org mode introduces the org-fragtog
package to automatically toggle between the plain text and the preview.
To create front and back matter, use the \frontmatter
and \backmatter
LaTeX commands in your Org file at the appropriate locations.
For more complex snippets, you need to use a structure template. Press C-c C-, l
to insert a LaTeX source block. This LaTeX example creates an image using the picture environment.
,#+begin_export latex
\setlength{\unitlength}{1cm}
\begin{picture}(10,10)(-5,5)
\linethickness{1pt}
\put(-2.5,0){\vector(1,0){5}}
\put(0,-2.5){\vector(0,1){5}}
\put(0,0){\circle{3}}
\end{picture}
,#+end_export
The image will not appear in Org mode as it is generated by LaTeX and will only appear when exporting.

LaTeX Packages and Classes
By default, Org mode uses the article class and a set of default packages to export documents. Org mode provides three mechanisms to use LaTeX packages in your export:
- In the header, using
#+latex_header:
- Configuring the
org-latex-packages-alist
variable. - Configure the
org-latex-classes
variable.
The Org mode header can do a lot of the work. The example below specifies the book document class with A4 paper size. This example also specifies the Times fonts package. The last line tells Org mode to omit the table of contents from the export.
#+latex_class: book
#+latex_class_options: [a4paper]
#+latex_header: \usepackage{times}
#+options: toc:nil
The org-latex-packages-alist
variable defines the default packages that are used for every LaTeX export.
You can define more complex header configurations by changing the org-latex-classes
association list.
The example below adds the template for the American Psychological Association (APA) journals. This list's documentation provides all the details you need to configure packages and classes for your exports. The with-eval-after-load
function ensures that this variable is only set once the LaTeX export function is loaded by Emacs. Note the double backslash instead of the single one in regular LaTeX syntax for compatibility with Emacs Lisp.
(with-eval-after-load 'ox-latex
(add-to-list 'org-latex-classes
'("apa6"
"\\documentclass[a4paper, jou, 11pt]{apa6}
\\usepackage[nodoi]{apacite}
\\usepackage{graphicx}
\\usepackage[T1]{fontenc}
\\usepackage{times}"
("\\section{%s}" . "\\section*{%s}")
("\\subsection{%s}" . "\\subsection*{%s}"))))
The last part of this association list specifies the mapping between Org mode and LaTeX headers. In this case, the highest level is associated with the section header, the second level with a subsection, and so on.
You can call this particular class by adding #+latex_class: apa6
to your file header. This mechanism empowers you to define bespoke LaTeX classes to create a library of export options.
These three mechanisms allow fine-grained control over how your Org mode document is exported to LaTeX and PDF. The Emacs Writing Studio configuration only uses the default settings for these variables because the possible use cases are too numerous to define a sensible default other than what is already available.
PDF export configuration
The Emacs Writing Studio configuration for PDF export defines the export process to ensure that bibliographies work appropriately. This configuration also cleans all temporary files that LaTeX creates so that only the exported file remains.
;; LaTeX PDF Export settings
(use-package ox-latex
:ensure nil
:demand t
:custom
;; Multiple LaTeX passes for bibliographies
(org-latex-pdf-process
'("pdflatex -interaction nonstopmode -output-directory %o %f"
"bibtex %b"
"pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
"pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"))
;; Clean temporary files after export
(org-latex-logfiles-extensions
(quote ("lof" "lot" "tex~" "aux" "idx" "log" "out"
"toc" "nav" "snm" "vrb" "dvi" "fdb_latexmk"
"blg" "brf" "fls" "entoc" "ps" "spl" "bbl"
"tex" "bcf"))))
Publishing Ebooks
Most ebook publishers use the ePub format for distribution. This file type is a ZIP file with your book stored as a website optimised for an e-reader. The ox-epub
package adds this functionality to the Org export dispatcher. This package uses the built-in Org to HTML export to create the ebook, so you can use any of its features to fine-tune the output.
;; epub export
(use-package ox-epub
:demand t)
There are some required export options that need to be set in your header:
#+title:
the document title.#+uid:
a unique ID of the document, otherwise known as URI, could be a website or ISBN number.#+date
: the date of the document.#+author:
the document author or editor, the creator in the EPUB spec
The default settings will add a postamble to the bottom of the last page with a timestamp, author and a HTML validation service. Adding #+options: html-postamble:nil
toepub the Org file header removes these from your ebook.
Any LaTeX fragments are ignored in the export, which means it is not possible to export the same source file to both PDF and ePub wit the same output.
However, LaTeX math formulas are possible with the tex:dvipng
option added to the Org header. This option converts any LaTeX formula to a PNG image, which is not ideal but readable.
The ox-epub
package does not convert Org mode timestamps to a date format that complies with the ePub standard. You can correct this by removing the square brackets and the day and time from the timestamp.
Lastly, please note to only use open image formats such as .png
as some ebook readers cannot display JPG files and other proprietary formats. The ebook will look alright on your computer but might not pass any checks by a publisher.
Emacs Writing Studio
If you like to support my work, then please purchase the Emacs Writing Studio book.
Emacs Writing Studio
A comprehensive guide for writers seeking to streamline their workflow using Emacs. The book covers everything from organising ideas and writing distraction-free to publishing in multiple formats. It’s perfect for both beginners and experienced Emacs users, offering practical tips and a tailored configuration to enhance your writing process.
You can find the source files for the book and the latest configuration files on GitHub:
Emacs is a malleable system, so everybody will have their personal preferences to undertake a task. Any article on how to use Emacs is thus opinionated. If you have a different way of doing things, please complete the contact form to send me an email or contact me on social media through the links in the footer.
The next article dives into using Org mode and Hugo to create websites.
Share this content