docs/manual/guide/12-export.org
308 lines · 23113 bytes
1#+TITLE: Export
2#+DESCRIPTION: Exporting Org files from Orgstar to HTML and Markdown, and to PDF, LaTeX, ODT and plain text through Emacs.
3#+LEDE: Orgstar exports HTML and Markdown itself, and hands PDF, LaTeX, ODT and plain text to Emacs on the Mac.
4
5* Exporting a file
6
7Export 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 [[file:11-code-blocks.org][Code blocks]].
8
9** On the Mac
10
11| Format | Command | Emacs preset | Doom | Needs Emacs |
12|--------------------+----------------------------------+---------------+-------------------------------+-------------|
13| HTML | Export to HTML | =C-c C-e h h= | =SPC m e h h=, =C-c C-e h h= | no |
14| 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 |
15| Markdown | Export to Markdown | =C-c C-e m m= | =SPC m e m m=, =C-c C-e m m= | no |
16| PDF | Export to PDF with Emacs | =C-c C-e l p= | =SPC m e l p=, =C-c C-e l p= | yes |
17| LaTeX | Export to LaTeX with Emacs | =C-c C-e l l= | =C-c C-e l l= | yes |
18| ODT | Export to ODT with Emacs | =C-c C-e o o= | =C-c C-e o o= | yes |
19| Plain text | Export to Plain Text with Emacs | =C-c C-e t u= | =C-c C-e t u= | yes |
20
21The 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.
22
23All 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/".
24
25** The export dialog
26
27*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 [[file:03-keys.org][Keys and commands]]). The dialog has:
28
29- *Format*: HTML, Markdown, PDF (Emacs), ODT (Emacs), LaTeX (Emacs) or Plain text (Emacs).
30- *Destination*: beside the Org file by default. *Choose…* picks another place and name. Changing the format changes the extension.
31- *Open after export*: opens the file in its default app when the export finishes.
32
33The dialog remembers the format and the *Open after export* setting.
34
35** On iOS
36
37The 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.
38
39* HTML export
40
41Orgstar 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=.
42
43** Title, author and date
44
45| Keyword | Effect |
46|------------+--------------------------------------------------------------------------|
47| =#+TITLE:= | The page title and a top heading. Without one, the file's name is used. |
48| =#+AUTHOR:=| Shown under the title. |
49| =#+DATE:= | Shown under the title, after the author, as written. |
50
51Keywords in files named by =#+SETUPFILE:= count, as they do in Org.
52
53** =#+OPTIONS=
54
55| Option | Values | Default | Effect |
56|---------+---------------------------------------+---------+------------------------------------------------------------------------|
57| =toc= | =t=, =nil=, a number | =t= | Table of contents, to the given depth. =t= goes to =H=. |
58| =num= | =t=, =nil=, a number | =t= | Section numbers, to the given depth. =t= goes to =H=. |
59| =H= | a number | =3= | The deepest heading level the table of contents and numbering count. |
60| =tags= | =t=, =nil=, =not-in-toc= | =t= | Heading tags; =not-in-toc= leaves them out of the table of contents. |
61| =todo= | =t=, =nil= | =t= | TODO keywords in headings. |
62| =pri= | =t=, =nil= | =nil= | Priority cookies in headings. |
63| =^= | =t=, =nil=, ={}= | =t= | =_= and =^= as subscripts and superscripts; ={}= only when braced, as in =x_{1}=. |
64| =tex= | =t=, =nil= | =t= | LaTeX fragments and environments; =nil= drops them. |
65| =title= | =t=, =nil= | =t= | The title heading. |
66| =author=| =t=, =nil= | =t= | The author. |
67| =date= | =t=, =nil= | =t= | The date. |
68
69A 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.
70
71#+BEGIN_SRC org
72,#+TITLE: Field notes
73,#+AUTHOR: Sam
74,#+OPTIONS: toc:2 num:nil pri:t ^:{}
75#+END_SRC
76
77** Which headings are exported
78
79- A heading tagged with one of =#+EXCLUDE_TAGS= (=noexport= by default) is left out, with everything under it.
80- A heading whose title starts with =COMMENT= is left out.
81- A heading tagged =ARCHIVE= is exported as the heading alone, without its contents.
82- If any heading has one of =#+SELECT_TAGS= (=export= by default), only those headings, their ancestors and everything under them are exported.
83
84Each 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>=.
85
86** The page head
87
88Each =#+HTML_HEAD:= and =#+HTML_HEAD_EXTRA:= line goes into the page's =<head>= as written, in order. Use them for stylesheets and scripts:
89
90#+BEGIN_SRC org
91,#+HTML_HEAD: <link rel="stylesheet" href="notes.css">
92#+END_SRC
93
94The built-in stylesheet is always included first. Other =#+HTML_…= keywords are not used.
95
96** Math
97
98LaTeX 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.
99
100** Includes
101
102=#+INCLUDE:= inserts another file before export, as =org-export-expand-include-keyword= does. Paths are relative to the Org file.
103
104| Form | Effect |
105|-----------------------------------------------+-----------------------------------------------------------|
106| =#+INCLUDE: "part.org"= | The file's contents, read as Org; its includes are expanded too, up to eight levels. |
107| =#+INCLUDE: "part.org::*Heading"= | Only the subtree with that heading. |
108| =#+INCLUDE: "part.org::#custom-id"= | Only the subtree with that =CUSTOM_ID=. |
109| =#+INCLUDE: "code.sh" src sh= | The file in a source block. |
110| =#+INCLUDE: "log.txt" example= | The file in an example block. |
111| =#+INCLUDE: "page.html" export html= | The file in an export block. |
112| =quote=, =verse=, =center=, =comment= | The file in a block of that kind. |
113| =:lines "5-10"= | Only those lines; either end may be left out. |
114| =:minlevel 2= | Shift the included headings so the shallowest is at that level. |
115
116A file that cannot be read is replaced by an empty line.
117
118** Macros
119
120={{{name(arguments)}}}= is replaced before export (=org-macro-replace-all=).
121
122| Macro | Replaced by |
123|------------------------------+----------------------------------------------------------------------|
124| =#+MACRO: name text= | =text=, with =$1=, =$2=… replaced by the arguments. |
125| ={{{title}}}=, ={{{author}}}=, ={{{date}}}=, ={{{email}}}= | That keyword's value. |
126| ={{{keyword(NAME)}}}= | The value of =#+NAME:=. |
127| ={{{input-file}}}= | The Org file's name. |
128| ={{{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. |
129| ={{{property(NAME,SEARCH)}}}= | The same for the entry =SEARCH= finds in this file: =*Title=, =#custom-id= or a title. |
130| ={{{n}}}=, ={{{n(name)}}}= | A counter, increased at each use. =n(name,-)= repeats the current value; =n(name,5)= sets it to 5. |
131| ={{{time(format)}}}= | The current time, formatted as =format-time-string= does. |
132
133Arguments 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.
134
135** Footnotes
136
137Footnote 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.
138
139** Tables
140
141An 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.
142
143A 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.
144
145** Images and links
146
147A 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.
148
149An image paragraph with =#+CAPTION:= or =#+ATTR_HTML:= becomes a =<figure>=; a caption is numbered "Figure 1:", "Figure 2:" and so on.
150
151Links 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.
152
153** Source blocks and their results
154
155A 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.
156
157The 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 [[file:11-code-blocks.org][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.
158
159| =:exports= | Exported |
160|------------------+-------------------------------------------|
161| =code= | The code. |
162| =results= | The block's existing =#+RESULTS:=. |
163| =both= | The code, then the results. |
164| =none= | Nothing. |
165
166A =#+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.
167
168** Other blocks and elements
169
170| Org | HTML |
171|----------------------------------+-------------------------------------------------|
172| =#+begin_example= | =<pre>= |
173| =: = lines | =<pre class="example">= |
174| =#+begin_quote= | =<blockquote>= |
175| =#+begin_center= | =<div class="center">= |
176| =#+begin_verse= | =<p class="verse">=, lines and indentation kept |
177| =#+begin_export html= | Its contents, as they are |
178| =#+begin_export= other formats | Nothing |
179| =#+begin_comment= | Nothing |
180| =#+begin_NAME=, any other name | =<div class="NAME">= (a special block) |
181| =@@html:…@@= | Its contents, as they are; other back-ends' snippets are dropped |
182| Plain, numbered and description lists | =<ul>=, =<ol>=, =<dl>=; checkboxes as =[X]=, =[-]=, =[ ]= |
183| Timestamps | =<time datetime="…">= |
184| Inline tasks | =<div class="inlinetask">= with the title in bold |
185| Dynamic blocks | Their contents |
186| =-----= | =<hr>= |
187
188Comments, drawers, property drawers, planning lines, clock lines and keywords are not exported.
189
190** Citations
191
192HTML and Markdown export handle citations the same way; see Citations below.
193
194* Markdown export
195
196Markdown export writes GitHub-flavored Markdown:
197
198- =#+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=.
199- Source blocks become fenced code blocks with the language; example blocks, =: = lines and table.el tables become fenced blocks without one.
200- Tables become pipe tables. A rule after the first row makes it the header; otherwise the header row is empty.
201- Checkboxes become task-list items (=- [x]=, =- [ ]=).
202- Footnotes become =[^1]= references with the notes at the end.
203- Quotes become =>= blocks. Verse lines end with two spaces.
204- Images become ==. Links to =.org= files, with or without =file:=, point to the =.md= file of the same name; a search option after =::= is dropped.
205- =#+begin_export= blocks for =markdown=, =md= or =html=, and =@@html:…@@= snippets, are copied as they are.
206- Underline, subscripts and superscripts are written as HTML tags.
207- =:exports= is handled as in HTML export.
208- Citations are handled as in HTML export.
209
210As 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.
211
212* Exporting through Emacs
213
214On the Mac, PDF, LaTeX, ODT and plain text exports are done by Emacs, with the =ox= functions Emacs's dispatcher uses:
215
216| Format | Function |
217|------------+-----------------------------|
218| PDF | =org-latex-export-to-pdf= |
219| LaTeX | =org-latex-export-to-latex= |
220| ODT | =org-odt-export-to-odt= |
221| Plain text | =org-ascii-export-to-ascii= |
222
223Orgstar 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/".
224
225What you need:
226
227- 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."
228- 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.
229
230Things to know:
231
232- =-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.
233- File-local variables are applied only when Emacs considers them safe.
234- =org-export-use-babel= is off, so no source blocks run.
235- An export that takes more than two minutes is stopped with "Emacs took too long to export."
236- 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.
237- If Emacs fails, the message area shows the last line of its error output.
238
239To use your own Emacs configuration, or formats Orgstar does not list, export from Emacs itself; see [[file:15-alongside-emacs.org][Alongside Emacs]].
240
241* Citations
242
243HTML and Markdown export process citations as Org's =basic= citation processor does (=oc-basic=).
244
245#+BEGIN_SRC org
246,#+bibliography: refs.bib
247,#+cite_export: basic author-year
248
249As shown in [cite:@smith2020], and again [cite/t:@smith2020; see @lee2019 p. 4].
250
251,#+print_bibliography:
252#+END_SRC
253
254** Bibliography files
255
256Each =#+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.
257
258** =#+cite_export:=
259
260=#+cite_export: PROCESSOR [BIBLIOGRAPHY-STYLE [CITATION-STYLE]]=.
261
262- With no =#+cite_export:=, or with =basic=, citations are processed.
263- With any other processor, such as =csl= or =biblatex=, Orgstar leaves citations as they are written.
264- The citation style, which may include a variant (=text/bare=), is the default for citations that do not name one.
265
266** Citation styles
267
268A 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.
269
270| Style | Output |
271|-------------------------------+-------------------------------------------------------------------------|
272| default (none given) | =(Author, Year)= |
273| =author=, =a= | =Author= |
274| =noauthor=, =na= | =(Year)= |
275| =text=, =t= | =Author (Year)= |
276| =note=, =ft= | A footnote holding the =text= form |
277| =numeric=, =nb= | =(1)=, numbered by the cited works sorted by author; three or more in a row as =1-3= |
278| =nocite=, =n= | Nothing; the work is still listed in the bibliography |
279
280| Variant | Effect |
281|----------------------+--------------------------------------------|
282| =bare=, =b= | No parentheses |
283| =caps=, =c= | Capitalized author |
284| =bare-caps=, =bc= | Both |
285
286Works 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.
287
288For =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.
289
290** The bibliography
291
292=#+print_bibliography:= is replaced by an entry for every cited work, sorted by author. The bibliography style from =#+cite_export:= sets the form:
293
294| Bibliography style | Entry |
295|------------------------+----------------------------------------------------------|
296| default | =Author (Year). /Title/, Publisher.= |
297| =plain= | =Surnames. Title, Publisher, Year.= |
298| =numeric= | =[1] Author, /Title/, Publisher, Year.= |
299
300The publisher part comes from the =publisher=, =journal=, =institution= or =school= field. Without =#+print_bibliography:= no bibliography is written.
301
302* What export does not do
303
304- There is no subtree export, body-only export, or asynchronous export; each command exports the whole file.
305- =#+EXPORT_FILE_NAME:= is not used by HTML and Markdown export.
306- Source blocks are not run, and noweb references are not expanded.
307- HTML export does not color source code.
308- Export settings in the dialog are not per file.