The release of Org-mode 8.0 (and the git repository master branch, as of commit 1cac3127c) uses a new export framework, developed by Nicolas Goaziou. This document provides information on general changes to Org, as well as the steps needed to update your configuration properly.
If the instructions below do not help solving your problem, please ask any question on the mailing list. Keep in mind that the new export framework is under heavy development, and posting to the mailing list will help not only to resolve your issues, but also make sure that documentation is properly udpated for the benefit of others with similar issues.
This page serves as an upgrade guide for the changes widely affecting users. /Please/ refer to the , which contains an up to date list of Org-mode exporters, and links to backend-specific setup and usage details.
These files have been moved to the
If you were using them, you need to add the
of the Org distribution to the Emacs
The most comprehensive overview of the new exporter may be found in Nicolas' merge announcement in this email to the mailing list. Please scan the post, as you may find answers to your questions there.
Global export options start with the
org-export-* prefix, most of them
are in the
Most generic export options should not require any changes. If you find that a generic option is useless or broken or badly documented in the manual, please report it to the list.
Backend-specific options are now defined via the convention
ox-backend-*. For example:
HTMLand live in
LaTeXand live in
There is a new variable
org-export-backends which controls what backends
are loaded when you lauch Org. By default, the
HTML and =LaTeX=
are loaded; in contrast with the old exporter behavior, others will need to be explicitly
loaded in order to use them. See the upgrade section for instructions.
Some html-specific options were renamed more signficantly or deleted. Examine this table and update accordingly:
|Org 7.9.3f (maint)||Master (8.0)|
|org-export-htmlized-org-css-url||org-org-htmlized-css-url (in ox-org.el|
Some changes also specifically affect
org-publish-project-alist settings. The publishing
functions are not loaded until the corresponding backend has been loaded. You need to
org-publish-project-alist and to use the function from the new publishing engine
in the table below:
|Old publishing engine||New publishing engine|
To specify a style for the project
:style keyword changes to
If something does not work, please report it on the mailing list.
The practical implication for users upgrading from Org-mode < version 7.9.4f is two-fold:
LaTeX, you need to load them
1: Load exporter upon first export execution per session
setq org-export-backends (quote ( beamer md ... taskjuggler)))
2: Loading all listed exporters upon Emacs startup
(require 'ox-beamer) (require 'ox-md) ... (require 'ox-taskjuggler)
Note: Please stick to one of the above two methods!
For users who used the new exporter prior to its integration into the current master branch, here are some additional steps you may need to do in order to upgrade properly:
git pulland any changes to your
ORG_ADD_CONTRIB = org-e-*
org-*(e.g. org-html-xml-declaration, ..)
org-*(e.g. org-latex-classes, org-ascii-bullets, ..)
Again, please refer to Nicolas' announcement about the merge for more details.
In the exporting of a table of contents, options only allowed for setting the level of the deepest table of contents headline, like so:
Upon export, only first and second level headlines would be included in the generated
table of contents. With the new exporter, a dedicated
#+TOC now exists which allows for
futher customization: adding table of contents, lists of tables, and lists of listings at
specific locations during export.
,#+TOC: headlines 2 ,#+TOC: tables ,#+TOC: listings
See the Table of contents section in the manual for more information.
Export snippets are a generalization of
@<tag> concept, which has
been removed, and the inline version of
Their syntax is
backend is the targetted
export backend (e.g.
value can contain anything but
When export is done with
backend, the snippet is replaced with
value, otherwise it is removed. Whitespace characters around
the construct are never deleted.
A footnote definition (not inline) can now be ended with two consecutive blank lines.
As a consequence, multiple paragraphs inside can be written
normally, separated with blank lines, instead of relying on the
#+STYLEoption is now specified with
#+INCLUDE: keyword requires quotes around the file name. Those
are optional in
There is now also a clear difference between these two statements.
The first will only read keyword statements like
#+TODO: and use
this to set up the current file. The second will pull in the entire
content of the file during export. The
#+INCLUDE: statement will
make every headline in the included file will be a child of the
headline containing the include keyword. You can overwrite this
:minlevel num parameter.
#+attr_latex: :width 5cm #+attr_beamer: :options width=5cm #+attr_html: :width 200px
TIP: To upgrade from old
attr_html lines with verbatim HTML
attribute syntax, you could try a Perl one-liner like the following,
filename.org with your file (or a bunch of files with
*.org if you're feeling adventurous -- no warranty, make sure
you're backed up first!).
perl -i.bak -pe "s/([a-z]+)=(\"|')(.*?)\2/:\1 \3/g if /^#\+attr_html/i" filename.org