Export

Orgstar exports HTML and Markdown itself, and hands PDF, LaTeX, ODT and plain text 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

Format	Command	Emacs preset	Doom	Needs Emacs
HTML	Export to HTML	`C-c C-e h h`	`SPC m e h h`, `C-c C-e h h`	no
HTML, then open it	Export to HTML and Open	`C-c C-e h o`	`SPC m e h o`, `C-c C-e h o`	no
Markdown	Export to Markdown	`C-c C-e m m`	`SPC m e m m`, `C-c C-e m m`	no
PDF	Export to PDF with Emacs	`C-c C-e l p`	`SPC m e l p`, `C-c C-e l p`	yes
LaTeX	Export to LaTeX with Emacs	`C-c C-e l l`	`C-c C-e l l`	yes
ODT	Export to ODT with Emacs	`C-c C-e o o`	`C-c C-e o o`	yes
Plain text	Export to Plain Text with Emacs	`C-c C-e t u`	`C-c C-e t u`	yes

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 seven 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, .tex, .odt or .txt. 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 (Emacs), ODT (Emacs), LaTeX (Emacs) or Plain text (Emacs).
Destination: beside the Org file by default. 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 and Markdown. 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. Send it to another app, or use Save to Files to keep it. The export is the same as on the Mac. PDF, LaTeX, ODT and plain text are not available on iOS.

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

Keyword	Effect
`#+TITLE:`	The page title and a top heading. Without one, the file's name is used.
`#+AUTHOR:`	Shown under the title.
`#+DATE:`	Shown under the title, after the author, as written.

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

`#+OPTIONS`

Option	Values	Default	Effect
`toc`	`t`, `nil`, a number	`t`	Table of contents, to the given depth. `t` goes to `H`.
`num`	`t`, `nil`, a number	`t`	Section numbers, to the given depth. `t` goes to `H`.
`H`	a number	`3`	The deepest heading level the table of contents and numbering count.
`tags`	`t`, `nil`, `not-in-toc`	`t`	Heading tags; `not-in-toc` leaves them out of the table of contents.
`todo`	`t`, `nil`	`t`	TODO keywords in headings.
`pri`	`t`, `nil`	`nil`	Priority cookies in headings.
`tex`	`t`, `nil`	`t`	LaTeX fragments and environments; `nil` drops them.
`title`	`t`, `nil`	`t`	The title heading.
`author`	`t`, `nil`	`t`	The author.
`date`	`t`, `nil`	`t`	The date.

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.

Form	Effect
`#+INCLUDE: "part.org"`	The file's contents, read as Org; its includes are expanded too, up to eight levels.
`#+INCLUDE: "part.org::*Heading"`	Only the subtree with that heading.
`#+INCLUDE: "part.org::#custom-id"`	Only the subtree with that `CUSTOM_ID`.
`#+INCLUDE: "code.sh" src sh`	The file in a source block.
`#+INCLUDE: "log.txt" example`	The file in an example block.
`#+INCLUDE: "page.html" export html`	The file in an export block.
`quote`, `verse`, `center`, `comment`	The file in a block of that kind.
`:lines "5-10"`	Only those lines; either end may be left out.
`:minlevel 2`	Shift the included headings so the shallowest is at that level.

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

Macros

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

Macro	Replaced by
`#+MACRO: name text`	`text`, with `$1`, =$2=… replaced by the arguments.
`{{{title}}}`, `{{{author}}}`, `{{{date}}}`, `{{{email}}}`	That keyword's value.
`{{{keyword(NAME)}}}`	The value of `#+NAME:`.
`{{{input-file}}}`	The Org file's name.
`{{{property(NAME)}}}`	The value of property `NAME` of the entry the macro is in; `ITEM` gives the heading's title. Empty before the first heading.
`{{{property(NAME,SEARCH)}}}`	The same for the entry `SEARCH` finds in this file: `*Title`, `#custom-id` or a title.
`{{{n}}}`, `{{{n(name)}}}`	A counter, increased at each use. `n(name,-)` repeats the current value; `n(name,5)` sets it to 5.
`{{{time(format)}}}`	The current time, formatted as `format-time-string` does.

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. Orgstar does not color the code; the class lets a script or stylesheet in #+HTML_HEAD highlight it. Noweb references are shown as written. Line-number switches are ignored.

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.

`:exports`	Exported
`code`	The code.
`results`	The block's existing `#+RESULTS:`.
`both`	The code, then the results.
`none`	Nothing.

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

Org	HTML
`#+begin_example`	`<pre>`
=: = lines	`<pre class`"example">=
`#+begin_quote`	`<blockquote>`
`#+begin_center`	`<div class`"center">=
`#+begin_verse`	`<p class`"verse">=, lines and indentation kept
`#+begin_export html`	Its contents, as they are
`#+begin_export` other formats	Nothing
`#+begin_comment`	Nothing
`#+begin_NAME`, any other name	`<div class`"NAME">= (a special block)
`@@html:…@@`	Its contents, as they are; other back-ends' snippets are dropped
Plain, numbered and description lists	`<ul>`, `<ol>`, `<dl>`; checkboxes as `[X]`, `[-]`, `[ ]`
Timestamps	`<time datetime`"…">=
Inline tasks	`<div class`"inlinetask">= with the title in bold
Dynamic blocks	Their contents
`-----`	`<hr>`

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.

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.

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:

Format	Function
PDF	`org-latex-export-to-pdf`
LaTeX	`org-latex-export-to-latex`
ODT	`org-odt-export-to-odt`
Plain text	`org-ascii-export-to-ascii`

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.

Style	Output
default (none given)	`(Author, Year)`
`author`, `a`	`Author`
`noauthor`, `na`	`(Year)`
`text`, `t`	`Author (Year)`
`note`, `ft`	A footnote holding the `text` form
`numeric`, `nb`	`(1)`, numbered by the cited works sorted by author; three or more in a row as `1-3`
`nocite`, `n`	Nothing; the work is still listed in the bibliography

Variant	Effect
`bare`, `b`	No parentheses
`caps`, `c`	Capitalized author
`bare-caps`, `bc`	Both

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:

Bibliography style	Entry
default	`Author (Year). /Title/, Publisher.`
`plain`	`Surnames. Title, Publisher, Year.`
`numeric`	`[1] Author, /Title/, Publisher, Year.`

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

What export does not do

There is no subtree export, body-only export, or asynchronous export; each command exports the whole file.
#+EXPORT_FILE_NAME: is not used by HTML and Markdown export.
Source blocks are not run, and noweb references are not expanded.
HTML export does not color source code.
Export settings in the dialog are not per file.