Export
The exporter is a port of Emacs Org 9.8.10 ox.el and its back-ends: the buffer is parsed into the same element tree as org-element, and each back-end turns it into text with the same transcoders, so the output of HTML, LaTeX, Beamer, Markdown, ASCII, Org, iCalendar, Texinfo, KOMA-Script letters and man pages matches Emacs.
<prefix>e (Emacs C-c C-e) opens the export dispatcher:
| b / s / v / f / a | toggle body only / subtree only / visible only / force publishing / async (also <C-b> <C-s> <C-v> <C-f> <C-a>) |
| c f | iCalendar: current file |
| c a | iCalendar: every agenda file |
| c c | iCalendar: combined |
| h H / h h / h o | HTML buffer / file / file and open |
| i t / i i / i o | Texinfo file / Info file / Info file and open |
| k L / k l | KOMA letter buffer / file |
| k p / k o | KOMA letter PDF / PDF and open |
| l L / l l | LaTeX buffer / file |
| l p / l o | LaTeX PDF / PDF and open |
| l B / l b | Beamer buffer / file |
| l P / l O | Beamer PDF / PDF and open |
| m M / m m / m o | Markdown buffer / file / file and open |
| m G / m g | GFM buffer / file |
| M m | man file |
| M p / M o | man PDF (groff) / PDF and open |
| O O / O o / O v | Org buffer / file / file and open |
| o o / o O | ODT file / ODT and open |
| d d | DOCX (pandoc) |
| t A / t a | ASCII buffer / file |
| t L / t l | Latin-1 buffer / file |
| t U / t u | UTF-8 buffer / file |
| H H / H h / H A | Hugo post (org-extensions-hugo, when it is on) |
| P f | publish the file |
| P p | publish the current project |
| P x | publish a project |
| P a | publish all projects |
| p | other format via pandoc |
| & | the export stack (org-export-stack) |
| # | insert the default export template |
The toggles start from export.initial_scope ("buffer" or "subtree"), export.body_only, export.visible_only, export.force_publishing and export.in_background (Emacs org-export-initial-scope, -body-only, -visible-only, -force-publishing, -in-background). With export.dispatch_use_expert_ui (org-export-dispatch-use-expert-ui) there is no menu, only the prompt "Export command (C-bvsfa) [keys]: " with the active options highlighted; ? switches to the menu. "As ... buffer" exports show their buffer in a split unless export.show_temporary_export_buffer is false (the buffer is still made). export.copy_to_kill_ring (true, "if-interactive" or false) also puts the output in the unnamed register and the clipboard. export.coding_system (org-export-coding-system) is the encoding of exported files, an iconv() name such as "latin1"; nil is UTF-8. export.process_citations = false leaves citations to the back-end (they export as nothing, like Emacs) and export.replace_macros = false keeps macros unexpanded (they also export as nothing; with Babel on, a macro other than {{{results}}} stops the export, like Emacs). export.smart_quotes_alist gives the smart quotes of a language (org-export-smart-quotes-alist); a language set there replaces its entry of the Emacs table.
Asynchronous export
With the dispatcher's a toggle, export.in_background or :Org export {format} async, the dispatcher returns at once and the result is not shown but added to the export stack. :Org export_stack (the dispatcher's &) lists it: number, back-end, age and the file or buffer. <CR> or v views the entry at the cursor (a file like a file link: HTML or PDF with the system opener, links.file_apps honoured; with a count in Neovim), d removes it from the stack, x cancels it while it runs (:Org export_stack_cancel, which elsewhere cancels the newest running export), C clears the stack (:Org export_stack_clear), g refreshes, q closes. Like Emacs' org-export-async-start, a separate Neovim (nvim --clean --headless) exports a copy of the buffer with the session's options, minus their Lua functions (filters, hooks, format functions): export.async_init_file (org-export-async-init-file) is a Lua file it runs first to set them. The buffer and the options are copied when the export starts, so editing the buffer meanwhile doesn't change the result. Prompts are answered "no" there, so Babel blocks that need a confirmation keep their results. Visible-only exports need the folds and run in this Neovim instead, right after the dispatcher closes.
While an export runs, its age is "run" and its source the buffer with the output of its process ("*Org Export Process*", or the compiler's output buffer); viewing it shows that output as it comes. When it is done, the entry becomes the result and "Asynchronous export finished: FILE" is shown. When it fails, the error is shown (for a PDF: the "File ... wasn't produced" message of Emacs and the error lines of the LaTeX output), and the entry stays with the output, aged "exit", as Emacs keeps the buffer of a process that "exited abnormally". Cancelling kills the process with the programs it started (pdflatex under latexmk, LibreOffice, the separate Neovim): the entry stays as "signal". Running exports are cancelled when Neovim quits.
The external part of an ordinary export runs in the background as well: the PDF compilation of l p, l o, k p, M p, ... (unless export.latex.async_compile is false) and the conversion of an ODT file to export.odt.preferred_output_format (unless export.odt.async_convert is false). Neovim doesn't wait for them; they are on the export stack while they run (where x cancels them), "and open" opens the file once it's there, and a notification says when it's done ("PDF file produced" or "Exported to FILE") or why it failed. Without a UI (headless, scripts) they run to the end before the export returns. The Lua part of the export (Org to LaTeX, ODT XML, HTML) runs in Neovim itself, as in Emacs: on a document of 3,000 headlines (16,000 lines) it takes about 0.6 s for LaTeX and 1 s for ODT; with a it runs in the separate Neovim too.
Convert region
In Visual mode the actions convert_region_to_html, _latex, _md, _ascii, _utf8 and _texinfo (Emacs org-html-convert-region-to-html, org-latex-convert-region-to-latex, ...) replace the selection with its body-only export, the selection being exported on its own like a temporary Org buffer. :[range]Org convert_region {format} does the same for lines (any native format), and :[range]Org export_region_to_html (latex, md, ascii, utf8, texinfo) are the Emacs org-export-region-to-* aliases.
:Org export {format} [subtree] [body] [visible] [buffer] [open] [async] where format is html, md, gfm, ascii (or txt), latin1, utf8, latex, pdf, beamer, beamer-pdf, org, ics, odt, texinfo (or texi), info, koma-letter (or koma), koma-pdf, man, man-pdf or a pandoc format (docx, rst, epub, ...). :Org publish [project|file|current|all] [force] publishes projects (org-publish). Lua: require("org.export").export(format, opts) returns the output path, .to_string(format, opts) the text.
Output goes next to the source file (named after it or #+EXPORT_FILE_NAME), or to export.output_dir. PDF compiles the LaTeX file with export.latex.pdf_process (latexmk when available, else three runs of export.latex.compiler); it runs in the background with vim.system() unless export.latex.async_compile is false (org-export-stack), its output going to the "*Org PDF LaTeX Output*" buffer. ODT is written natively (org-export-odt). DOCX and other pandoc formats run pandoc on the output of the Org back-end.
Live HTML preview
:Org preview exports the buffer with the HTML back-end and opens the page in the browser, served by a small HTTP server inside Neovim (vim.uv, no other program). Each write of the buffer (:w, and org's own saves) exports it again and the page reloads, keeping its scroll position; with export.preview.on_change = "text" it also follows typing, debounce ms after the last change. Moving the cursor to another heading scrolls the page to that heading (sync_cursor). When an export fails the page keeps the last good version and shows the error at the bottom (a page opened while the export fails shows it too), and Neovim warns once until an export works again. :Org preview_toggle starts or stops the preview of the buffer, :Org preview_stop stops it (every preview when the buffer has none). A preview also stops when its buffer is wiped out and when Neovim quits.
The page is exported like :Org export html (#+HTML_HEAD, #+OPTIONS and the export.html options apply), except that no code from the document runs: source blocks are not evaluated (the results already in the buffer are shown), #+MACRO: name (eval FORM) macros show as "[macro NAME not evaluated in the preview]", and Lisp header values are not sent to Emacs, unless export.preview.evaluate_babel is true. Images and other links relative to the Org file are served from its directory, so they show as they would next to an exported file (videos can seek: the server answers byte ranges); absolute paths and links to other Org files (exported as .html) don't resolve. The export runs in Neovim itself (about a second for 16,000 lines), so on large files "write" suits better than "text".
One server, on a free port, serves every previewed buffer, each under its own random path (http://127.0.0.1:PORT/p/TOKEN/); it stops with the last preview. Options (export.preview):
export = { preview = {
host = "127.0.0.1", -- keep it on loopback (see below)
port = 0, -- 0 = a free port
open_browser = true, -- false: only show the URL; a command
-- ({ "open", "-a", "Safari" }, "firefox") or
-- function(url)
on_change = "write", -- or "text"
debounce = 300, -- ms, for "text"
sync_cursor = true,
evaluate_babel = false,
stylesheet = nil, -- a URL, or a CSS file added to the page
} }
open_browser as a list ({ "open", "-a", "Safari" }) passes each item as one argument; a string is taken whole when it is the path of a program, and split on spaces otherwise. host takes an address ("127.0.0.1", "::1"), "localhost" (127.0.0.1) or a host name, looked up when the server starts.
Browsers open at most about six connections to one host and port at a time, and each open preview page keeps one for its event stream: with more than five previews open in one browser, further pages and their images wait. Close the pages you don't need (or open some through localhost instead of 127.0.0.1, which the browser counts apart).
Security: the server answers only GET and HEAD, listens on 127.0.0.1 by default, and serves only the page and the regular files below the directory of the Org file that the page refers to (its images, links, <link>ed stylesheets and the fonts and images those use); any other file is "404 Not Found", so a document in a large directory (~/todo.org) doesn't show the rest of it. Paths with .., . or hidden (dot) segments, absolute or drive paths, backslashes and NUL bytes are refused, and a symlink that leads out of the directory is refused too. Each preview's path holds 128 random bits, and requests whose Host isn't the server's own address (127.0.0.1:PORT, localhost:PORT) are refused, so a web page can't reach it by pointing its own domain name at this machine (DNS rebinding). A connection that doesn't send its request within 15 seconds is closed. Other users and programs on the same machine can still connect to the port; anything that knows the path can read the files the page refers to while the preview runs. Setting host to another address (or "0.0.0.0") shows them to the network and warns when the server starts.
Preview only documents you trust: raw HTML in the document (#+HTML:, @@html:...@@, export blocks, #+HTML_HEAD) goes into the page as it is, and its scripts run in the browser on the preview's address, where they can read the files the page refers to. The page is sent with a Content-Security-Policy that keeps it from connecting to or posting forms to other sites (connect-src 'self'; form-action 'self'), but it can still load images and scripts from anywhere.
Export settings
#+TITLE, #+SUBTITLE, #+AUTHOR, #+EMAIL, #+DATE, #+CREATOR, #+LANGUAGE, #+SELECT_TAGS, #+EXCLUDE_TAGS, #+EXPORT_FILE_NAME, #+KEYWORDS, #+DESCRIPTION and back-end keywords (#+HTML_HEAD, #+HTML_LINK_HOME, #+HTML_DOCTYPE, #+HTML_CONTAINER, #+LATEX_CLASS, #+LATEX_CLASS_OPTIONS, #+LATEX_HEADER, #+LATEX_HEADER_EXTRA, #+LATEX_COMPILER, #+BEAMER_THEME, ...) as in Emacs. #+OPTIONS: takes every Emacs key: ': *: -: :: <: \n: ^: arch: author: broken-links: c: creator: d: date: e: email: f: H: inline: num: p: pri: prop: stat: tags: tasks: tex: timestamp: title: toc: todo: |: and the back-end ones (html-postamble:, html-preamble:, html-style:, html5-fancy:, html-link-use-abs-url:, ...). Values are read like Emacs, so lists work: tasks:("TODO" "NEXT"), d:(not "LOGBOOK"). Every key has a default in export (org-config-export), named after the Emacs variable. When exporting a subtree, its EXPORT_TITLE, EXPORT_FILE_NAME, EXPORT_OPTIONS, EXPORT_AUTHOR, EXPORT_DATE, EXPORT_LATEX_CLASS, ... properties override the keywords. # in the dispatcher inserts the default template (#+options:, #+title: ... lines, or EXPORT_* properties in subtree mode).
#+LANGUAGE: translates the generated strings ("Table of Contents", "Footnotes", "Figure", ...) with the Emacs dictionary, and smart quotes (':t) use that language's quotes.
Select tags (export) export only the tagged subtrees; exclude tags (noexport) and COMMENT subtrees are removed; archived subtrees keep only their headline (arch:). Headlines deeper than H: become lists. Visible only (v) exports what is not folded.
Links: internal links ([[*Heading]], [[#custom-id]], [[name]], [[target]], radio targets, id: links, coderefs) resolve to generated labels; a link that resolves to nothing stops the export with an error unless broken-links:t (drop it) or broken-links:mark. In HTML, a file: link with a search option ([[file:x.org::*Heading]], [[file:notes.txt::some words]]) points at the headline's CUSTOM_ID when it has one, else at #MissingReference with a warning (outside publishing), as in Emacs. The search must find something in the file (in an Org file a headline, target, name or coderef; in any other file the words anywhere), or the link is broken. Links whose type has an export function in links.types use it, like org-link-parameters :export. #+TOC: headlines 2 [local], #+TOC: tables and #+TOC: listings insert lists anywhere.
#+INCLUDE: "file.org" includes a file; its headlines become children of the current one (or start at :minlevel N). Add ::*Heading, ::#id or ::name to include one subtree or named element, :only-contents t to drop the subtree's headline, :lines "5-10", or src LANG / example / export BACKEND to include it as a block. #+SETUPFILE: reads the keywords of another file.
#+INCLUDE: https://… (and #+SETUPFILE:, see org-setupfile) downloads the file (with curl) only when resource_download_policy allows it (org-resource-download-policy): "prompt" (default) downloads URLs matching safe_remote_resources and asks about the others, "safe" downloads only those, true downloads everything (dangerous) and false only the safe ones (like Emacs). A URL is safe when it, or "file://" followed by the exporting file's name, matches one of the Vim regexes of safe_remote_resources (org-safe-remote-resources). The question offers, like Emacs:
| y <Space> | download it, just this once |
| n | skip it: the export stops with "The remote resource … is considered unsafe, and will not be downloaded." |
| ! | download it and mark the URL safe |
| d | download it and mark its domain (https://example.com) safe |
| f | download it and mark everything the file requests safe |
The URLs, domains and files marked safe are kept in stdpath("data")/org/safe-remote-resources.json (Emacs saves them with customize). A download is reused for the rest of the session.
Macros: #+MACRO: name text $1 $2 ($0 = all arguments, \, a literal comma, macros may use other macros), export.global_macros (strings or Lua functions) and the built-ins {{{title}}}, {{{author}}}, {{{email}}}, {{{date(FMT)}}}, {{{time(FMT)}}}, {{{modification-time(FMT)}}}, {{{input-file}}}, {{{keyword(NAME)}}}, {{{property(NAME[,search])}}}, {{{n(name[,-|N])}}} and {{{results(...)}}}. Like Emacs, {{{title}}}, {{{author}}}, {{{email}}}, {{{date}}} and {{{keyword(NAME)}}} read the keywords written in the file itself (and its #+INCLUDEd text), not those of a #+SETUPFILE; the #+MACRO definitions of a setup file apply. {{{modification-time(FMT,t)}}} takes the date of the file's last Git commit (Emacs asks any VC back-end). As in Emacs, macros are replaced in the text before it is parsed: a macro that expands to nothing on a line of its own ends the paragraph, and one whose value starts with - at the start of a line makes a list item. The whole file is gone through in order, also for a subtree export, and the macros of #+TITLE, #+AUTHOR, #+DATE, #+SUBTITLE (and the other keywords the back-end parses, such as LaTeX's #+DESCRIPTION) and of their EXPORT_ properties are replaced where they are: {{{n}}} counters follow the document.
#+MACRO: name (eval FORM) macros evaluate the Emacs Lisp FORM like org-macro: $1...$N are variables bound to the arguments (strings, nil when missing; a $1 inside a string stays as it is) and the value is inserted with format "%s". FORM runs on the Lisp interpreter of table formulas (org-table-calc), which also has org-texinfo-kbd-macro (the Org manual's #+MACRO: kbd (eval (org-texinfo-kbd-macro $1)) works), and for other functions in a separate emacs --batch with Org and ox loaded (babel.emacs_lisp), started in the file's directory; results are kept for the export. Without Emacs such a macro gives a warning and exports as nothing (Emacs has no such case).
#+BIND: VARIABLE VALUE sets an export variable for the export of the buffer when export.allow_bind_keywords is true (Emacs org-export-allow-bind-keywords, off by default for safety). The variable becomes the option it mirrors: org-export-NAME is export.NAME, org-BACKEND-NAME is export.BACKEND.NAME for html, latex, md, ascii, odt, texinfo, icalendar, beamer, org and cite (- becomes _), user-full-name / user-mail-address are export.author / export.email, and org-export-creator-string, org-html-container-element, org-latex-packages-alist, org-latex-default-packages-alist, org-inlinetask-min-level and org-table-number-fraction map to creator, html.container, latex.packages, latex.default_packages, inlinetask_min_level and table_number_fraction. VALUE is read, not evaluated, like Emacs: strings, numbers, t (true), nil (false), symbols (their name: #+BIND: org-html-checkbox-type unicode), lists (("a" "b"), (not "LOGBOOK"), (1 . 2)); org-export-global-macros, org-export-snippet-translation-alist, org-html-postamble-format and org-html-preamble-format take alists. Other variables are ignored (Emacs sets any variable), and so is a value in a shape the option does not use. Unlike Emacs, a quote before a list is dropped ('("a") is ("a")). Options set in the file (#+OPTIONS, keywords) and passed to the export still override them, like Emacs.
Code blocks follow :exports when babel.evaluate_on_export is true (the default, Emacs org-export-use-babel): results are computed in a copy of the buffer, with the usual babel.confirm_evaluate question. When it is false the buffer is exported as it is.
Hooks and filters (Emacs org-export-before-processing-functions, org-export-before-parsing-functions and org-export-filter-*-functions) are Lua functions:
export = {
hooks = { before_parsing = function(backend, lines) return lines end },
filters = {
["final-output"] = function(text, backend, info) return text end,
headline = { function(text) return text end },
},
}
A key may be written with underscores (parse_tree, plain_text, final_output); the filters run after the back-end's own of that type.
Back-ends
| HTML | ox-html: XHTML strict by default (#+HTML_DOCTYPE: html5, html5-fancy:t), default CSS, MathJax, postamble "auto" (author, date, creator, validation link), #+ATTR_HTML, #+HTML_HEAD, info.js (#+INFOJS_OPT), inline images. LaTeX (tex:, export.html.with_latex, org-html-with-latex): MathJax (t, "mathjax"), pictures in ltximg/ next to the output with a LaTeX preview process ("dvipng", "dvisvgm", "imagemagick", or one of ui.latex_preview.processes), "html" runs export.html.latex_to_html_convert_command (org-latex-to-html-convert-command, %i = the fragment) on each fragment, "verbatim" or false keep the LaTeX. Source code is coloured from its tree-sitter highlights (Emacs uses htmlize): export.html.htmlize_output_type "inline-css" (default) puts the colour scheme's colours in style attributes, "css" writes classes named htmlize_font_prefix ("org-") + the Emacs face (org-keyword, org-string, org-comment, org-function-name, ...), false leaves the code plain. export.html.indent (org-html-indent) indents the document the way Emacs' mhtml-mode does (CSS and JavaScript by bracket depth); a body-only export takes the indentation of its first line, like Emacs' fundamental-mode. :Org html_htmlize_generate_css (org-html-htmlize-generate-css) shows the stylesheet of those classes in a "*html*" buffer. A language without a tree-sitter parser stays plain, like a language without an Emacs mode. export.html.fontify, a function(code, lang), replaces the built-in highlighting. |
| LaTeX / PDF | ox-latex: classes (export.latex.classes, #+LATEX_CLASS), packages, labels, figures and tables with #+ATTR_LATEX (:width :float :placement :environment :mode :align :booktabs :caption ...), math environments, special blocks as environments, babel/polyglossia from #+LANGUAGE, src_block_backend verbatim, listings, minted or engraved. Engraved (engrave-faces) colours code from its tree-sitter highlights with \EF<face> commands defined in the preamble (engraved_preamble, engraved_options); engraved_theme or #+LATEX_ENGRAVED_THEME (and :engraved-theme in #+ATTR_LATEX) picks the colours: engrave-faces' "default" preset (nil), the current colour scheme (true or "t") or a named colour scheme. |
| Markdown | ox-md (headline_style "atx", "setext" or "mixed"); tables and other constructs without Markdown syntax become HTML. |
| GFM | GitHub flavoured Markdown (pipe tables, fenced code, - [ ] task lists), format "gfm". |
| ASCII | ox-ascii: :Org export ascii, latin1 or utf8; export.ascii.charset sets the default ("ascii"). |
| Org | ox-org: the buffer after macro expansion, #+INCLUDE and removal of non-exported subtrees. |
| iCalendar | org-export-icalendar |
| Beamer | org-export-beamer |
| Texinfo | org-export-texinfo |
| ODT | org-export-odt |
| KOMA letter | org-export-koma-letter |
| Man | org-export-man |
| Hugo | ox-hugo's Hugo-compatible Markdown with TOML or YAML front matter, an extension (org-extensions-hugo). |
ASCII
ascii exports plain text like Emacs ox-ascii. Text is filled to export.ascii.text_width columns (default 72; the older export.text_width is still read) with two spaces after sentences. center, justifyright and justifyleft blocks align their text, and link targets are listed as notes after each section unless export.ascii.links_to_notes is false. export.ascii.charset ("ascii", "latin1" or "utf-8") picks the characters used for entities, bullets, checkboxes, rules and table borders; the Latin-1 and UTF-8 dispatcher entries override it. The other layout options (margins, spacing, bullets, underlines, caption position, verbatim format, drawer and inlinetask formatters) mirror the Emacs org-ascii-* variables of the same name. With table_use_ascii_art (org-ascii-table-use-ascii-art) table.el tables are drawn with box characters in UTF-8 exports, like the ascii-art-to-unicode package (every "-" and "|" of the table, and each "+" as the junction its neighbours need).
Beamer
:Org export beamer (dispatcher: l B buffer, l b file, l P PDF, l O PDF and open) writes a Beamer presentation, derived from the LaTeX exporter like Emacs ox-beamer. Headlines at the frame level (H:, default export.beamer.frame_level = 1) become frames, shallower ones sections and deeper ones blocks. A headline with BEAMER_env: frame sets the frame level of its subtree. Properties:
| BEAMER_env | block alertblock theorem definition example exampleblock proof quote quotation verse structureenv onlyenv beamercolorbox, frame fullframe note noteNH appendix ignoreheading againframe columns column (plus export.beamer.environments_extra) |
| BEAMER_act | overlay (<2->), or a default overlay in brackets [<+->] |
| BEAMER_opt | frame/block options (allowframebreaks, label=x, ...) |
| BEAMER_col | column width (fraction of \columnwidth) |
| BEAMER_ref | frame resumed by againframe |
| BEAMER_subtitle | frame subtitle |
Frames with code or verbatim text get the fragile option. An @@beamer:<2->@@ snippet at the start of an item, bold text, link or radio target is its overlay; #+ATTR_BEAMER: :overlay <+-> :options ... applies to lists and images. Keywords: #+BEAMER_THEME, #+BEAMER_COLOR_THEME, #+BEAMER_FONT_THEME, #+BEAMER_INNER_THEME, #+BEAMER_OUTER_THEME (all accept [options]name), #+BEAMER_HEADER, #+BEAMER: (raw line), #+SUBTITLE, #+TOC: headlines N [options]. With toc: an outline frame titled export.beamer.outline_frame_title is added.
Beamer mode
:Org beamer_mode toggles org-beamer-mode in the buffer; it is on from the start with startup_with_beamer_mode = true (org-startup-with-beamer-mode) or #+STARTUP: beamer. While it is on, <C-c><C-b> (mappings.beamer.beamer_select_environment; it replaces "previous sibling" like in Emacs) runs beamer_select_environment (org-beamer-select-environment): a fast tag selection of B_ENV tags, one key per environment (f frame, b block, c column, C columns, n note, ...), sets BEAMER_env (pressing the key of the current environment removes it); | toggles BMCOL and asks for the column width (BEAMER_col), A makes an againframe and asks for BEAMER_ref and BEAMER_act. Setting BEAMER_env or BEAMER_col as a property also updates the B_ENV / BMCOL tags, which are highlighted with OrgBeamerTag. Toggling fires the OrgBeamerMode User autocmd (org-beamer-mode-hook), data = { bufnr, enabled }.
Texinfo
:Org export texinfo (dispatcher i t, Emacs C-c C-e i t) writes a Texinfo manual like Emacs ox-texinfo; info (i i, i o to open it with info) then runs export.texinfo.info_process (default makeinfo --no-split %f) and removes the index log files. The document gets the header (@setfilename, @settitle, class header with @documentencoding / @documentlanguage), a @direntry, the title page, @contents (toc:), the Top node holding the text before the first headline, and a master @menu with a detailed node listing. Each headline is a @node with the sectioning command of the class (numbered, unnumbered, @heading-like when excluded from the TOC, appendix); deeper ones (H:) become list items. Keywords:
| TEXINFO_FILENAME | Info file name (@setfilename) |
| TEXINFO_CLASS | class in export.texinfo.classes (default "info") |
| TEXINFO_HEADER | lines added to the header (repeatable) |
| TEXINFO_POST_HEADER | lines added after the header |
| SUBTITLE, SUBAUTHOR | title page |
| TEXINFO_DIR_CATEGORY, TEXINFO_DIR_NAME (or _TITLE), TEXINFO_DIR_DESC | the @dircategory and @direntry of the Info directory |
| TEXINFO_PRINTED_TITLE | @title of the printed manual |
| CINDEX FINDEX KINDEX PINDEX TINDEX VINDEX | index entries; TEXINFO raw |
Headline properties: COPYING (contents become @copying, shown on the title page), APPENDIX, INDEX (cp, fn, ky, pg, tp, vr: adds @printindex), ALT_TITLE (menu entry and node name), DESCRIPTION (menu description). Emphasis maps to @strong, @emph, @code and @samp (export.texinfo.text_markup_alist); @, {, } and commas are escaped. #+ATTR_TEXINFO: options: lists :enum, :table-type (ftable, vtable), :indic, :sep, :compact (or compact-itemx:t); tables :columns (@columnfractions, else the widest cells); images :width :height :alt; quotes :tag :author; special blocks :options. Description items named Function:, Command:, Macro:, Special Form:, Variable:, User Option: become @defun, @deffn... blocks and Key: C-c C-c (command) items get @kbd, @kindex and @findex. Captions make @float with @caption / @shortcaption; links become @ref, @uref, @email (and info: links @ref to the other manual); footnotes @footnote; LaTeX math @math / @displaymath when with_latex is true or makeinfo supports it. Key bindings use org-texinfo-kbd-macro like the Org manual, #+MACRO: kbd (eval (org-texinfo-kbd-macro $1)), or its Lua version as a global macro:
export = { global_macros = { kbd = function(key)
return require("org.export.texinfo").kbd_macro(key)
end } }
Set export.texinfo.use_pandoc = true to go through pandoc instead.
ODT
:Org export odt (dispatcher: o o file, o O file and open) writes an OpenDocument Text file like Emacs ox-odt: content.xml, styles.xml (the factory OrgOdtStyles.xml of Emacs), meta.xml (title, author, date, keywords, description) and the manifest, zipped by a pure-Lua writer (no zip program needed). The transcoders are those of ox-odt: numbered and unnumbered headings (outline numbering follows num:), a table of contents (toc:, #+TOC: headlines N [local]), text styles, links (internal ones become cross-references showing the section, item or sequence number; [[url][file:img.png]] is a clickable image), ordered/unordered/description lists with checkboxes, headlines deeper than H: as lists, tables (header rows, column groups, <l>/<r>/<c> alignment, <N> widths as column ratios, tables in lists), src, example, quote, verse, center blocks, textbox and annotation special blocks, inline tasks, footnotes (native ODF notes), planning, clocks, timestamps, #+ODT: / #+BEGIN_EXPORT odt / @@odt:...@@ raw XML, and captions ("Table 1:", "Figure 1:", "Listing 1:" numbered per section down to export.odt.display_outline_level). Images ([[file:img.png]], jpeg/jpg/png/gif/svg) are embedded under Images/; #+ATTR_ODT: :width W :height H (cm), :scale S and :anchor as-char|paragraph|page (:style, :attributes) size and place them; the pixel size comes from the file header (or ImageMagick identify) at export.odt.pixels_per_inch. Links to .mml/.mathml/.odf files embed the formula. LaTeX (tex:): with export.odt.latex_to_mathml_convert_command (e.g. "latexmlmath %i --presentationmathml=%o") fragments and environments become embedded MathML formulas; tex:dvipng, tex:dvisvgm or tex:imagemagick render them to pictures with the LaTeX preview processes; without the programs, or with tex:verbatim, they are kept as code (with a warning, like Emacs). Tables: #+ATTR_ODT: :rel-width 50 sets the width in percent, :style NAME applies a template of export.odt.table_styles (org-odt-table-styles), :header-columns N styles the first columns as headers; #+ATTR_ODT: :list-table t turns a two-level list into a table. Source blocks are colorized with tree-sitter highlights when a parser is available (Emacs uses htmlfontify): one OrgSrc<Capture> text style per highlight capture, colored like the current colorscheme (fontify_srcblocks, create_custom_styles_for_srcblocks). Styles: #+ODT_STYLES_FILE: "file" (or export.odt.styles_file) uses a styles.xml, or the styles.xml of an .odt/.ott file, and #+ODT_STYLES_FILE: ("file.ott" ("styles.xml" "image/hdr.png")) also copies the other members into the document (reading .odt/.ott files needs unzip). #+ODT_EXTRA_STYLES: (or export.odt.extra_styles, a plugin addition) adds raw style XML to <office:styles>. export.odt.preferred_output_format ("pdf", "docx", "doc", ...) converts the result with convert_process ("LibreOffice": soffice --headless --convert-to, or "unoconv"; convert_processes, convert_capabilities), in the background unless export.odt.async_convert is false (org-export-stack); require("org.export.odt").convert(file, format) converts any file (org-odt-convert); :Org odt_convert asks for the file and the output format (with a count it opens the result). :Org odt_export_as_odf (org-odt-export-as-odf) converts a LaTeX fragment to MathML with latex_to_mathml_convert_command and writes it as an OpenDocument formula, FILE.odf; the fragment is the first one of the Visual selection (or typed at the prompt) and the file name is asked for. odt_export_as_odf_and_open also opens the file. export.odt.use_pandoc = true exports ODT with pandoc instead. Lua: require("org.export").export("odt", opts); to_string("odt") returns content.xml. Differences: use_date_fields, with_forbidden_chars, the drawer, headline and inlinetask format functions work as in Emacs; the output matches Emacs except for a few Emacs slips that are not copied: labels of unnamed captioned images are not called "nil", [[#custom-id][desc]] links point to the heading's bookmark, meta.xml gets the title without markup, and inline source blocks (an error in Emacs) are exported as code. The MathML of each fragment is kept in export.odt.latex_mathml_directory ("ltxmathml/" next to the Org file, org-latex-mathml-directory) and reused while the fragment and the command are unchanged.
KOMA-Script letters
:Org export koma-letter (dispatcher k L buffer, k l file, k p PDF, k o PDF and open; Emacs C-c C-e k) writes a scrlttr2 letter like Emacs ox-koma-letter, derived from the LaTeX back-end (so every LaTeX keyword and option applies); koma-pdf compiles it like org-export PDF. The class is export.koma_letter.default_class ("default-koma-letter", added to the LaTeX classes as \documentclass[11pt]{scrlttr2}) or #+LATEX_CLASS. Keywords (defaults from export.koma_letter):
| LCO | letter class option files (\LoadLetterOption), "NF" |
| AUTHOR EMAIL | sender name and email (fromname, fromemail) |
| FROM_ADDRESS | sender address (repeatable; lines become \\) |
| TO_ADDRESS | recipient (repeatable; "\mbox{}" when missing) |
| PHONE_NUMBER URL FROM_LOGO PLACE LOCATION SIGNATURE | letter variables |
| SUBJECT | \setkomavar{subject}; #+TITLE becomes the title |
| OPENING CLOSING | \opening{} and \closing{} |
| KOMA-LETTER | raw line (also #+begin_export koma-letter, and @@koma-letter:...@@ like LaTeX snippets) |
#+OPTIONS items: backaddress, email, phone, url, from-logo, place (show or hide the field), foldmarks (t, nil or a list like (b l m t)), subject (t, nil or a list like (underlined centered)), title-subject (the title is the subject when there is no SUBJECT), special-headings (headlines win over keywords), after-closing-order and after-letter-order (lists of tags). Settings from the config are written before the LCO files and in-buffer ones after them, so the buffer overrides the LCO files. Headlines are not exported as sections: a headline tagged to, from, location or closing sets the recipient, the sender address, the location or the closing (its contents are the signature); ps, cc and encl become \ps{}, \cc{}, \encl{} after the closing, after_closing and after_letter raw text after the closing / after \end{letter}. The first untagged headline is the opening (when there is no OPENING keyword, or with special-headings); its contents are the letter body.
Man pages
:Org export man (dispatcher M m; Emacs C-c C-e M) writes a groff man(7) page like Emacs ox-man (this replaces the former pandoc export). man-pdf (M p, M o to open) runs export.man.pdf_process (default three runs of tbl %f | eqn | groff -man | ps2pdf - > %b.pdf) and removes export.man.logfiles_extensions files (remove_logfiles). The page starts with .TH "TITLE" "SECTION" "DATE" "RELEASE" "HEADER" from #+TITLE, #+DATE and #+MAN_CLASS_OPTIONS: :section-id "8" :release "tool 1.0" :header "User Commands" (section 1 by default). Level 1 headlines are .SH, levels 2 and 3 .SS, deeper ones (and those below H:) .TP items. Lists become .IP / .TP items with \(em, \(bu, \(dg bullets and check boxes, emphasis \fB / \fI, code \fC, sub/superscripts \d \u, blocks .RS/.nf, verse .ft I, center .ce. Tables use tbl(1): #+ATTR_MAN: :expand t :placement center|left :boxtype allbox :divider t :title-line t :long-cells t :disable-caption t :verbatim t, with export.man.tables_centered, tables_verbatim and table_scientific_notation ("%sE%s"). #+MAN: lines, #+begin_export man and @@man:...@@ are copied. Footnotes, timestamps, planning lines, inline tasks and horizontal rules are dropped, like Emacs; links are written as "URL \fBat\fP \fIdesc\fP". With export.man.source_highlight source blocks go through GNU source-highlight (source_highlight_langs maps the languages). Differences: man-pdf compiles with pdf_process (Emacs 9.8 passes the page to org-latex-compile, which fails), and inline source blocks call source-highlight from the PATH (Emacs looks for it in the current directory).
iCalendar
Dispatcher keys (Emacs C-c C-e c): c f current file, c a every agenda file (one .ics each), c c all agenda files combined into export.icalendar.combined_agenda_file ("~/org.ics"). Lua: require("org.export.icalendar").export_file(), .export_agenda_files(), .combine_agenda_files(), .to_string(lines). Entries become VEVENTs from active timestamps (with_timestamps, <:), DEADLINE ("DL: " prefix, use_deadline) and SCHEDULED ("S: ", use_scheduled); with include_todo TODO entries also become VTODOs (DTSTART/DUE, RRULE with UNTIL, PRIORITY from the priority cookie, STATUS). Repeaters (+1w) give RRULE; APPT_WARNTIME or alarm_time adds a VALARM; SUMMARY, LOCATION, DESCRIPTION, CLASS and TIMEZONE properties are honoured; the body is the DESCRIPTION (include_body). Tags and the category go to CATEGORIES (categories). #+ICALENDAR_EXCLUDE_TAGS and #+ICAL-TTL are read. Files use CRLF line endings and lines folded at 75 octets (RFC 5545). Differences: entries without an ID get a UID derived from the file and the entry (stable across exports) instead of a random one; ++/.+ repeaters give no RRULE (like Emacs); BBDB anniversaries are not supported. Diary sexps (%%(...) lines with include_sexps, and <%%(...)> timestamps) become VEVENTs with an RRULE like Emacs' diary iCalendar library does: diary-anniversary (yearly), diary-block (daily until the end), diary-cyclic (every N days), diary-float (the Nth weekday of a month) and diary-date (arguments in agenda.calendar_date_style order); a time (<%%(...) 10:00-11:30>) gives the start time and a DURATION. Recurrences start at their first date from January 1 of last year, like Emacs. Other sexps are skipped with a warning (Emacs cannot convert them either), and the UID is Org's (DS1-ID, TS1-ID) where Emacs 31 makes up its own.
Citations
Citations written as [cite/STYLE:prefix @key suffix] are rendered on export by a citation processor, chosen with #+CITE_EXPORT: NAME [BIBSTYLE [CITESTYLE]] or by export.cite.export_processors (default: "basic" for every back-end). Bibliography files come from #+BIBLIOGRAPHY: keywords (BibTeX .bib/.bibtex or CSL-JSON .json, relative to the exported file) and export.cite.global_bibliography. #+PRINT_BIBLIOGRAPHY: inserts the bibliography at that point. Processors:
| basic | any back-end; styles author (a), noauthor (na), nocite (n), text (t), note (ft), numeric (nb) and the default; variants bare (b), caps (c), bare-caps (bc); bibliography styles "plain", "numeric" or author-year (default). |
| natbib | LaTeX; \citep, \citet, ... and \bibliography. |
| biblatex | LaTeX; \autocite, \textcite, ..., multi-cite commands, \printbibliography[OPTIONS] from ":key value" properties; loads biblatex and adds \addbibresource lines. |
| bibtex | LaTeX; \cite, \nocite and \bibliography. |
| csl | any back-end; formats with a Citation Style Language style (#+CITE_EXPORT: csl [STYLE.csl], default the bundled Chicago author-date style; relative names are looked up next to the file, then in export.cite.csl_styles_dir). Styles author (a), noauthor (na), year (y), text (t), title (ti), bibentry, locators (l), nocite (n) with the variants bare, caps, full... HTML back-ends get HTML, LaTeX back-ends LaTeX (the \cslbibliography environment; its preamble, csl_latex_preamble, is added before \begin{document}), others Org markup. Locators are read from the suffix ("p. 12", "chap. 3", a bare number is a page). Note styles put citations in footnotes. #+PRINT_BIBLIOGRAPHY: takes the filters :type, :nottype, :csltype, :notcsltype, :keyword and :notkeyword (sub-bibliographies). Options: csl_styles_dir, csl_locales_dir (more locales; en-US is bundled), csl_link_cites, csl_no_citelinks_backends { "ascii" }, csl_html_hanging_indent, csl_html_label_width_per_char, csl_latex_hanging_indent, csl_latex_label_separator, csl_latex_label_width_per_char, csl_latex_preamble and csl_bibtex_titles_to_sentence_case (all under export.cite). The formatting engine is a Lua port of citeproc-el. |
Note styles turn a citation into a footnote, moving punctuation according to export.cite.note_rules and the document LANGUAGE.
Publishing
Projects are set in export.publish.projects (org-publish-project-alist):
export = { publish = { projects = {
site = { base_directory = "~/org/site", publishing_directory = "~/www",
recursive = true, publishing_function = "html",
auto_sitemap = true, sitemap_title = "My site",
makeindex = true },
static = { base_directory = "~/org/site", base_extension = "png\\|css",
publishing_directory = "~/www", recursive = true,
publishing_function = "attachment" },
all = { components = { "site", "static" } },
} } }
Keys are the Emacs plist properties with _ for -. publishing_function is "html", "latex", "pdf", "beamer", "md", "gfm", "ascii", "latin1", "utf8", "org", "texinfo", "attachment", a Lua function(plist, file, pub_dir) or a list. With "org" and htmlized_source = true, the source is also written as coloured HTML, FILE.org.html, by Neovim's :TOhtml (Emacs uses htmlize); export.org.htmlized_css_url (org-org-htmlized-css-url) links that stylesheet instead of embedding the styles. exclude and base_extension are Vim regular expressions matched against file names relative to base_directory. Other keys (with_toc, html_postamble, ...) are export options for the project's files. Only files changed since they were last published (or whose #+INCLUDE files changed) are published; the timestamps live in export.publish.timestamp_directory (default stdpath("data")/org-timestamps/, Emacs uses ~/.org-timestamps/). With a site map (auto_sitemap) a "sitemap.org" listing the files ("tree" or "list" style, sorted with sitemap_sort_files / sitemap_sort_folders) is written and published; makeindex collects #+INDEX: entries into theindex.inc / theindex.org. Links to headlines of other project files point to the right anchor. Functions: require("org.export.publish").publish_all(force), publish_project(name, force), publish_current_file(force), publish_current_project(force).
Not supported
These need Emacs Lisp or Emacs itself:
#+BIND:sets only the export variables that have an option (see org-export macros and #+BIND); other variables, and values that are functions or must be evaluated, are ignored.(eval ...)macros see nothing of an Emacs session: forms beyond the Lisp interpreter run in a separateemacs --batchwith an empty scratch buffer (buffer-file-name,org-with-point-atand the like don't see the document). Without Emacs they export as nothing, with a warning.- Source fontification: HTML uses tree-sitter highlights instead of htmlize (org-export-backends), so the spans differ from Emacs' font-lock. LaTeX with
src_block_backend = "engraved"writes the same LaTeX as engrave-faces, but with the faces of tree-sitter's highlights: where tree-sitter and the Emacs major mode disagree the \EF commands differ (tree-sitter has no declaration face, solocal xand parameters are not \EFv; comment delimiters (\EFcd) are split off by the comment starter), and languages without a tree-sitter parser stay plain. A named theme is a Neovim colour scheme, loaded for the moment (Emacs loads the Emacs theme); its faces come from the highlight groups. export.smart_quotes_alistsets the quotes of the languages it lists and keeps the Emacs table for the others (Emacs replaces the whole alist).export.ascii.table_use_ascii_artdraws table.el tables with box characters; in Org 9.8.10 the option does nothing when ascii-art-to-unicode is installed (its package check is inverted) and fails when it is not.- LaTeX pictures in HTML (
tex:dvipng, ...) are named ltximg/FILE_HASH.png with a hash of their own; a failed conversion warns and leaves the LaTeX out instead of stopping the export. - table.el tables: the HTML comment table.el puts before the table names org.nvim instead of the Emacs version, and a grid table.el cannot read is exported as preformatted text (HTML) or
verbatim(LaTeX) where Emacs fails. - Asynchronous export (
a) runs in a separate Neovim, like Emacs; a visible-only export runs on the editor's event loop instead, and so does publishing. - PDF compilation and ODT conversion run in the background, on the export stack, also without
a(export.latex.async_compile,export.odt.async_convert; Emacs waits for them). The stack can cancel a running export (x,:Org export_stack_cancel; Emacs kills it with its process buffer), shows "signal" for a cancelled one, and names the back-end of a running export (Emacs leaves it empty until the result). A failed compilation's message also quotes the error lines of the LaTeX output. - Remote (TRAMP) files and directories.
- Generated labels (
orgXXXXXXX) and iCalendar UIDs are derived from the content instead of random, so repeated exports give the same output. - iCalendar lines are folded at 75 octets without splitting a UTF-8 character (RFC 5545); Emacs folds at 75 characters, so the two differ only on lines with non-ASCII text.
- The default creator string names Neovim and org.nvim instead of Emacs.
- LaTeX: a backslash in the text followed by another is escaped twice,
$\backslash$$\backslash$. Emacs escapes the first and copies the second as it is (\\ xbecomes$\backslash$\ x, and\\$a line break followed by a stray$), which can leave broken LaTeX. - Org: plain lists are repaired (renumbered, sub-lists aligned) with spaces. Emacs re-indents their lines with tabs from column 8 on when
indent-tabs-modeis on, its default.