openleaf

Configuration

Almost everything is in Settings (⌘,), applied the moment you change it. This page covers what those settings mean, where they are stored, and the parts that are only reachable from a terminal.

Where things live

Path	Contents
./projects/	your documents, one folder each
~/.config/openleaf/settings.json	global settings
<project>/.openleaf.json	that project’s main file and engine
~/.cache/openleaf/build/<project>/	.aux, .log, .synctex.gz, the PDF
~/.cache/openleaf/history/<project>/	version snapshots
~/.cache/openleaf/browser-profile/	the app window’s size and zoom

Two things follow from this layout:

Your project folders stay readable. Build artifacts go to the cache, not next to your sources, so a project folder contains only files you wrote. That makes git status useful without a .gitignore full of TeX extensions.

Deleting the cache is always safe. rm -rf ~/.cache/openleaf loses your version history and forces a full rebuild, and nothing else.

For a global install (npm install -g openleaf), projects default to ~/OpenLeaf instead, because the install directory lives inside node_modules and is not a sensible place for documents.

Two tiers of settings

Anything about the build belongs to the project, so a document that needs XeTeX keeps that choice and carries it if you share the folder:

• engine
• main
• layout, splitRatio

Anything about how the app behaves belongs to the machine, so switching projects does not change your font size:

• theme, accent, transparency
• editorFontSize, editorLineHeight, editorMaxWidth, lineWrapping
• focusMode, spellCheck, showInvisibles
• autoCompile, compileDelayMs
• doubleClickSync, pdfSyncOnType
• snapshotOnCompile
• sidebarWidth

Project settings win where they are set.

Settings reference

Editing

Compile as you type. Rebuilds shortly after you stop typing. Worth turning off on a document where a build takes several seconds, and using ⌘↩ instead.

Wait before compiling. 300ms to 4s. Lower feels more immediate; higher avoids rebuilding mid-sentence. The default of 1.1s is about the length of a natural pause.

Wrap long lines. On by default. Off gives you horizontal scrolling, which some people prefer for tables.

Focus mode. Dims every line except the one the cursor is on. Useful for a first draft, less so for editing a table.

Check spelling. Uses the browser’s own spellchecker. It does not understand LaTeX, so it will underline command names.

Show invisible characters. Reveals tabs and trailing spaces.

Typography

Text size. 10px to 22px, editor only.

Line spacing. 1.2 to 2.2. More space is easier to scan, less fits more on screen.

Line length. Caps how wide the text runs, measured in characters. A 120-character line of prose is hard to read, and on a wide display the editor is otherwise as wide as the pane. Zero means full width.

Preview

Double-click the PDF to find the source. On by default. ⌘-click works regardless, so turning this off only disables the plain double-click, which is worth doing if you select text in the preview a lot.

Follow the cursor in the preview. Scrolls the PDF to match the line you are editing after each rebuild. Some people find this essential and others find it disorienting, hence the switch.

Build

LaTeX engine. Automatic uses the fastest installed. See engines.

Keep version history. Records a compressed snapshot per save. Turn it off if you version with git and would rather not keep two histories.

Appearance

Theme. Dark, light, or match the system. “Match the system” follows changes live, including at sunset if your OS is set up that way.

Accent colour. Violet, blue, green, amber, rose or cyan. It drives selections, highlights, the active file marker and the document graph, so the whole interface follows one hue.

Frosted panels. The sidebar, toolbars and dialogs are translucent with a blurred backdrop. Turn it off for plain opaque surfaces, which is worth doing on a slower machine or if the effect is distracting. OpenLeaf also drops it automatically when the system asks for reduced transparency.

Editing the files directly

Both config files are JSON and can be edited by hand. Unknown keys are ignored and numbers are clamped, so a mistake cannot break the interface.

~/.config/openleaf/settings.json:

{
  "theme": "dark",
  "accent": "violet",
  "transparency": true,
  "autoCompile": true,
  "compileDelayMs": 1100,
  "editorFontSize": 13.5,
  "editorLineHeight": 1.68,
  "editorMaxWidth": 0,
  "lineWrapping": true,
  "focusMode": false,
  "spellCheck": false,
  "showInvisibles": false,
  "doubleClickSync": true,
  "pdfSyncOnType": false,
  "snapshotOnCompile": true,
  "sidebarWidth": 260
}

theme accepts dark, light or system. accent accepts violet, blue, green, amber, rose or cyan. An unrecognised value is dropped rather than stored, so a typo here cannot leave the interface in a state the code does not handle.

<project>/.openleaf.json:

{
  "main": "main.tex",
  "engine": "latexmk-xelatex"
}

Engine ids are latexmk, latexmk-xelatex, latexmk-lualatex, pdflatex and tectonic. main is relative to the project folder.

The project file is worth committing to git: it records which file is the root, which is the one piece of information a collaborator cannot infer.

Environment variables

OPENLEAF_HOME	projects folder
PORT	server port, default 4173, auto-incremented if taken
HOST	bind address, default 127.0.0.1

OPENLEAF_HOME=~/Documents/Papers openleaf
openleaf --projects ~/Documents/Papers    # the same thing

A note on HOST

HOST exists because the server needs to bind somewhere, not as an invitation to change it. Setting it to 0.0.0.0 exposes a filesystem-reading API to your entire network with no authentication of any kind. Do not do this. If you want to reach OpenLeaf from another machine, use an SSH tunnel:

ssh -L 4173:127.0.0.1:4173 you@your-machine

That keeps the bind on localhost and the traffic encrypted.

Command line

openleaf [options]

  --no-open          start the server without opening a window
  --browser          use your default browser instead of an app window
  --port <n>         listen on a specific port
  --projects <dir>   use a different projects folder
  --version          print the version
  --help             show this message

npm run serve runs the server alone with no window, which is what you want when developing or running it under a process manager.

Command palette as configuration

Several things that would otherwise be settings are one-off actions in the palette (⌘K) instead, because they are per-moment rather than per-preference:

• Change the LaTeX engine
• Set the main document
• Switch theme
• Change the accent colour
• Turn focus mode on or off
• Turn frosted panels on or off
• Turn compile-as-you-type on or off
• Switch layout

This site is open source. Improve this page.