Upgrading to Org 8.0 or the current master branch

Some html-specific options were renamed more signficantly or deleted. Examine this table and update accordingly:

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 update org-publish-project-alist and to use the function from the new publishing engine in the table below:

To specify a style for the project :style keyword changes to :html-head

If something does not work, please report it on the mailing list.

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:

1. Issue make clean before git pull and any changes to your configuration.

2. If you had already been using the new exporter from contrib, you should remove the following lines from your local.mk:

   ORG_ADD_CONTRIB = org-e-*
   

3. Export engine renamed from org-export to ox
4. Backend requires renamed org-e-* to ox-*
5. All backend specific variables and functions renamed:
   • org-export-* to org-* (e.g. org-html-xml-declaration, ..)
   • org-e-* to org-* (e.g. org-latex-classes, org-ascii-bullets, ..)
6. Generic export variables retain the name org-export-*, (e.g. org-export-dispatch-use-expert-ui, org-export-filter-headline-functions, ..)
7. org-latex-to-pdf-process renamed org-latex-pdf-process
8. This is a guess, export snippets and backend symbols renamed:
   • e-<backend> to <backend>

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:

#+OPTIONS: TOC:2

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 #+begin_backend...#+end_backend blocks.

Their syntax is @@backend:value where backend is the targetted export backend (e.g. html) and 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 \par command.

• The #+STYLE option is now specified with #+HTML_HEAD

• Using #+SETUPFILE: file versus #+INCLUDE: "file".

  #+INCLUDE: keyword requires quotes around the file name. Those are optional in #+SETUPFILE:.

  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 behaviour with :minlevel num parameter.

• Attribute lines now take plists (similar to Babel code block syntax):

  #+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, replacing 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
  

• Beamer backend now interprets nested headline levels as blocks instead of lists. For more guidance, see this page.