✅ HTML Exports

• [h h] HTML file - Export to .html file

• [h o] HTML and open - Export to .html and open in browser

• [h p] HTML preview - Preview HTML in VS Code webview

✅ LaTeX/PDF Exports

• [l l] LaTeX file - Export to .tex file

• [l p] PDF file - Export to PDF via LaTeX compilation

• [l o] PDF and open - Export to PDF and open with system viewer

These three can be routed to a custom exporter based on the document's #+LATEX_CLASS, so a memo or report class exports correctly without running a separate command. See Custom Exporters by LaTeX Class.

Beamer Exports

• [s b] Beamer (LaTeX) - Export to Beamer .tex file

• [s p] Beamer PDF - Compile Beamer to PDF

• [s o] Beamer PDF and open - Compile and open with system viewer

See Beamer Export for the keyword/property reference.

✅ Markdown Exports

• [m m] Markdown file - Export to .md file

• [m o] Markdown and open - Export to .md and open in VS Code

✅ Jupyter Notebook Exports

• [j j] Jupyter Notebook - Export to .ipynb file

• [j o] Notebook and open - Export and open in VS Code notebook viewer

• [j p] Participant notebook - Export with solutions stripped (for teaching)

✅ DOCX (Word) Exports

• [d d] Word document - Export to .docx file

• [d o] Word and open - Export and open in Microsoft Word

✅ Clipboard Exports (ox-clip style)

Copy formatted content to clipboard for pasting into other applications:

• [k h] HTML (rich) - Copy as formatted rich text (paste into Word, email, etc.)

• [k H] HTML (source) - Copy HTML source code

• [k l] LaTeX - Copy LaTeX source code

• [k m] Markdown - Copy Markdown source code

Quick keybinding: C-c k copies current subtree as rich HTML.

✅ Features

• Semantic HTML5 structure (<section>, <header>, <nav>)

• Syntax highlighting via highlight.js

• MathJax support for mathematical equations

• Responsive design with mobile-friendly layout

• Table of contents generation

• Footnote support

• Custom CSS and JavaScript support

✅ MathJax Integration

HTML exports automatically include MathJax for rendering mathematical content:

LaTeX environments also work directly.

Inline math: \(\int_0^1 x dx\)

Display math:

\[\int0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}\]

✅ Example

This document demonstrates HTML export with math: \(E = mc^2\)

Export with `C-c C-e h h' to produce a standalone HTML file.

✅ Document Classes

The default document class is article. You can specify alternatives:

#+LATEX_CLASS: report
#+LATEX_CLASS_OPTIONS: [11pt,a4paper,twoside]

Supported classes: article, report, book, beamer (for presentations)

⚠️ Custom Exporters by LaTeX Class

Document classes that need a template (letters, memos, theses) are handled by custom exporters. Map the class to an exporter id once, and the standard LaTeX/PDF exports use it automatically:

{
  "scimax.export.latexClassExporters": {
    "cmu-memo": "cmu-memo"
  }
}

Then a file that begins with

,#+LATEX_CLASS: cmu-memo
,#+TO: Selection Committee
,#+FROM: John Kitchin
,#+SUBJECT: Recommendation

exports through the cmu-memo template on C-c C-e l o - no special command to remember. Class names match case-insensitively, and the mapped exporter id does not have to match the class name.

Per-document control:

Routing applies to l l (writes the rendered .tex), l p (compiles the PDF) and l o (compiles and opens it), plus scimax export --format latex|pdf on the command line. Body-only exports are never routed. If the mapped exporter is not installed you get a warning and the built-in export runs instead.

✅ Custom Preambles

Add custom LaTeX packages and settings in the preamble:

#+LATEX_HEADER: \usepackage{geometry}
#+LATEX_HEADER: \geometry{margin=1in}
#+LATEX_HEADER: \usepackage{tcolorbox}

✅ Global Custom Header

Configure a complete custom LaTeX preamble in VS Code settings:

1. Open Settings (`C-,')

2. Search for `scimax.export.latex.customHeader'

3. Enter your complete preamble (from \documentclass through packages)

Example:

\documentclass[11pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb}
\usepackage{graphicx}
\usepackage[colorlinks=true]{hyperref}

Code Listings

LaTeX export supports two code highlighting backends:

#+BEGIN_SRC python
def fibonacci(n):
    return n if n < 2 else fibonacci(n-1) + fibonacci(n-2)

\begin{lstlisting}[language=Python]
def fibonacci(n):
    return n if n < 2 else fibonacci(n-1) + fibonacci(n-2)
\end{lstlisting}

#+LATEX_COMPILER: pdflatex -shell-escape

Tables with booktabs

Tables are exported using the booktabs package for professional appearance:

#+CAPTION: Experimental Results
#+NAME: tab:results
| Method | Accuracy | Time (s) |
|--------+----------+----------|
| A      |     0.95 |     12.3 |
| B      |     0.97 |     15.6 |

Exports to:

\begin{table}[htbp]
\centering
\begin{tabular}{lrr}
\toprule
Method & Accuracy & Time (s) \\
\midrule
A & 0.95 & 12.3 \\
B & 0.97 & 15.6 \\
\bottomrule
\end{tabular}
\caption{Experimental Results}
\label{tab:results}
\end{table}

Wide tables fit the margins automatically

Plain tabular columns (l, c, r) do not wrap or shrink, so a table with long cell content would otherwise run past the right page margin. By default the LaTeX exporter wraps each plain table in an adjustbox with max width\textwidth=, which scales over-wide tables down to fit the text width while leaving narrower tables at their natural size:

\begin{adjustbox}{max width=\textwidth}
\begin{tabular}{lll}
...
\end{tabular}
\end{adjustbox}

This adds \usepackage{adjustbox} to the preamble. Tables that set their own width via #+ATTR_LATEX: :environment tabularx :width \textwidth (or longtable) are left alone, since they already control their width. The behavior is controlled by the fitTablesToTextWidth export option (default true); set it to false to emit a bare tabular. If a scaled table's text becomes too small, prefer a tabularx table with wrapping X columns, which keeps the font size and wraps long cells instead.

⚠️ Long inline code wraps at separators

Inline verbatim (=code=), Emacs command markup (`command'), and inline source (src_python{...}) export to \texttt{}, which does not hyphenate. A long dotted identifier such as =difflow.flowsheet.Flowsheet.solve()= would otherwise be one unbreakable box that overflows the right margin (an Overfull \hbox). The exporter inserts \allowbreak after identifier separators (. / : - _) so these wrap naturally across lines. Word-internal characters are not broken, so a single very long token with no separators can still overrun; add a natural separator or use a display source block for such cases.

⚠️ Literal dollar signs in prose

A $ in text starts inline LaTeX math mode on PDF/LaTeX export. A single stray $, or a pair around currency ($50,000 ... $273,000), is silently typeset as math, dropping the $ signs and running the words together in italics.

Important: the usual escape \$ does *not* work in this org→LaTeX pipeline. Org turns the leading backslash into \textbackslash{}, so \$50,000 exports as \textbackslash{}\$50,000 (a visible stray backslash), and in Emacs org it can even fail to compile with ! Missing $ inserted.

Forms that do work:

• Reword to drop the sign: 50,000 USD or USD 50,000.

• Inline verbatim: =$50,000= exports as \texttt{\$50,000} (monospace, but correct).

• Raw LaTeX snippet for the sign only: @@latex:\$@@50,000 emits a literal \$ just in the LaTeX backend.

The literal-dollar lint flags likely offenders: comma-grouped currency amounts ($50,000) and any line with an odd number of unescaped $ (which opens math mode). Dollar signs inside verbatim/code spans and source blocks are ignored.

Cross-References

Use #+NAME: for labeled elements and link to them:

#+NAME: fig:diagram
[[file:diagram.png]]

See Figure [[fig:diagram]] for the system architecture.

✅ Compilation Process

The system uses latexmk for smart incremental builds:

1. Org → LaTeX conversion

2. `latexmk' compilation (handles multiple passes automatically)

3. Bibliography processing if needed

4. PDF generation

✅ Supported Compilers

Configure the LaTeX compiler in VS Code settings (scimax.latexLivePreview.compiler):

• `pdflatex' (default) - Standard LaTeX compiler

• `xelatex' - For Unicode and system fonts

• `lualatex' - For advanced features and LuaTeX

✅ Requirements

PDF export requires:

• LaTeX distribution (TeX Live, MiKTeX, or MacTeX)

• `latexmk' utility (included with most distributions)

⚠️ Build Profiles

A single compiler setting cannot express every build. One paper needs pdflatex + bibtex, the next needs lualatex + biber, a third needs an extra makeglossaries pass. A build profile is a named sequence of commands that replaces the built-in compile logic for a document.

Profiles come from four places, lowest precedence first:

Project files are found by walking up from the document's directory to the workspace root, checking .scimax/latex-profiles.json then latex-profiles.json at each level. A nearer definition wins, so a profile in a manuscript folder overrides the same name defined at the repository root.

,#+LATEX_BUILD: lualatex-biber

% !SCIMAX build = lualatex-biber

{
  "default": "pdflatex-bibtex",
  "profiles": {
    "thesis": {
      "description": "lualatex with biber and a glossary",
      "steps": [
        { "command": "lualatex", "args": ["-interaction=nonstopmode", "%f"] },
        { "command": "biber", "args": ["%b"], "whenFileExists": "%b.bcf" },
        { "command": "makeglossaries", "args": ["%b"], "whenFileExists": "%b.glo" },
        { "command": "lualatex", "args": ["-interaction=nonstopmode", "%f"] },
        { "command": "lualatex", "args": ["-interaction=nonstopmode", "%f"] }
      ]
    }
  }
}

{ "command": "bibtex", "args": ["%b"],
  "whenFileMatches": { "file": "%b.aux", "pattern": "\\\\citation", "regex": true } }

👀 SVG Images

LaTeX engines (pdflatex/lualatex/xelatex) cannot embed .svg files directly, so a figure like [[file:diagram.svg]] would otherwise abort the build with "Unknown graphics extension: .svg".

Scimax handles this automatically: during PDF export each referenced SVG is converted to PDF next to the original (diagram.svg → diagram.svg.pdf) and the \includegraphics path is rewritten to the converted file. No -shell-escape is required. The first available converter is used, tried in this order:

1. rsvg-convert (from librsvg -- fastest, recommended)

2. cairosvg (a Python package)

3. inkscape (version 1.x)

Install at least one to get SVG support (e.g. brew install librsvg for rsvg-convert). If none is installed, or a specific SVG cannot be converted, the export prints a warning naming the file and continues; the .svg include is left untouched (so LaTeX will still error on that figure). The generated diagram.svg.pdf is a derived build artifact and is safe to delete.

HTML export renders SVG natively and needs no conversion.

👀 Error Handling

If PDF compilation fails:

1. The extension offers to open the `.log' file

2. Review the log for LaTeX errors

3. Common issues:

   • Missing packages → Install via your TeX distribution

   • Syntax errors → Check LaTeX syntax in export

   • Image paths → Ensure images exist and paths are correct

⚠️ The generated .tex is disposable

The org file is the source of truth; the report.tex produced during PDF export is a disposable build artifact. Every scimax export --format pdf run regenerates report.tex from report.org, overwriting any manual edits to the .tex. (The converted *.svg.pdf files from SVG figures are disposable in the same way.)

Practical consequences:

• Do not hand-edit report.tex expecting the change to survive. Fix the problem in the .org source and re-export. With in-pipeline SVG→PDF conversion (see SVG Images above) and clear failure reporting (see Error Handling above), the two common reasons to reach for a .tex patch are already handled inside the export.

• Some LaTeX setups also define a latexmk custom dependency that rebuilds .tex from .org; where that exists, running latexmk on the .tex regenerates it too, so a .tex-level patch is doubly futile.

• If you truly need a one-off from an edited .tex (e.g. to test a fix for an export bug), compile it directly with the LaTeX engine and do *not* re-run scimax export (which would regenerate it): #+BEGIN_SRC bash lualatex -interaction=nonstopmode report.tex bibtex report lualatex -interaction=nonstopmode report.tex lualatex -interaction=nonstopmode report.tex #+END_SRC

Build on Save

Enable automatic PDF building in settings:

{
  "scimax.latexLivePreview.buildOnSave": true,
  "scimax.latexLivePreview.compiler": "pdflatex"
}

✅ PDF Viewer Panel with Bidirectional Sync

For an Overleaf-like editing experience, use the built-in PDF viewer panel:

Command: scimax.org.viewPdfPanel - "Scimax Org: View PDF in Panel (with sync)"

This exports your org file to PDF and opens it in a VS Code panel with full bidirectional synchronization support.

✅ Features

• Headings (`# ## ###')

• Emphasis (*bold*, _italic_, `~strikethrough~')

• Lists (ordered and unordered)

• Code blocks with syntax highlighting

• Tables (GFM format)

• Links and images

• Blockquotes

✅ Example Conversion

Org input:

,* Project Overview
This is a *bold* statement and an /italic/ one.

,** Features
- Fast rendering
- Simple syntax
- Wide support

,#+BEGIN_SRC python
print("Hello, world!")
,#+END_SRC

Markdown output:

# Project Overview
This is **bold** statement and an *italic* one.

## Features
- Fast rendering
- Simple syntax
- Wide support

```python
print("Hello, world!")
```

Features

• Full nbformat v4 notebook structure

• Automatic kernel detection from document content

• Source blocks become code cells (when language matches kernel)

• Headlines, paragraphs, lists, tables become markdown cells

• Participant mode for teaching materials (strips solutions)

• ox-ipynb compatibility (keywords, slideshow metadata)

• Base64 image embedding for self-contained notebooks

Basic Usage

Export the current org file to Jupyter Notebook:

Kernel Detection

The kernel is determined in this order:

1. #+OX_IPYNB_KERNEL_NAME: keyword in the document

2. Most common source block language in the document

3. Default: python3

,#+OX_IPYNB_KERNEL_NAME: julia-1.9
,#+TITLE: Julia Tutorial

Content here will use the Julia kernel.

Cell Conversion

Participant Mode (for Teaching)

Create student versions of notebooks with solutions stripped:

,#+BEGIN_SRC python
# Setup code (kept)
x = 1

### BEGIN SOLUTION
# This solution is removed in participant mode
y = x + 1
### END SOLUTION

# More code (kept)
,#+END_SRC

Content between ### BEGIN SOLUTION / ### END SOLUTION markers is removed. Also supports ### BEGIN HIDDEN / ### END HIDDEN markers.

Headlines with the :remove: tag are also excluded in participant mode.

Settings

Configure notebook export behavior in VS Code settings:

ox-ipynb Compatibility

The following ox-ipynb keywords are supported:

,#+OX_IPYNB_KERNEL_NAME: python3
,#+OX_IPYNB_LANGUAGE: python
,#+OX_IPYNB_NOTEBOOK_METADATA: {"custom_key": "value"}

Requirements

Pandoc must be installed for DOCX export. Install from https://pandoc.org/installing.html

Features

• High-quality conversion via Pandoc

• LaTeX equations render as native Word equations

• Bibliography support via pandoc-citeproc

• Full export options support (p:nil, todo:nil, tags:nil, etc.)

• Citation formats: org-ref (cite:key) and org-cite ([cite:@key])

• Embedded images from file links

• Tables with proper formatting

• Nested lists (ordered, unordered, description)

• Special blocks (quote, example, verse)

Basic Usage

Export the current org file to Word:

Code Blocks

Source blocks are exported as formatted code:

,#+BEGIN_SRC python
def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n-1) + fibonacci(n-2)
,#+END_SRC

Code blocks appear in Word with monospace formatting. Pandoc handles the conversion.

Images

Images from file links are embedded directly into the Word document:

[[file:diagram.png]]

Images are automatically scaled to fit within the page margins. Control image width with attributes:

#+ATTR_HTML: :width 400
[[file:large-diagram.png]]

Tables

Org tables are converted to Word tables with:

• Header row with bold text and shaded background

• Proper cell borders

• Caption support from #+CAPTION:

#+CAPTION: Experimental Results
| Method | Accuracy | Time (s) |
|--------+----------+----------|
| A      |     0.95 |     12.3 |
| B      |     0.97 |     15.6 |

Citations and Bibliography

DOCX export uses Pandoc's citeproc for full bibliography support. Both org-ref and org-cite citation formats are supported:

* My Document

Recent work cite:smith2023 demonstrates...

According to citet:jones2024, the approach...

You can also use org-cite: [cite:@smith2023] or [cite/t:@jones2024].

* References

bibliography:~/references.bib

The = line specifies your BibTeX file. Citations are automatically resolved and a formatted bibliography is generated at the end of the document.

Note: Add a * References heading where you want the bibliography to appear.

Sharing in Email

1. Position cursor on a headline

2. Press C-c k to copy as rich HTML

3. Paste into email - formatting, code blocks, and links are preserved

Copying to Word/Google Docs

1. Select the content or position on headline

2. C-c C-e k h to copy as rich HTML

3. Paste into document - tables, lists, and emphasis are formatted

Sharing Source Code

1. Position on headline containing code explanation

2. C-c C-e k m to copy as Markdown

3. Paste into GitHub issue or PR description

LaTeX Snippets

1. Select a portion with equations

2. C-c C-e k l to copy as LaTeX

3. Paste into LaTeX editor

Use Cases for Subtree Export

• Export a single chapter from a book

• Generate standalone reports from sections

• Create focused documentation for specific topics

• Share individual project components

Standalone (default)

Generates complete HTML document:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>My Document</title>
  <!-- CSS and JavaScript -->
</head>
<body>
  <main>
    <!-- Content -->
  </main>
</body>
</html>

Headline Levels

Control which headline levels become sections:

#+OPTIONS: H:4

• H:1 → Only top-level headlines become sections

• H:2 → Two levels (section, subsection)

• H:3 → Three levels (section, subsection, subsubsection)

• H:4 → Four levels (adds paragraph)

Section Numbering

Control section numbering:

#+OPTIONS: num:t      % Number all sections
#+OPTIONS: num:nil    % No numbering
#+OPTIONS: num:3      % Number up to level 3

In LaTeX output, this sets:

\setcounter{secnumdepth}{3}

Table of Contents

#+OPTIONS: toc:t      % Include TOC
#+OPTIONS: toc:nil    % No TOC
#+OPTIONS: toc:2      % TOC with 2 levels

Generates:

\tableofcontents
\newpage

Image Attributes

• :width - Image width (e.g., 0.8\textwidth, 12cm)

• :height - Image height

• :placement - Float placement ([htbp])

• :scale - Scale factor (0.5 for 50%)

BibTeX Integration

Include bibliography:

#+LATEX_HEADER: \usepackage{natbib}

Reference a citation cite:knuth1984.

bibliography:~/references.bib
bibliographystyle:plainnat

Citation Links

Org-ref style citations work directly:

• cite:key → \cite{key}

• citep:key → \citep{key} (parenthetical)

• citet:key → \citet{key} (textual)

• citeauthor:key → \citeauthor{key}

• citeyear:key → \citeyear{key}

Org-cite Citations [cite/STYLE/VARIANTS:@key]

Org-cite citations are translated to LaTeX through a configurable backend. The default backend, bibtex, emits natbib commands; the biblatex backend emits the corresponding biblatex commands.

Choose a backend with the setting scimax.export.latex.citeBackend (values bibtex or biblatex) or per-document with:

#+cite_export: bibtex
,#+cite_export: biblatex

Both the short and long org-cite spellings are accepted (t = text, a = author, na = noauthor, n = nocite, y = year). Variants are b (bare), c (caps), f (full); they may be combined as bc, cf, bcf or as hyphenated long names like bare-caps.

HTML Citation Export

HTML export includes full citation processing using citation-js, which formats citations according to standard citation styles (CSL).

#+BIBLIOGRAPHY: references.bib

Or use a bibliography link:
[[bibliography:~/path/to/references.bib]]

#+CSL_STYLE: apa

#+TITLE: My Research Paper
#+AUTHOR: Jane Doe
#+BIBLIOGRAPHY: references.bib
#+CSL_STYLE: apa

,* Introduction

Recent advances in machine learning cite:lecun2015 have enabled
remarkable progress in computer vision. According to citet:krizhevsky2012,
deep convolutional networks outperform traditional methods.

,* Methods

We follow the approach of citep:he2016,simonyan2014 for our experiments.

{
  "scimax.references.defaultCiteStyle": "citep"
}

Custom Environments

Use #+BEGIN_LATEX blocks for raw LaTeX:

#+BEGIN_LATEX
\begin{theorem}[Pythagorean Theorem]
For a right triangle with legs $a$ and $b$ and hypotenuse $c$:
\[a^2 + b^2 = c^2\]
\end{theorem}
#+END_LATEX

Special Blocks

Special blocks map to LaTeX environments:

#+BEGIN_abstract
This paper presents a novel approach...
#+END_abstract

#+BEGIN_theorem
If $P$, then $Q$.
#+END_theorem

#+BEGIN_proof
Assume $P$. Then...
#+END_proof

Math Environments

LaTeX math environments work directly:

\begin{equation}
E = mc^2
\label{eq:einstein}
\end{equation}

\begin{align}
x &= a + b \\
y &= c + d
\end{align}

pdflatex (default)

• Fast compilation

• Wide compatibility

• Standard LaTeX packages

• ASCII and Latin-1 support

Configuration:

{
  "scimax.latexLivePreview.compiler": "pdflatex"
}

xelatex

• Unicode support (UTF-8)

• System fonts (TrueType, OpenType)

• Modern typography

• Required for non-Latin scripts

Configuration:

{
  "scimax.latexLivePreview.compiler": "xelatex"
}

Example with system fonts:

#+LATEX_HEADER: \usepackage{fontspec}
#+LATEX_HEADER: \setmainfont{Libertinus Serif}
#+LATEX_HEADER: \setmonofont{Fira Code}

lualatex

• Unicode support

• Lua scripting in LaTeX

• Advanced typography

• Memory-efficient for large documents

Configuration:

{
  "scimax.latexLivePreview.compiler": "lualatex"
}

Benefits

• Automatic multiple passes (for TOC, references, etc.)

• Bibliography processing (BibTeX/Biber)

• Dependency tracking

• Incremental builds

Configuration File

Create .latexmkrc in your project directory:

# Use pdflatex
$pdf_mode = 1;

# Clean auxiliary files
$clean_ext = "synctex.gz synctex.gz(busy) run.xml";

# Custom compiler options
$pdflatex = 'pdflatex -interaction=nonstopmode -shell-escape %O %S';

Disabling latexmk

If you prefer direct compiler invocation:

{
  "scimax.latexLivePreview.useLatexmk": false
}

Build on Save

Automatically rebuild PDF when saving:

{
  "scimax.latexLivePreview.buildOnSave": true
}

Build on Idle

Build after idle period (useful for live preview):

{
  "scimax.latexLivePreview.buildOnIdle": true,
  "scimax.latexLivePreview.idleDelay": 2000
}

Forward Sync (Source → PDF)

1. Place cursor in org file

2. Press `C-c C-e l s'

3. PDF viewer jumps to corresponding location

Reverse Sync (PDF → Source)

C-click in PDF viewer (if supported) to jump to source line.

Headings

,* Level 1      →  # Level 1
,** Level 2     →  ## Level 2
,*** Level 3    →  ### Level 3

Text Formatting

*bold*          →  **bold**
/italic/        →  *italic*
_underline_     →  _underline_
+strikethrough+ →  ~~strikethrough~~
=code=          →  `code`
~verbatim~      →  `verbatim`

Lists

Unordered:

- Item 1
- Item 2
  - Nested

Ordered:

1. First
2. Second
3. Third

Code Blocks

#+BEGIN_SRC python
def hello():
    print("Hello")

Exports to:

```python
def hello():
    print("Hello")
```

Tables

| Name  | Age | City       |
|-------+-----+------------|
| Alice |  30 | New York   |
| Bob   |  25 | London     |

Exports to:

| Name  | Age | City       |
| ---   | --- | ---        |
| Alice | 30  | New York   |
| Bob   | 25  | London     |

Links

[[https://example.com][Example Site]]  →  [Example Site](https://example.com)
[[file:image.png]]                     →  [image.png](image.png)

Images

[[file:diagram.png]]  →  ![](diagram.png)

Syntax

#+OPTIONS: key1:value1 key2:value2 ...

Complete OPTIONS Reference

Examples

Full configuration:

#+OPTIONS: toc:3 num:t H:4 author:t date:t tags:nil todo:nil

Minimal export (no metadata):

#+OPTIONS: toc:nil num:nil author:nil date:nil tags:nil todo:nil pri:nil

Academic paper:

#+OPTIONS: toc:t num:t H:3 ^:{} author:t date:t email:t

Include all drawers:

#+OPTIONS: d:t c:t p:t

Include only specific drawers:

#+OPTIONS: d:("LOGBOOK" "NOTES")

Hide tags from headlines but keep them in TOC:

#+OPTIONS: tags:not-in-toc

Subscripts and Superscripts

The ^ option controls how _ and ^ are interpreted in body text:

The default was changed from t to {} because bare _ and ^ in prose (filenames, identifiers, math expressions) are usually meant literally. If you have an existing document that relied on bare-form subscripts, add #+OPTIONS: ^:t to restore the old behavior.

# Default behavior (subscripts only render with braces)
H_{2}O is water.    # → H<sub>2</sub>O is water
file_name.txt       # → literal: file_name.txt

# Old behavior (any underscore is a subscript)
#+OPTIONS: ^:t
H_2O is water.      # → H<sub>2</sub>O is water
file_name.txt       # → file<sub>name</sub>.txt (probably unwanted)

Required Keywords

#+TITLE: Document Title
#+AUTHOR: Your Name
#+DATE: 2024-01-15
#+EMAIL: you@example.com
#+LANGUAGE: en

Note: #+EMAIL is only included in output when email:t is set in OPTIONS.

HTML-Specific Keywords

#+HTML_HEAD: <style>body { font-family: sans-serif; }</style>
#+HTML_HEAD_EXTRA: <meta name="keywords" content="research, science" />
#+HTML_LINK_HOME: index.html
#+HTML_LINK_UP: ../index.html

LaTeX-Specific Keywords

#+LATEX_CLASS: article
#+LATEX_CLASS_OPTIONS: [11pt,a4paper]
#+LATEX_HEADER: \usepackage{geometry}
#+LATEX_HEADER: \geometry{margin=1in}
#+LATEX_COMPILER: pdflatex

✅ Export Settings Keywords

#+EXPORT_FILE_NAME: custom-output-name

#+TITLE: My Report
#+EXPORT_FILE_NAME: final-report-v2

,* Content here...

#+EXCLUDE_TAGS: noexport private draft

#+SELECT_TAGS: export publish

#+SELECT_TAGS: publish
#+EXCLUDE_TAGS: noexport

,* Internal Notes                                    :noexport:
Not exported (excluded).

,* Introduction
Not exported (no select tag).

,* Published Chapter                                 :publish:
Exported (has select tag).

,** Subsection
Also exported (child of published chapter).

Custom Header

Setting: scimax.export.latex.customHeader

Type: String (multiline)

Description: Complete custom LaTeX preamble replacing auto-generated one.

Example:

{
  "scimax.export.latex.customHeader": "\\documentclass[12pt]{article}\n\\usepackage[utf8]{inputenc}\n\\usepackage{graphicx}\n\\usepackage{amsmath}"
}

Or in settings.json:

{
  "scimax.export.latex.customHeader": [
    "\\documentclass[12pt]{article}",
    "\\usepackage[utf8]{inputenc}",
    "\\usepackage{graphicx}",
    "\\usepackage{amsmath}",
    "\\usepackage[colorlinks=true]{hyperref}"
  ]
}

Compiler

Setting: scimax.latexLivePreview.compiler

Values: "pdflatex", "xelatex", "lualatex"

Default: "pdflatex"

Example:

{
  "scimax.latexLivePreview.compiler": "xelatex"
}

Use latexmk

Setting: scimax.latexLivePreview.useLatexmk

Type: Boolean

Default: true

Description: Use latexmk for smart incremental builds (recommended).

Build on Save

Setting: scimax.latexLivePreview.buildOnSave

Type: Boolean

Default: true

Description: Automatically rebuild PDF when org file is saved.

Build on Idle

Setting: scimax.latexLivePreview.buildOnIdle

Type: Boolean

Default: false

Description: Rebuild PDF after idle period (for live preview).

Idle Delay

Setting: scimax.latexLivePreview.idleDelay

Type: Number (milliseconds)

Default: 2000

Description: Delay before idle build triggers.

Exclude Content by Tag

Tag headlines to exclude them from export:

#+EXCLUDE_TAGS: noexport private draft

,* Public Section
Content for everyone.

,* Private Notes                                    :noexport:
Internal notes not included in export.

,* Draft Ideas                                      :draft:
Work in progress, excluded.

Select Content by Tag

Only export tagged content:

#+SELECT_TAGS: export publish

,* Internal Document
This section won't be exported.

,* Published Chapter                                 :export:
This section will be exported.

HTML-Only Content

#+BEGIN_EXPORT html
<div class="alert alert-info">
  This appears only in HTML export.
</div>
#+END_EXPORT

LaTeX-Only Content

#+BEGIN_EXPORT latex
\begin{tcolorbox}[title=Important]
This appears only in LaTeX/PDF export.
\end{tcolorbox}
#+END_EXPORT

Export Snippets

Inline backend-specific content:

Click @@html:<button>@@here@@html:</button>@@ to continue.

The value is @@latex:\textcolor{red}{@@important@@latex:}@@.

Basic Syntax

,#+INCLUDE: "chapter1.org"
,#+INCLUDE: "path/to/file.org"

Paths can be relative (to the current document) or absolute.

Block Wrappers

Wrap included content in a block:

,# Include as source code block
,#+INCLUDE: "code/example.py" src python
,#+INCLUDE: "script.sh" src bash

,# Include as example (verbatim) block
,#+INCLUDE: "output.txt" example

,# Include as quote block
,#+INCLUDE: "excerpt.txt" quote

,# Include as export block (raw format)
,#+INCLUDE: "custom.html" export html

Line Selection with :lines

Include only specific lines from a file:

,# Lines 10 through 20 (inclusive, 1-indexed)
,#+INCLUDE: "data.org" :lines "10-20"

,# From line 10 to end of file
,#+INCLUDE: "data.org" :lines "10-"

,# From beginning to line 20
,#+INCLUDE: "data.org" :lines "-20"

,# Single line
,#+INCLUDE: "data.org" :lines "15"

Headline Level Adjustment with :minlevel

Shift all headlines in the included file to a minimum level:

,# Shift headlines so the minimum level is 2
,#+INCLUDE: "chapter.org" :minlevel 2

This is useful for including a standalone document as a section:

• A file with * Heading becomes ** Heading with :minlevel 2

• Sub-headlines are adjusted proportionally

Content Only with :only-contents

Strip the first headline and include only its contents:

,#+INCLUDE: "section.org" :only-contents t

This extracts the body of the first headline without including the headline itself.

Combining Options

Options can be combined:

,# Include lines 5-25 of Python file, shift headlines to level 3
,#+INCLUDE: "code.py" src python :lines "5-25"

,# Include chapter, make it a subsection (minlevel 2)
,#+INCLUDE: "chapter.org" :minlevel 2 :only-contents t

Recursive Includes

Included files can themselves contain #+INCLUDE: directives, which are processed recursively. A maximum depth of 10 levels prevents infinite loops.

Example: Modular Book Structure

,#+TITLE: My Book
,#+AUTHOR: Author Name

,#+INCLUDE: "frontmatter.org"

,* Part I: Introduction
,#+INCLUDE: "chapters/intro.org" :minlevel 2

,* Part II: Main Content
,#+INCLUDE: "chapters/chapter1.org" :minlevel 2
,#+INCLUDE: "chapters/chapter2.org" :minlevel 2

,* Appendices
,#+INCLUDE: "appendices/code-samples.org" :minlevel 2

,* Index
,#+INCLUDE: "backmatter/index.org" :only-contents t

MathJax Not Rendering

Problem: Math equations appear as plain text.

Solution:

1. Ensure internet connection (MathJax loads from CDN)

2. Check browser console for errors

3. Verify math syntax (use \(...\) or $...$ for inline, \[...\] for display)

Broken Images

Problem: Images don't appear in exported HTML.

Solution:

1. Use relative paths: [[file:.imagesplot.png]]

2. Ensure images are in same directory or subdirectory

3. Check image file names (case-sensitive on Linux)

CSS Not Applied

Problem: Custom CSS doesn't show.

Solution:

1. Verify #+HTML_HEAD: syntax

2. Check CSS selector specificity

3. Inspect generated HTML for CSS inclusion

Missing Packages

Problem: Compilation fails with "! LaTeX Error: File xyz.sty not found"

Solution:

# TeX Live
sudo tlmgr install xyz

# MiKTeX (Windows)
miktex packages install xyz

# MacTeX
sudo tlmgr install xyz

Unicode Errors

Problem: "! Package inputenc Error: Unicode character ... not set up"

Solution:

1. Switch to XeLaTeX or LuaLaTeX: #+BEGIN_SRC json { "scimax.latexLivePreview.compiler": "xelatex" } #+END_SRC

2. Or use LaTeX-safe characters

Bibliography Not Generated

Problem: Citations show as [?] in PDF.

Solution:

1. Ensure `.bib' file exists

2. Use `latexmk' (handles BibTeX automatically)

3. Check citation keys match bibliography entries

4. Verify bibliography: and bibliographystyle: links

Images Not Found

Problem: LaTeX can't find image files.

Solution:

1. Use relative paths from org file location

2. Avoid spaces in filenames

3. Use supported formats: PNG, JPG, PDF, EPS

4. Check \graphicspath if using custom image directories

Compilation Timeout

Problem: PDF export hangs or times out.

Solution:

1. Check for infinite loops in LaTeX code

2. Reduce document size

3. Disable auto-build: buildOnSave: false

4. Review `.log' file for warnings

Table Alignment

Problem: Tables don't align properly.

Solution:

• GitHub-flavored Markdown tables are left-aligned by default

• Org-mode alignment hints (<l>, <c>, <r>) are not supported

• Consider using HTML tables for complex layouts

Math Not Rendering

Problem: Math equations don't work.

Solution:

• GitHub supports some math via $$...$$ (display) and $...$ (inline)

• Other platforms may require MathJax integration

• Consider exporting to HTML for math-heavy content

Empty Export

Problem: Export produces empty or minimal file.

Solution:

1. Check export scope (full vs. subtree)

2. Verify content isn't excluded by tags

3. Ensure headlines match H: level setting

4. Review #+OPTIONS settings

Slow Export

Problem: Export takes very long.

Solution:

1. Disable `buildOnIdle' for PDF export

2. Reduce `toc' depth

3. Split large documents into smaller files

4. Use #+INCLUDE: for modular organization

Wrong Output Location

Problem: Export file appears in unexpected location.

Solution:

1. Check #+EXPORT_FILE_NAME: keyword

2. Verify save dialog selection

3. Review file permissions in target directory

Use Meaningful Headings

• Clear, descriptive headline text

• Logical hierarchy (avoid jumping levels)

• Consistent depth for similar content

Metadata at Top

#+TITLE: Document Title
#+AUTHOR: Your Name
#+DATE: 2024-01-15
#+OPTIONS: toc:t num:t
#+LATEX_CLASS: article

Separate Concerns

• Content in main file

• References in `.bib' file

• Images in images/ directory

• Custom styles in `.css' file

Track Generated Files Separately

Add to .gitignore:

*.pdf
*.html
*.tex
*.aux
*.log
*.out
*.toc

Use Meaningful Commit Messages

Update export configuration for XeLaTeX support
Add custom LaTeX preamble for ACM format
Fix image paths in HTML export

✅ For Large Documents

1. Disable auto-build during editing

2. Use #+INCLUDE: for modular structure

3. Cache expensive computations

4. Optimize image sizes

✅ For Fast Iteration

1. Use HTML preview for quick checks

2. Enable `buildOnIdle' with appropriate delay

3. Use body-only export for faster generation

4. Minimize custom packages

1. Initial Setup

#+TITLE: Novel Approach to Machine Learning
#+AUTHOR: Dr. Jane Smith
#+DATE: \today
#+OPTIONS: toc:t num:t H:3
#+LATEX_CLASS: IEEEtran
#+LATEX_HEADER: \usepackage{amsmath,amssymb}
#+LATEX_HEADER: \usepackage{algorithm,algorithmic}
#+BIBLIOGRAPHY: references.bib

2. Write Content

Structure with standard sections:

• Abstract

• Introduction

• Related Work

• Methodology

• Results

• Discussion

• Conclusion

3. Add Citations

Recent work cite:smith2023 has shown...

4. Export to PDF

`C-c C-e l p' → PDF via LaTeX

5. Submit

Review generated PDF, make final edits, submit.

1. Setup

#+TITLE: API Documentation
#+AUTHOR: Development Team
#+OPTIONS: toc:2 num:nil H:4
#+HTML_HEAD: <link rel="stylesheet" href="docs.css" />

2. Write Sections

• Getting Started

• API Reference

• Examples

• Troubleshooting

3. Export to HTML

`C-c C-e h h' → HTML

4. Deploy

Copy HTML and CSS to docs server or GitHub Pages.

✅ 1. Write in Org

#+TITLE: 10 Tips for Better Python Code
#+AUTHOR: Tech Blogger
#+DATE: 2024-01-15
#+OPTIONS: toc:nil num:nil

✅ 2. Export to Markdown

`C-c C-e m m' → Markdown

✅ 3. Publish

Copy Markdown to CMS or static site generator (Hugo, Jekyll, etc.)

✅ Org-Mode Documentation

• Official Export Documentation

• LaTeX Export Tutorial

• HTML Export Tutorial

✅ LaTeX Resources

• LaTeX Project

• CTAN - Package Archive

• Overleaf Learn LaTeX

✅ Tools

• MathJax Documentation

• highlight.js

• Pandoc - Universal Document Converter

Essential Packages (Auto-Included)

Optional Packages

Document Structure

• `.org-content' - Main content container

• `.org-section' - Document section

• `.org-preamble' - Document preamble

• `#title-block' - Title, author, date header

Headings and TOC

• `.org-toc' - Table of contents

• `.section-number' - Section number prefix

Text Elements

• `.org-todo' - TODO keyword

• `.org-done' - DONE keyword

• `.org-priority' - Priority marker

• `.org-tags' - Tag container

• `.org-tag' - Individual tag

• `.org-timestamp' - Timestamp

• `.org-underline' - Underlined text

Blocks

• `.org-src-container' - Source block wrapper

• `.src' - Source block pre element

• `.example' - Example block

• `.org-center' - Centered content

• `.org-latex-environment' - LaTeX environment

Tables and Lists

• `.org-table' - Table element

• `.org-footnotes' - Footnotes container

• `.org-footnote' - Individual footnote

• `.org-footnote-ref' - Footnote reference link

Admonitions

• `.admonition' - Generic admonition

• `.org-warning' - Warning box

• `.org-note' - Note box

• `.org-tip' - Tip box

• `.org-important' - Important box