krz/orgstar

A native macOS editor for org-mode files. editor org-mode swift

guide/12-export.html

pages
orgstar/guide/12-export.html history · blame · raw

344 lines · 35779 bytes

  1<!DOCTYPE html>
  2<html lang="en">
  3<head>
  4<meta charset="utf-8">
  5<meta name="viewport" content="width=device-width, initial-scale=1">
  6<title>Export &middot; Orgstar</title>
  7<meta name="description" content="Exporting Org files from Orgstar to HTML and Markdown, and to PDF, LaTeX, ODT and plain text through Emacs.">
  8<link rel="icon" href="../favicon.svg" type="image/svg+xml">
  9<link rel="stylesheet" href="../theme.css">
 10<link rel="stylesheet" href="../syntax.css">
 11<link rel="stylesheet" href="../style.css">
 12</head>
 13<body>
 14<header class="site">
 15<a class="site-title" href="../index.html">Orgstar</a>
 16<nav>
 17<a href="../install.html">Install</a>
 18<a href="../quickstart.html">Quick start</a>
 19<a href="index.html">Manual</a>
 20</nav>
 21</header>
 22<main>
 23<h1>Export</h1>
 24<p class="lede">Orgstar exports HTML and Markdown itself, and hands PDF, LaTeX, ODT and plain text to Emacs on the Mac.</p>
 25<nav class="toc" aria-label="On this page">
 26<h2>On this page</h2>
 27<ul>
 28<li><a href="#exporting-a-file">Exporting a file</a>
 29<ul>
 30<li><a href="#on-the-mac">On the Mac</a></li>
 31<li><a href="#the-export-dialog">The export dialog</a></li>
 32<li><a href="#on-ios">On iOS</a></li>
 33</ul></li>
 34<li><a href="#html-export">HTML export</a>
 35<ul>
 36<li><a href="#title-author-and-date">Title, author and date</a></li>
 37<li><a href="#options">#+OPTIONS</a></li>
 38<li><a href="#which-headings-are-exported">Which headings are exported</a></li>
 39<li><a href="#the-page-head">The page head</a></li>
 40<li><a href="#math">Math</a></li>
 41<li><a href="#includes">Includes</a></li>
 42<li><a href="#macros">Macros</a></li>
 43<li><a href="#footnotes">Footnotes</a></li>
 44<li><a href="#tables">Tables</a></li>
 45<li><a href="#images-and-links">Images and links</a></li>
 46<li><a href="#source-blocks-and-their-results">Source blocks and their results</a></li>
 47<li><a href="#other-blocks-and-elements">Other blocks and elements</a></li>
 48<li><a href="#citations">Citations</a></li>
 49</ul></li>
 50<li><a href="#markdown-export">Markdown export</a></li>
 51<li><a href="#exporting-through-emacs">Exporting through Emacs</a></li>
 52<li><a href="#citations">Citations</a>
 53<ul>
 54<li><a href="#bibliography-files">Bibliography files</a></li>
 55<li><a href="#cite-export">#+cite_export:</a></li>
 56<li><a href="#citation-styles">Citation styles</a></li>
 57<li><a href="#the-bibliography">The bibliography</a></li>
 58</ul></li>
 59<li><a href="#what-export-does-not-do">What export does not do</a></li>
 60</ul>
 61</nav>
 62<h2 id="exporting-a-file">Exporting a file</h2>
 63<p>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 <a href="11-code-blocks.html">Code blocks</a>.</p>
 64<h3 id="on-the-mac">On the Mac</h3>
 65<table>
 66<thead>
 67<tr><th>Format</th><th>Command</th><th>Emacs preset</th><th>Doom</th><th>Needs Emacs</th></tr>
 68</thead>
 69<tbody>
 70<tr><td>HTML</td><td>Export to HTML</td><td><code class="verbatim">C-c C-e h h</code></td><td><code class="verbatim">SPC m e h h</code>, <code class="verbatim">C-c C-e h h</code></td><td>no</td></tr>
 71<tr><td>HTML, then open it</td><td>Export to HTML and Open</td><td><code class="verbatim">C-c C-e h o</code></td><td><code class="verbatim">SPC m e h o</code>, <code class="verbatim">C-c C-e h o</code></td><td>no</td></tr>
 72<tr><td>Markdown</td><td>Export to Markdown</td><td><code class="verbatim">C-c C-e m m</code></td><td><code class="verbatim">SPC m e m m</code>, <code class="verbatim">C-c C-e m m</code></td><td>no</td></tr>
 73<tr><td>PDF</td><td>Export to PDF with Emacs</td><td><code class="verbatim">C-c C-e l p</code></td><td><code class="verbatim">SPC m e l p</code>, <code class="verbatim">C-c C-e l p</code></td><td>yes</td></tr>
 74<tr><td>LaTeX</td><td>Export to LaTeX with Emacs</td><td><code class="verbatim">C-c C-e l l</code></td><td><code class="verbatim">C-c C-e l l</code></td><td>yes</td></tr>
 75<tr><td>ODT</td><td>Export to ODT with Emacs</td><td><code class="verbatim">C-c C-e o o</code></td><td><code class="verbatim">C-c C-e o o</code></td><td>yes</td></tr>
 76<tr><td>Plain text</td><td>Export to Plain Text with Emacs</td><td><code class="verbatim">C-c C-e t u</code></td><td><code class="verbatim">C-c C-e t u</code></td><td>yes</td></tr>
 77</tbody>
 78</table>
 79<p>The keys follow Emacs's export dispatcher (<code class="verbatim">org-export-dispatch</code>). <code class="verbatim">C-c C-e</code> on its own is only a prefix: pause after it and the key hints list the formats. The <code class="verbatim">SPC m e</code> keys work in normal state; the <code class="verbatim">C-c C-e</code> keys work in every Doom state. The Mac preset has no keys for the single formats; its <code class="verbatim">⇧⌘E</code> opens the export dialog.</p>
 80<p>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: <code class="verbatim">.html</code>, <code class="verbatim">.md</code>, <code class="verbatim">.pdf</code>, <code class="verbatim">.tex</code>, <code class="verbatim">.odt</code> or <code class="verbatim">.txt</code>. A file already there is replaced. The message area shows "Exported to <em>name</em>".</p>
 81<h3 id="the-export-dialog">The export dialog</h3>
 82<p><strong>Export…</strong> in the command palette, or <code class="verbatim">⇧⌘E</code> in the Mac preset, opens a dialog. The Emacs and Doom presets have no key for it; bind <code class="verbatim">app.export-dialog</code> in <code class="verbatim">keymap.toml</code> if you want one (see <a href="03-keys.html">Keys and commands</a>). The dialog has:</p>
 83<ul>
 84<li><strong>Format</strong>: HTML, Markdown, PDF (Emacs), ODT (Emacs), LaTeX (Emacs) or Plain text (Emacs).</li>
 85<li><strong>Destination</strong>: beside the Org file by default. <strong>Choose…</strong> picks another place and name. Changing the format changes the extension.</li>
 86<li><strong>Open after export</strong>: opens the file in its default app when the export finishes.</li>
 87</ul>
 88<p>The dialog remembers the format and the <strong>Open after export</strong> setting.</p>
 89<h3 id="on-ios">On iOS</h3>
 90<p>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.</p>
 91<h2 id="html-export">HTML export</h2>
 92<p>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, <code class="verbatim">ox-html</code>.</p>
 93<h3 id="title-author-and-date">Title, author and date</h3>
 94<table>
 95<thead>
 96<tr><th>Keyword</th><th>Effect</th></tr>
 97</thead>
 98<tbody>
 99<tr><td><code class="verbatim">#+TITLE:</code></td><td>The page title and a top heading. Without one, the file's name is used.</td></tr>
100<tr><td><code class="verbatim">#+AUTHOR:</code></td><td>Shown under the title.</td></tr>
101<tr><td><code class="verbatim">#+DATE:</code></td><td>Shown under the title, after the author, as written.</td></tr>
102</tbody>
103</table>
104<p>Keywords in files named by <code class="verbatim">#+SETUPFILE:</code> count, as they do in Org.</p>
105<h3 id="options"><code class="verbatim">#+OPTIONS</code></h3>
106<table>
107<thead>
108<tr><th>Option</th><th>Values</th><th>Default</th><th>Effect</th></tr>
109</thead>
110<tbody>
111<tr><td><code class="verbatim">toc</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code>, a number</td><td><code class="verbatim">t</code></td><td>Table of contents, to the given depth. <code class="verbatim">t</code> goes to <code class="verbatim">H</code>.</td></tr>
112<tr><td><code class="verbatim">num</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code>, a number</td><td><code class="verbatim">t</code></td><td>Section numbers, to the given depth. <code class="verbatim">t</code> goes to <code class="verbatim">H</code>.</td></tr>
113<tr><td><code class="verbatim">H</code></td><td>a number</td><td><code class="verbatim">3</code></td><td>The deepest heading level the table of contents and numbering count.</td></tr>
114<tr><td><code class="verbatim">tags</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code>, <code class="verbatim">not-in-toc</code></td><td><code class="verbatim">t</code></td><td>Heading tags; <code class="verbatim">not-in-toc</code> leaves them out of the table of contents.</td></tr>
115<tr><td><code class="verbatim">todo</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code></td><td><code class="verbatim">t</code></td><td>TODO keywords in headings.</td></tr>
116<tr><td><code class="verbatim">pri</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code></td><td><code class="verbatim">nil</code></td><td>Priority cookies in headings.</td></tr>
117<tr><td><code class="verbatim">tex</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code></td><td><code class="verbatim">t</code></td><td>LaTeX fragments and environments; <code class="verbatim">nil</code> drops them.</td></tr>
118<tr><td><code class="verbatim">title</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code></td><td><code class="verbatim">t</code></td><td>The title heading.</td></tr>
119<tr><td><code class="verbatim">author</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code></td><td><code class="verbatim">t</code></td><td>The author.</td></tr>
120<tr><td><code class="verbatim">date</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code></td><td><code class="verbatim">t</code></td><td>The date.</td></tr>
121</tbody>
122</table>
123<p>A depth for <code class="verbatim">toc</code> or <code class="verbatim">num</code> larger than <code class="verbatim">H</code> is cut to <code class="verbatim">H</code>. Any value other than <code class="verbatim">nil</code> turns an option on. Other <code class="verbatim">#+OPTIONS</code> keys are ignored.</p>
124<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+TITLE:</span><span class="string unquoted org"> Field notes</span>
125<span class="keyword other keyword org">#+AUTHOR:</span><span class="string unquoted org"> Sam</span>
126<span class="keyword other keyword org">#+OPTIONS:</span><span class="string unquoted org"> toc:2 num:nil pri:t ^:{}</span></span></code></pre>
127<h3 id="which-headings-are-exported">Which headings are exported</h3>
128<ul>
129<li>A heading tagged with one of <code class="verbatim">#+EXCLUDE_TAGS</code> (<code class="verbatim">noexport</code> by default) is left out, with everything under it.</li>
130<li>A heading whose title starts with <code class="verbatim">COMMENT</code> is left out.</li>
131<li>A heading tagged <code class="verbatim">ARCHIVE</code> is exported as the heading alone, without its contents.</li>
132<li>If any heading has one of <code class="verbatim">#+SELECT_TAGS</code> (<code class="verbatim">export</code> by default), only those headings, their ancestors and everything under them are exported.</li>
133</ul>
134<p>Each heading gets an <code class="verbatim">id</code> for links: its <code class="verbatim">CUSTOM_ID</code> property, or a slug made from its title. Headings are one level down from Org's: a top-level heading is an <code class="verbatim">&lt;h2&gt;</code>, since the title is the <code class="verbatim">&lt;h1&gt;</code>.</p>
135<h3 id="the-page-head">The page head</h3>
136<p>Each <code class="verbatim">#+HTML_HEAD:</code> and <code class="verbatim">#+HTML_HEAD_EXTRA:</code> line goes into the page's <code class="verbatim">&lt;head&gt;</code> as written, in order. Use them for stylesheets and scripts:</p>
137<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+HTML_HEAD:</span><span class="string unquoted org"> &lt;link rel=&quot;stylesheet&quot; href=&quot;notes.css&quot;&gt;</span></span></code></pre>
138<p>The built-in stylesheet is always included first. Other <code class="verbatim">#+HTML_…</code> keywords are not used.</p>
139<h3 id="math">Math</h3>
140<p>LaTeX fragments (<code class="verbatim">\(…\)</code>, <code class="verbatim">\[…\]</code>, <code class="verbatim">$…$</code>, <code class="verbatim">$$…$$</code>) and LaTeX environments are left in the page for MathJax. When the page has any, Orgstar adds MathJax 3 from <code class="verbatim">cdn.jsdelivr.net</code>, so the page needs a network connection to show math. Entities such as <code class="verbatim">\alpha</code> become their characters.</p>
141<h3 id="includes">Includes</h3>
142<p><code class="verbatim">#+INCLUDE:</code> inserts another file before export, as <code class="verbatim">org-export-expand-include-keyword</code> does. Paths are relative to the Org file.</p>
143<table>
144<thead>
145<tr><th>Form</th><th>Effect</th></tr>
146</thead>
147<tbody>
148<tr><td><code class="verbatim">#+INCLUDE: "part.org"</code></td><td>The file's contents, read as Org; its includes are expanded too, up to eight levels.</td></tr>
149<tr><td><code class="verbatim">#+INCLUDE: "part.org::*Heading"</code></td><td>Only the subtree with that heading.</td></tr>
150<tr><td><code class="verbatim">#+INCLUDE: "part.org::#custom-id"</code></td><td>Only the subtree with that <code class="verbatim">CUSTOM_ID</code>.</td></tr>
151<tr><td><code class="verbatim">#+INCLUDE: "code.sh" src sh</code></td><td>The file in a source block.</td></tr>
152<tr><td><code class="verbatim">#+INCLUDE: "log.txt" example</code></td><td>The file in an example block.</td></tr>
153<tr><td><code class="verbatim">#+INCLUDE: "page.html" export html</code></td><td>The file in an export block.</td></tr>
154<tr><td><code class="verbatim">quote</code>, <code class="verbatim">verse</code>, <code class="verbatim">center</code>, <code class="verbatim">comment</code></td><td>The file in a block of that kind.</td></tr>
155<tr><td><code class="verbatim">:lines "5-10"</code></td><td>Only those lines; either end may be left out.</td></tr>
156<tr><td><code class="verbatim">:minlevel 2</code></td><td>Shift the included headings so the shallowest is at that level.</td></tr>
157</tbody>
158</table>
159<p>A file that cannot be read is replaced by an empty line.</p>
160<h3 id="macros">Macros</h3>
161<p><code class="verbatim">{{{name(arguments)}}}</code> is replaced before export (<code class="verbatim">org-macro-replace-all</code>).</p>
162<table>
163<thead>
164<tr><th>Macro</th><th>Replaced by</th></tr>
165</thead>
166<tbody>
167<tr><td><code class="verbatim">#+MACRO: name text</code></td><td><code class="verbatim">text</code>, with <code class="verbatim">$1</code>, =$2=… replaced by the arguments.</td></tr>
168<tr><td><code class="verbatim">{{{title}}}</code>, <code class="verbatim">{{{author}}}</code>, <code class="verbatim">{{{date}}}</code>, <code class="verbatim">{{{email}}}</code></td><td>That keyword's value.</td></tr>
169<tr><td><code class="verbatim">{{{keyword(NAME)}}}</code></td><td>The value of <code class="verbatim">#+NAME:</code>.</td></tr>
170<tr><td><code class="verbatim">{{{input-file}}}</code></td><td>The Org file's name.</td></tr>
171<tr><td><code class="verbatim">{{{property(NAME)}}}</code></td><td>The value of property <code class="verbatim">NAME</code> of the entry the macro is in; <code class="verbatim">ITEM</code> gives the heading's title. Empty before the first heading.</td></tr>
172<tr><td><code class="verbatim">{{{property(NAME,SEARCH)}}}</code></td><td>The same for the entry <code class="verbatim">SEARCH</code> finds in this file: <code class="verbatim">*Title</code>, <code class="verbatim">#custom-id</code> or a title.</td></tr>
173<tr><td><code class="verbatim">{{{n}}}</code>, <code class="verbatim">{{{n(name)}}}</code></td><td>A counter, increased at each use. <code class="verbatim">n(name,-)</code> repeats the current value; <code class="verbatim">n(name,5)</code> sets it to 5.</td></tr>
174<tr><td><code class="verbatim">{{{time(format)}}}</code></td><td>The current time, formatted as <code class="verbatim">format-time-string</code> does.</td></tr>
175</tbody>
176</table>
177<p>Arguments are separated by commas; write <code class="verbatim">\,</code> for a literal comma. Macros defined with <code class="verbatim">(eval …)</code>, and macros Orgstar does not know, become empty. <code class="verbatim">#+MACRO:</code> definitions in setup files count.</p>
178<h3 id="footnotes">Footnotes</h3>
179<p>Footnote references, named or inline (<code class="verbatim">[fn:: text]</code>), 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.</p>
180<h3 id="tables">Tables</h3>
181<p>An Org table becomes an HTML <code class="verbatim">&lt;table&gt;</code>. If it has rules, the rows before the first rule are the header (<code class="verbatim">&lt;thead&gt;</code>) and the rest the body. <code class="verbatim">#+CAPTION:</code> gives the table a caption. <code class="verbatim">#+TBLFM:</code> lines are not exported.</p>
182<p>A table.el table (one drawn with <code class="verbatim">+</code>, <code class="verbatim">-</code> and <code class="verbatim">|</code>) becomes a table with each cell's <code class="verbatim">colspan</code> and <code class="verbatim">rowspan</code>, 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.</p>
183<h3 id="images-and-links">Images and links</h3>
184<p>A link to an image file without a description becomes an <code class="verbatim">&lt;img&gt;</code>. The image types are <code class="verbatim">png</code>, <code class="verbatim">jpg</code>, <code class="verbatim">jpeg</code>, <code class="verbatim">gif</code>, <code class="verbatim">svg</code>, <code class="verbatim">webp</code>, <code class="verbatim">bmp</code>, <code class="verbatim">tif</code>, <code class="verbatim">tiff</code> and <code class="verbatim">avif</code>. <code class="verbatim">#+ATTR_HTML:</code> before the paragraph adds attributes (<code class="verbatim">:width 300 :alt "Map"</code>); without an <code class="verbatim">:alt</code>, the file name is used.</p>
185<p>An image paragraph with <code class="verbatim">#+CAPTION:</code> or <code class="verbatim">#+ATTR_HTML:</code> becomes a <code class="verbatim">&lt;figure&gt;</code>; a caption is numbered "Figure 1:", "Figure 2:" and so on.</p>
186<p>Links to <code class="verbatim">.org</code> files point to the <code class="verbatim">.html</code> file of the same name. Links to headings (<code class="verbatim">[[*Heading]]</code>), to <code class="verbatim">CUSTOM_ID</code> targets and to radio targets point to the heading's or target's <code class="verbatim">id</code> on the page. <code class="verbatim">id:</code> links point to <code class="verbatim">#</code> and the ID. Other links are written as they are.</p>
187<h3 id="source-blocks-and-their-results">Source blocks and their results</h3>
188<p>A source block is exported as <code class="verbatim">&lt;pre&gt;&lt;code class</code>"language-LANG"&gt;=, with the code escaped and its common indentation removed. Orgstar does not color the code; the class lets a script or stylesheet in <code class="verbatim">#+HTML_HEAD</code> highlight it. Noweb references are shown as written. Line-number switches are ignored.</p>
189<p>The block's <code class="verbatim">:exports</code> header argument decides what appears. Orgstar resolves it as running the block would: from the <code class="verbatim">#+begin_src</code> line, <code class="verbatim">#+HEADER:</code> lines, <code class="verbatim">header-args</code> properties and <code class="verbatim">#+PROPERTY:</code> lines (see <a href="11-code-blocks.html">Code blocks</a>). Without one, it is <code class="verbatim">results</code> for <code class="verbatim">dot</code>, <code class="verbatim">plantuml</code>, <code class="verbatim">ditaa</code>, <code class="verbatim">gnuplot</code>, <code class="verbatim">latex</code> and <code class="verbatim">lilypond</code> blocks, as their Org defaults set it, and <code class="verbatim">code</code> for other languages.</p>
190<table>
191<thead>
192<tr><th><code class="verbatim">:exports</code></th><th>Exported</th></tr>
193</thead>
194<tbody>
195<tr><td><code class="verbatim">code</code></td><td>The code.</td></tr>
196<tr><td><code class="verbatim">results</code></td><td>The block's existing <code class="verbatim">#+RESULTS:</code>.</td></tr>
197<tr><td><code class="verbatim">both</code></td><td>The code, then the results.</td></tr>
198<tr><td><code class="verbatim">none</code></td><td>Nothing.</td></tr>
199</tbody>
200</table>
201<p>A <code class="verbatim">#+CALL:</code> line exports its existing results, never the call itself; <code class="verbatim">:exports code</code> or <code class="verbatim">none</code> on the call, or in the <code class="verbatim">header-args</code> properties where the call is, exports nothing. An inline <code class="verbatim">src_</code> block has <code class="verbatim">:exports results</code> by default: the <code class="verbatim">{{{results(…)}}}</code> after it is exported and its code is not. With <code class="verbatim">:exports code</code> the code is exported in <code class="verbatim">&lt;code&gt;</code> and the results are not; with <code class="verbatim">both</code>, both. An inline <code class="verbatim">call_</code> never appears itself, and the <code class="verbatim">{{{results(…)}}}</code> after it is always exported, whatever <code class="verbatim">:exports</code> says, as in Org.</p>
202<h3 id="other-blocks-and-elements">Other blocks and elements</h3>
203<table>
204<thead>
205<tr><th>Org</th><th>HTML</th></tr>
206</thead>
207<tbody>
208<tr><td><code class="verbatim">#+begin_example</code></td><td><code class="verbatim">&lt;pre&gt;</code></td></tr>
209<tr><td>=: = lines</td><td><code class="verbatim">&lt;pre class</code>"example"&gt;=</td></tr>
210<tr><td><code class="verbatim">#+begin_quote</code></td><td><code class="verbatim">&lt;blockquote&gt;</code></td></tr>
211<tr><td><code class="verbatim">#+begin_center</code></td><td><code class="verbatim">&lt;div class</code>"center"&gt;=</td></tr>
212<tr><td><code class="verbatim">#+begin_verse</code></td><td><code class="verbatim">&lt;p class</code>"verse"&gt;=, lines and indentation kept</td></tr>
213<tr><td><code class="verbatim">#+begin_export html</code></td><td>Its contents, as they are</td></tr>
214<tr><td><code class="verbatim">#+begin_export</code> other formats</td><td>Nothing</td></tr>
215<tr><td><code class="verbatim">#+begin_comment</code></td><td>Nothing</td></tr>
216<tr><td><code class="verbatim">#+begin_NAME</code>, any other name</td><td><code class="verbatim">&lt;div class</code>"NAME"&gt;= (a special block)</td></tr>
217<tr><td><code class="verbatim">@@html:…@@</code></td><td>Its contents, as they are; other back-ends' snippets are dropped</td></tr>
218<tr><td>Plain, numbered and description lists</td><td><code class="verbatim">&lt;ul&gt;</code>, <code class="verbatim">&lt;ol&gt;</code>, <code class="verbatim">&lt;dl&gt;</code>; checkboxes as <code class="verbatim">[X]</code>, <code class="verbatim">[-]</code>, <code class="verbatim">[ ]</code></td></tr>
219<tr><td>Timestamps</td><td><code class="verbatim">&lt;time datetime</code>"…"&gt;=</td></tr>
220<tr><td>Inline tasks</td><td><code class="verbatim">&lt;div class</code>"inlinetask"&gt;= with the title in bold</td></tr>
221<tr><td>Dynamic blocks</td><td>Their contents</td></tr>
222<tr><td><code class="verbatim">-----</code></td><td><code class="verbatim">&lt;hr&gt;</code></td></tr>
223</tbody>
224</table>
225<p>Comments, drawers, property drawers, planning lines, clock lines and keywords are not exported.</p>
226<h3 id="citations">Citations</h3>
227<p>HTML and Markdown export handle citations the same way; see Citations below.</p>
228<h2 id="markdown-export">Markdown export</h2>
229<p>Markdown export writes GitHub-flavored Markdown:</p>
230<ul>
231<li><code class="verbatim">#+TITLE:</code> becomes a top <code class="verbatim">#</code> heading. Org headings are one level down: <code class="verbatim">*</code> is <code class="verbatim">##</code>. TODO keywords stay in the heading text, and tags are shown as inline code. Priority cookies are left out unless <code class="verbatim">#+OPTIONS</code> has <code class="verbatim">pri:t</code>.</li>
232<li>Source blocks become fenced code blocks with the language; example blocks, =: = lines and table.el tables become fenced blocks without one.</li>
233<li>Tables become pipe tables. A rule after the first row makes it the header; otherwise the header row is empty.</li>
234<li>Checkboxes become task-list items (<code class="verbatim">- [x]</code>, <code class="verbatim">- [ ]</code>).</li>
235<li>Footnotes become <code class="verbatim">[^1]</code> references with the notes at the end.</li>
236<li>Quotes become <code class="verbatim">&gt;</code> blocks. Verse lines end with two spaces.</li>
237<li>Images become <code class="verbatim">![](path)</code>. Links to <code class="verbatim">.org</code> files, with or without <code class="verbatim">file:</code>, point to the <code class="verbatim">.md</code> file of the same name; a search option after <code class="verbatim">::</code> is dropped.</li>
238<li><code class="verbatim">#+begin_export</code> blocks for <code class="verbatim">markdown</code>, <code class="verbatim">md</code> or <code class="verbatim">html</code>, and <code class="verbatim">@@html:…@@</code> snippets, are copied as they are.</li>
239<li>Underline, subscripts and superscripts are written as HTML tags.</li>
240<li><code class="verbatim">:exports</code> is handled as in HTML export.</li>
241<li>Citations are handled as in HTML export.</li>
242</ul>
243<p>As in HTML export, <code class="verbatim">#+INCLUDE:</code> lines are expanded and macros replaced first, and <code class="verbatim">#+EXCLUDE_TAGS</code>, <code class="verbatim">#+SELECT_TAGS</code>, <code class="verbatim">COMMENT</code> headings and <code class="verbatim">ARCHIVE</code> tags decide which headings are exported (see <em>Which headings are exported</em>). Of the <code class="verbatim">#+OPTIONS</code>, Markdown export reads <code class="verbatim">todo</code>, <code class="verbatim">pri</code>, <code class="verbatim">tags</code>, <code class="verbatim">^</code> and <code class="verbatim">title</code>; the others do not apply. It writes no author or date.</p>
244<h2 id="exporting-through-emacs">Exporting through Emacs</h2>
245<p>On the Mac, PDF, LaTeX, ODT and plain text exports are done by Emacs, with the <code class="verbatim">ox</code> functions Emacs's dispatcher uses:</p>
246<table>
247<thead>
248<tr><th>Format</th><th>Function</th></tr>
249</thead>
250<tbody>
251<tr><td>PDF</td><td><code class="verbatim">org-latex-export-to-pdf</code></td></tr>
252<tr><td>LaTeX</td><td><code class="verbatim">org-latex-export-to-latex</code></td></tr>
253<tr><td>ODT</td><td><code class="verbatim">org-odt-export-to-odt</code></td></tr>
254<tr><td>Plain text</td><td><code class="verbatim">org-ascii-export-to-ascii</code></td></tr>
255</tbody>
256</table>
257<p>Orgstar runs <code class="verbatim">emacs -Q --batch</code> 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 <em>name</em>".</p>
258<p>What you need:</p>
259<ul>
260<li>Emacs, at <code class="verbatim">ORGSTAR_EMACS</code> or one of <code class="verbatim">/opt/homebrew/bin/emacs</code>, <code class="verbatim">/usr/local/bin/emacs</code>, <code class="verbatim">/Applications/Emacs.app/Contents/MacOS/Emacs</code>, <code class="verbatim">/run/current-system/sw/bin/emacs</code> or <code class="verbatim">/usr/bin/emacs</code>. Without it the export fails with "Emacs isn't installed, so this format can't be exported."</li>
261<li>For PDF, a TeX installation that Emacs's LaTeX export can run. Emacs runs with your <code class="verbatim">PATH</code> plus <code class="verbatim">/opt/homebrew/bin</code>, <code class="verbatim">/usr/local/bin</code>, <code class="verbatim">/Library/TeX/texbin</code>, <code class="verbatim">/usr/bin</code> and <code class="verbatim">/bin</code>, the same as code blocks get, so <code class="verbatim">latexmk</code> and <code class="verbatim">pdflatex</code> from MacTeX or Homebrew are found when Orgstar was opened from the Dock.</li>
262</ul>
263<p>Things to know:</p>
264<ul>
265<li><code class="verbatim">-Q</code> 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.</li>
266<li>File-local variables are applied only when Emacs considers them safe.</li>
267<li><code class="verbatim">org-export-use-babel</code> is off, so no source blocks run.</li>
268<li>An export that takes more than two minutes is stopped with "Emacs took too long to export."</li>
269<li>Edit ▸ Cancel Running Task (<code class="verbatim">⌘.</code>) stops the export and shows "Export canceled". Starting another export or table recalculation in Emacs cancels the one that is running.</li>
270<li>If Emacs fails, the message area shows the last line of its error output.</li>
271</ul>
272<p>To use your own Emacs configuration, or formats Orgstar does not list, export from Emacs itself; see <a href="15-alongside-emacs.html">Alongside Emacs</a>.</p>
273<h2 id="citations">Citations</h2>
274<p>HTML and Markdown export process citations as Org's <code class="verbatim">basic</code> citation processor does (<code class="verbatim">oc-basic</code>).</p>
275<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+bibliography:</span><span class="string unquoted org"> refs.bib</span>
276<span class="keyword other keyword org">#+cite_export:</span><span class="string unquoted org"> basic author-year</span>
277
278As shown in [cite:@smith2020], and again [cite/t:@smith2020; see @lee2019 p. 4].
279
280<span class="keyword other keyword org">#+print_bibliography:</span></span></code></pre>
281<h3 id="bibliography-files">Bibliography files</h3>
282<p>Each <code class="verbatim">#+bibliography:</code> line names one file, relative to the Org file, optionally in quotes. A file ending in <code class="verbatim">.json</code> is read as CSL-JSON; anything else is read as BibTeX, with <code class="verbatim">@string</code> abbreviations expanded and <code class="verbatim">@comment</code> and <code class="verbatim">@preamble</code> skipped. You can have several <code class="verbatim">#+bibliography:</code> lines; for a key in more than one file, the first file wins.</p>
283<h3 id="cite-export"><code class="verbatim">#+cite_export:</code></h3>
284<p><code class="verbatim">#+cite_export: PROCESSOR [BIBLIOGRAPHY-STYLE [CITATION-STYLE]]</code>.</p>
285<ul>
286<li>With no <code class="verbatim">#+cite_export:</code>, or with <code class="verbatim">basic</code>, citations are processed.</li>
287<li>With any other processor, such as <code class="verbatim">csl</code> or <code class="verbatim">biblatex</code>, Orgstar leaves citations as they are written.</li>
288<li>The citation style, which may include a variant (<code class="verbatim">text/bare</code>), is the default for citations that do not name one.</li>
289</ul>
290<h3 id="citation-styles">Citation styles</h3>
291<p>A citation is <code class="verbatim">[cite:…]</code> or <code class="verbatim">[cite/style:…]</code> or <code class="verbatim">[cite/style/variant:…]</code>, holding one or more <code class="verbatim">@key</code> references separated by <code class="verbatim">;</code>. Each reference may have its own prefix and suffix, and the whole citation a common prefix and suffix.</p>
292<table>
293<thead>
294<tr><th>Style</th><th>Output</th></tr>
295</thead>
296<tbody>
297<tr><td>default (none given)</td><td><code class="verbatim">(Author, Year)</code></td></tr>
298<tr><td><code class="verbatim">author</code>, <code class="verbatim">a</code></td><td><code class="verbatim">Author</code></td></tr>
299<tr><td><code class="verbatim">noauthor</code>, <code class="verbatim">na</code></td><td><code class="verbatim">(Year)</code></td></tr>
300<tr><td><code class="verbatim">text</code>, <code class="verbatim">t</code></td><td><code class="verbatim">Author (Year)</code></td></tr>
301<tr><td><code class="verbatim">note</code>, <code class="verbatim">ft</code></td><td>A footnote holding the <code class="verbatim">text</code> form</td></tr>
302<tr><td><code class="verbatim">numeric</code>, <code class="verbatim">nb</code></td><td><code class="verbatim">(1)</code>, numbered by the cited works sorted by author; three or more in a row as <code class="verbatim">1-3</code></td></tr>
303<tr><td><code class="verbatim">nocite</code>, <code class="verbatim">n</code></td><td>Nothing; the work is still listed in the bibliography</td></tr>
304</tbody>
305</table>
306<table>
307<thead>
308<tr><th>Variant</th><th>Effect</th></tr>
309</thead>
310<tbody>
311<tr><td><code class="verbatim">bare</code>, <code class="verbatim">b</code></td><td>No parentheses</td></tr>
312<tr><td><code class="verbatim">caps</code>, <code class="verbatim">c</code></td><td>Capitalized author</td></tr>
313<tr><td><code class="verbatim">bare-caps</code>, <code class="verbatim">bc</code></td><td>Both</td></tr>
314</tbody>
315</table>
316<p>Works by the same author in the same year get <code class="verbatim">a</code>, <code class="verbatim">b</code>, … after the year. A key not found in any bibliography file shows as <code class="verbatim">??</code> and <code class="verbatim">????</code>. Citations in the title are dropped.</p>
317<p>For <code class="verbatim">note</code> citations, the blank before the citation is removed and punctuation right after it moves in front of the footnote mark, as <code class="verbatim">org-cite-adjust-note</code> does.</p>
318<h3 id="the-bibliography">The bibliography</h3>
319<p><code class="verbatim">#+print_bibliography:</code> is replaced by an entry for every cited work, sorted by author. The bibliography style from <code class="verbatim">#+cite_export:</code> sets the form:</p>
320<table>
321<thead>
322<tr><th>Bibliography style</th><th>Entry</th></tr>
323</thead>
324<tbody>
325<tr><td>default</td><td><code class="verbatim">Author (Year). /Title/, Publisher.</code></td></tr>
326<tr><td><code class="verbatim">plain</code></td><td><code class="verbatim">Surnames. Title, Publisher, Year.</code></td></tr>
327<tr><td><code class="verbatim">numeric</code></td><td><code class="verbatim">[1] Author, /Title/, Publisher, Year.</code></td></tr>
328</tbody>
329</table>
330<p>The publisher part comes from the <code class="verbatim">publisher</code>, <code class="verbatim">journal</code>, <code class="verbatim">institution</code> or <code class="verbatim">school</code> field. Without <code class="verbatim">#+print_bibliography:</code> no bibliography is written.</p>
331<h2 id="what-export-does-not-do">What export does not do</h2>
332<ul>
333<li>There is no subtree export, body-only export, or asynchronous export; each command exports the whole file.</li>
334<li><code class="verbatim">#+EXPORT_FILE_NAME:</code> is not used by HTML and Markdown export.</li>
335<li>Source blocks are not run, and noweb references are not expanded.</li>
336<li>HTML export does not color source code.</li>
337<li>Export settings in the dialog are not per file.</li>
338</ul>
339</main>
340<footer class="site">
341Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>.
342</footer>
343</body>
344</html>