Export

orgstar exports HTML, Markdown, PDF, Word, RTF, plain text and iCalendar itself, and hands LaTeX, ODT, ASCII and LaTeX-made PDF to Emacs on the Mac.

Exporting a file

Export works on the file in the current editor, using its text as it is now, saved or not. It applies to Org files only; in any other file the command says "Not an org file". Source blocks are never run during export. Results already in the file are exported as they are; see Code blocks.

On the Mac

The keys follow Emacs's export dispatcher (org-export-dispatch). C-c C-e on its own is only a prefix: pause after it and the key hints list the formats. The SPC m e keys work in normal state; the C-c C-e keys work in every Doom state. The Mac preset has no keys for the single formats; its ⇧⌘E opens the export dialog.

All fourteen commands are in File ▸ Export and in the command palette. They write the export beside the Org file, with the same name and the format's extension: .html, .md, .pdf, .docx, .rtf, .tex, .odt, .txt or .ics. The two agenda-file commands are the exceptions; see iCalendar export. #+EXPORT_FILE_NAME: names it instead, as in Org: relative to the Org file's folder (or absolute, or starting with ~), with its extension replaced by the format's, so #+EXPORT_FILE_NAME: out/report writes out/report.html. A file already there is replaced. The message area shows "Exported to name".

The export dialog

Export… in the command palette, or ⇧⌘E in the Mac preset, opens a dialog. The Emacs and Doom presets have no key for it; bind app.export-dialog in keymap.toml if you want one (see Keys and commands). The dialog has:

• Format: HTML, Markdown, PDF, Word, Rich Text (RTF), Plain text, PDF via LaTeX (Emacs), ODT (Emacs), LaTeX (Emacs), Plain text, ASCII (Emacs) or iCalendar.
• Scope: the whole file, or the subtree at the caret (Org's C-s in the dispatcher). A subtree is exported as a document of its own: its heading is the title, its text the body, and its child headings move up a level. iCalendar is the exception: there the subtree's heading is an entry like any other. The file's #+ keywords still apply, and the heading's EXPORT_TITLE, EXPORT_AUTHOR, EXPORT_DATE, EXPORT_EMAIL, EXPORT_OPTIONS, EXPORT_SELECT_TAGS, EXPORT_EXCLUDE_TAGS, EXPORT_HTML_HEAD and EXPORT_HTML_HEAD_EXTRA properties override them. Its planning line and property drawer are left out. The choice is available when the caret is under a heading.
• Body only: leave out the title and the page around the text (Org's C-b). HTML is then the table of contents, the text and the footnotes, without <html>, <head> or the title; Markdown has no title heading. Not available for PDF, Word, RTF, plain text, ODT and iCalendar.
• Destination: where #+EXPORT_FILE_NAME: says, or the subtree's EXPORT_FILE_NAME property for a subtree, else beside the Org file. Choose… picks another place and name. Changing the format changes the extension.
• Open after export: opens the file in its default app when the export finishes.

The dialog remembers the format and the Open after export setting.

On iOS

The Export menu offers HTML, Markdown, PDF, Word, Rich Text (RTF), Plain Text and iCalendar, and Copy as Rich Text. It is under More in the editor, and in the toolbar in the reader. Choosing one opens the share sheet with the exported file, named after the Org file or its #+EXPORT_FILE_NAME:. Send it to another app, or use Save to Files to keep it. The export is the same as on the Mac. LaTeX, ODT, ASCII and PDF through LaTeX are not available on iOS, nor are the agenda-file iCalendar exports.

HTML export

orgstar writes a complete HTML page: a small built-in stylesheet that follows the system's light or dark appearance, the title, an author and date line, the table of contents, then the document. It does not use Emacs, and its output is close to, but not the same as, ox-html.

Title, author and date

Keywords in files named by #+SETUPFILE: count, as they do in Org.

#+OPTIONS

A depth for toc or num larger than H is cut to H. Any value other than nil turns an option on. Other #+OPTIONS keys are ignored.

#+TITLE: Field notes
#+AUTHOR: Sam
#+OPTIONS: toc:2 num:nil pri:t ^:{}

Which headings are exported

• A heading tagged with one of #+EXCLUDE_TAGS (noexport by default) is left out, with everything under it.
• A heading whose title starts with COMMENT is left out.
• A heading tagged ARCHIVE is exported as the heading alone, without its contents.
• If any heading has one of #+SELECT_TAGS (export by default), only those headings, their ancestors and everything under them are exported.

Each heading gets an id for links: its CUSTOM_ID property, or a slug made from its title. Headings are one level down from Org's: a top-level heading is an <h2>, since the title is the <h1>.

The page head

Each #+HTML_HEAD: and #+HTML_HEAD_EXTRA: line goes into the page's <head> as written, in order. Use them for stylesheets and scripts:

#+HTML_HEAD: <link rel="stylesheet" href="notes.css">

The built-in stylesheet is always included first. Other #+HTML_… keywords are not used.

Math

LaTeX fragments (\(…\), \[…\], $…$, $$…$$) and LaTeX environments are left in the page for MathJax. When the page has any, orgstar adds MathJax 3 from cdn.jsdelivr.net, so the page needs a network connection to show math. Entities such as \alpha become their characters.

Includes

#+INCLUDE: inserts another file before export, as org-export-expand-include-keyword does. Paths are relative to the Org file.

A file that cannot be read is replaced by an empty line.

Macros

{{{name(arguments)}}} is replaced before export (org-macro-replace-all).

Arguments are separated by commas; write \, for a literal comma. Macros defined with (eval …), and macros orgstar does not know, become empty. #+MACRO: definitions in setup files count.

Footnotes

Footnote references, named or inline ([fn:: text]), become numbered superscript links. The notes are collected in a Footnotes section at the end, numbered in the order they are first referenced, each with a link back. A reference without a definition is exported as written.

Tables

An Org table becomes an HTML <table>. If it has rules, the rows before the first rule are the header (<thead>) and the rest the body. #+CAPTION: gives the table a caption. #+TBLFM: lines are not exported.

A table.el table (one drawn with +, - and |) becomes a table with each cell's colspan and rowspan, and the lines in a cell joined with line breaks. If its drawing is not a well-formed table, it is exported as preformatted text.

Images and links

A link to an image file without a description becomes an <img>. The image types are png, jpg, jpeg, gif, svg, webp, bmp, tif, tiff and avif. #+ATTR_HTML: before the paragraph adds attributes (:width 300 :alt "Map"); without an :alt, the file name is used.

An image paragraph with #+CAPTION: or #+ATTR_HTML: becomes a <figure>; a caption is numbered "Figure 1:", "Figure 2:" and so on.

Links to .org files point to the .html file of the same name. Links to headings ([[*Heading]]), to CUSTOM_ID targets and to radio targets point to the heading's or target's id on the page. id: links point to # and the ID. Other links are written as they are.

Source blocks and their results

A source block is exported as <pre><code class"language-LANG">=, with the code escaped and its common indentation removed. Code in a language the editor highlights is colored as the editor colors it: each token is a <span> with the class Emacs's htmlize gives its face (org-keyword, org-string, org-comment, org-function-name, org-type, org-constant, org-property-name, org-variable-name), and the page's stylesheet colors them with the theme's syntax- colors, light and dark. Other languages are exported plain; the language- class lets a script or stylesheet in #+HTML_HEAD highlight them. Noweb references are shown as written. Code references are covered in Links: labels come off the lines, -n and +n number them, and [[(name)]] links to the labelled line.

The block's :exports header argument decides what appears. orgstar resolves it as running the block would: from the #+begin_src line, #+HEADER: lines, header-args properties and #+PROPERTY: lines (see Code blocks). Without one, it is results for dot, plantuml, ditaa, gnuplot, latex and lilypond blocks, as their Org defaults set it, and code for other languages.

A #+CALL: line exports its existing results, never the call itself; :exports code or none on the call, or in the header-args properties where the call is, exports nothing. An inline src_ block has :exports results by default: the {{{results(…)}}} after it is exported and its code is not. With :exports code the code is exported in <code> and the results are not; with both, both. An inline call_ never appears itself, and the {{{results(…)}}} after it is always exported, whatever :exports says, as in Org.

Other blocks and elements

Comments, drawers, property drawers, planning lines, clock lines and keywords are not exported.

Citations

HTML and Markdown export handle citations the same way; see Citations below.

PDF export

Export to PDF makes the HTML export into a PDF, laid out and split into pages by the system's web engine as printing does. It needs neither Emacs nor TeX, and works on iOS. The PDF has what the HTML export has: the title, the byline, the table of contents, colored code, tables, images and math (MathJax, which needs a network connection). For the page:

• Colors are always the light ones, whatever the system's appearance.
• Pages are US Letter where that is the usual size and A4 elsewhere; on the Mac, the paper size set for printing.
• Code blocks, tables, figures and quotes are kept on one page when they fit, and a heading is not left at the bottom of a page.

For typeset output with LaTeX's classes and packages, use Export to PDF with Emacs instead (see Exporting through Emacs).

Word, RTF and plain text

Export to Word, Export to RTF and Export to Plain Text make the HTML export into a document of that kind, as the system reads HTML: headings, emphasis, links, colored keywords and code, lists, and tables. Word files (.docx) are written by orgstar itself, so tables come through as Word tables; RTF keeps them too on the Mac. On iOS, where the system's HTML reader keeps no tables, Word's tables are made from the HTML export's tables, with header cells bold and the cells' text without its styles; RTF and plain text there have the cells' text but no table. Plain text is the same text without its styles: list bullets and table cells are kept, separated by tabs. Fonts are Helvetica Neue for text and Menlo for code, and the colors are the light ones. Images are not included.

For Org's own ASCII layout, with underlined headings and drawn tables, use Export to Plain Text with Emacs.

Copying as rich text

Copy as Rich Text (the command palette on the Mac, the Export menu on iOS) puts the selection, or the whole file when nothing is selected, on the clipboard as HTML, RTF and plain text. Paste it into Mail, Pages, Word or a web form to get the formatted text. On iOS it copies the whole file.

Markdown export

Markdown export writes GitHub-flavored Markdown:

• #+TITLE: becomes a top # heading. Org headings are one level down: * is ##. TODO keywords stay in the heading text, and tags are shown as inline code. Priority cookies are left out unless #+OPTIONS has pri:t.
• Source blocks become fenced code blocks with the language; example blocks, =: = lines and table.el tables become fenced blocks without one.
• Tables become pipe tables. A rule after the first row makes it the header; otherwise the header row is empty.
• Checkboxes become task-list items (- [x], - [ ]).
• Footnotes become [^1] references with the notes at the end.
• Quotes become > blocks. Verse lines end with two spaces.
• Images become ![](path). Links to .org files, with or without file:, point to the .md file of the same name; a search option after :: is dropped.
• #+begin_export blocks for markdown, md or html, and @@html:…@@ snippets, are copied as they are.
• Underline, subscripts and superscripts are written as HTML tags.
• :exports is handled as in HTML export.
• Citations are handled as in HTML export.

As in HTML export, #+INCLUDE: lines are expanded and macros replaced first, and #+EXCLUDE_TAGS, #+SELECT_TAGS, COMMENT headings and ARCHIVE tags decide which headings are exported (see Which headings are exported). Of the #+OPTIONS, Markdown export reads todo, pri, tags, ^ and title; the others do not apply. It writes no author or date.

iCalendar export

iCalendar export writes the .ics file org-icalendar-export-to-ics writes, for calendar apps to read or subscribe to. Each heading can give:

• a VEVENT for its DEADLINE and one for its SCHEDULED date, as org-icalendar-use-deadline and org-icalendar-use-scheduled say. Their summaries start with =DL: = and =S: =;
• a VEVENT for each other timestamp in its title and text, active ones only unless #+OPTIONS has <:t or <:inactive;
• a VTODO for a task, as org-icalendar-include-todo says. Its DTSTART is the scheduled date (with todo-start in org-icalendar-use-scheduled), its DUE the deadline (with todo-due in org-icalendar-use-deadline); without a scheduled date, a deadline with a + repeater starts its warning period before it. STATUS is NEEDS-ACTION or COMPLETED, and PRIORITY maps A to 1, B to 5 and C to 9.

The summary is the heading's title, or its SUMMARY property. The description is the heading's text as Org's ASCII export writes it, filled to 70 columns, or its DESCRIPTION property; LOCATION, CLASS, TIMEZONE and APPT_WARNTIME (an alarm, minutes before a timed event) are read too. CATEGORIES lists the heading's tags and its category. An ID property is the UID; a heading without one gets a new random UID each time, as in Org with org-icalendar-store-UID nil. Repeaters become RRULE lines. Times are local times without a zone, as Org writes them by default; a TIMEZONE property of UTC writes them in UTC, and any other value names the zone (TZID).

#+ICALENDAR_EXCLUDE_TAGS: lists tags whose subtrees are left out; #+EXCLUDE_TAGS: doesn't apply, so noexport subtrees are exported unless listed. #+SELECT_TAGS, COMMENT headings and ARCHIVE tags apply as in the other exports. #+ICAL-TTL: sets X-PUBLISHED-TTL, the refresh period, such as PT1H. The calendar is named after the file, its description is #+TITLE:, and its owner #+AUTHOR: or your full name. Lines longer than 75 characters are folded and lines end in CRLF, as RFC 5545 asks.

Export Agenda Files to iCalendar writes an .ics beside each agenda file (see The agenda). Combine Agenda Files into iCalendar writes all their entries to one calendar named OrgMode at org-icalendar-combined-agenda-file. On iOS, the Export menu's iCalendar shares the current file's calendar.

Differences from Org: diary sexps (%%(…) lines and <%%(…)> timestamps) are left out, as they need Emacs's icalendar.el. The other org-icalendar-* variables keep Org's defaults: alarms only from APPT_WARNTIME, categories (local-tags category), the whole body as the description, and local times. Descriptions of tables with column groups or alignment cookies, center blocks and links to targets can differ from Org's in layout.

Publishing

Publishing (org-publish) exports a folder of Org files to a folder of HTML or Markdown files, copies other files beside them, and can write a sitemap. Projects are [[publish]] tables in config.toml, as org-publish-project-alist entries are in Emacs:

[[publish]]
name = "notes"
base-directory = "~/notes"
publishing-directory = "~/public_html"
recursive = true
auto-sitemap = true
sitemap-title = "Notes"

[[publish]]
name = "static"
base-directory = "~/notes"
base-extension = "css\\|png\\|jpg"
recursive = true
publishing-directory = "~/public_html"
publishing-function = "org-publish-attachment"

[[publish]]
name = "site"
components = "notes static"

Files whose names start with a dot are left out. An Org file publishes to the same path under publishing-directory, named by #+EXPORT_FILE_NAME when it has one, with links to other .org files pointing to their .html. The sitemap lists each file as a link with its #+TITLE (or its name), as Org's default sitemap does.

On the Mac, File ▸ Publish has the commands, which are also in the command palette:

A file whose published copy is newer than it is skipped, as Org skips files that haven't changed; delete the copy to publish it again. The message area says how many files were published and how many were up to date. Differences from Org: preparation and completion functions, :makeindex, custom sitemap functions and the export options a project can set (:with-toc, :html-head and the rest) aren't read; set those with #+OPTIONS and the other keywords in the files, or a #+SETUPFILE. Publishing is on the Mac only.

Exporting through Emacs

On the Mac, PDF, LaTeX, ODT and plain text exports are done by Emacs, with the ox functions Emacs's dispatcher uses:

orgstar runs emacs -Q --batch in the Org file's folder. It opens the file, replaces its contents with the editor's current text without saving, and calls the function. Emacs writes the result beside the file, as it would itself; with a destination chosen in the export dialog, orgstar then moves it there. The message area shows "Exporting with Emacs…" and then "Exported to name".

What you need:

• Emacs, at ORGSTAR_EMACS or one of /opt/homebrew/bin/emacs, /usr/local/bin/emacs, /Applications/Emacs.app/Contents/MacOS/Emacs, /run/current-system/sw/bin/emacs or /usr/bin/emacs. Without it the export fails with "Emacs isn't installed, so this format can't be exported."
• For PDF, a TeX installation that Emacs's LaTeX export can run. Emacs runs with your PATH plus /opt/homebrew/bin, /usr/local/bin, /Library/TeX/texbin, /usr/bin and /bin, the same as code blocks get, so latexmk and pdflatex from MacTeX or Homebrew are found when orgstar was opened from the Dock.

Things to know:

• -Q means Emacs does not load your init file. Your LaTeX classes, export settings and packages from it are not used; the export uses Org's defaults and what the file itself sets.
• File-local variables are applied only when Emacs considers them safe.
• org-export-use-babel is off, so no source blocks run.
• An export that takes more than two minutes is stopped with "Emacs took too long to export."
• Edit ▸ Cancel Running Task (⌘.) stops the export and shows "Export canceled". Starting another export or table recalculation in Emacs cancels the one that is running.
• If Emacs fails, the message area shows the last line of its error output.

To use your own Emacs configuration, or formats orgstar does not list, export from Emacs itself; see Alongside Emacs.

Citations

HTML and Markdown export process citations as Org's basic citation processor does (oc-basic).

#+bibliography: refs.bib
#+cite_export: basic author-year

As shown in [cite:@smith2020], and again [cite/t:@smith2020; see @lee2019 p. 4].

#+print_bibliography:

Bibliography files

Each #+bibliography: line names one file, relative to the Org file, optionally in quotes. A file ending in .json is read as CSL-JSON; anything else is read as BibTeX, with @string abbreviations expanded and @comment and @preamble skipped. You can have several #+bibliography: lines; for a key in more than one file, the first file wins.

#+cite_export:

#+cite_export: PROCESSOR [BIBLIOGRAPHY-STYLE [CITATION-STYLE]].

• With no #+cite_export:, or with basic, citations are processed.
• With any other processor, such as csl or biblatex, orgstar leaves citations as they are written.
• The citation style, which may include a variant (text/bare), is the default for citations that do not name one.

Citation styles

A citation is [cite:…] or [cite/style:…] or [cite/style/variant:…], holding one or more @key references separated by ;. Each reference may have its own prefix and suffix, and the whole citation a common prefix and suffix.

Works by the same author in the same year get a, b, … after the year. A key not found in any bibliography file shows as ?? and ????. Citations in the title are dropped.

For note citations, the blank before the citation is removed and punctuation right after it moves in front of the footnote mark, as org-cite-adjust-note does.

The bibliography

#+print_bibliography: is replaced by an entry for every cited work, sorted by author. The bibliography style from #+cite_export: sets the form:

The publisher part comes from the publisher, journal, institution or school field. Without #+print_bibliography: no bibliography is written.

What export does not do

• Subtree and body-only export are in the export dialog only; the single-format commands export the whole file. There is no asynchronous export.
• Source blocks are not run, and noweb references are not expanded.
• Export settings in the dialog are not per file.