Publishing Articles and Books with Org Mode Export

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.

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.

  ;; 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"))

  #+options: d:t todo:t broken-links:mark toc:2 \\=':nil

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:

1. Create a LibreOffice file to your liking using the Styles menu (press F11),
2. Modify each style to your liking.
3. Test the document.
4. 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 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_class: book
  #+latex_class_options: [a4paper]
  #+latex_header: \usepackage{times}
  #+options: toc:nil

  (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}"))))

  ;; 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"))))

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.

If you like to support my work, then please purchase the Emacs Writing Studio book.

You can find the source files for the book and the latest configuration files on GitHub:

emacs-writing-studio

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.