openleaf

Getting started

A walkthrough for someone who has never used OpenLeaf, and possibly never used LaTeX outside a browser.

1. Install

npm install
npm start

npm install pulls the dependencies and builds the interface. npm start opens OpenLeaf in its own window.

You also need a LaTeX engine, which is the program that turns .tex files into a PDF. If you have never installed one:

brew install texlive                      # macOS
sudo apt install texlive-full latexmk     # Debian, Ubuntu

That download is large, around 4 GB, because it includes every package. A smaller option is brew install tectonic, a single binary that downloads packages the first time a document needs them. OpenLeaf works with either and picks whichever is fastest.

You can check what it found by clicking the engine name in the bottom-right corner of the window.

2. The window

Five regions, and nothing hidden behind a menu:

┌──┬────────────────────────────────────────────────────────────────┐
│  │  ☰  🔍            My Paper   Saved      ▣▥▤   Auto  ▶ Compile │
│  ├──────────────┬─────────────────────────┬──────────────────────┤
│▤ │              │                         │                      │
│≡ │   Sidebar    │        Editor           │      Preview         │
│⚭ │              │                         │                      │
│▦ │   files      │   your .tex source      │   the PDF            │
│⚠ │   outline    │                         │                      │
│◷ │   graph      │                         │                      │
│▩ │   refs       │                         │                      │
│⇅ │   ...        │                         │                      │
│  ├──────────────┴─────────────────────────┴──────────────────────┤
│  │ ● Compiled in 0.7s              graph  engine  main.tex  Ln 1 │
└──┴────────────────────────────────────────────────────────────────┘

The rail on the far left switches what the sidebar shows. Hover any icon for its name, or use ⌘1 through ⌘8.
The title in the centre is your project. Click it for project actions.
Auto on the right controls whether the document rebuilds as you type.
The status bar shows the last build, and is clickable throughout: the engine name changes engines, the filename changes which file is the root.

3. Write something

The starter project opens with main.tex. Change a heading and watch the preview: it rebuilds about a second after you stop typing. ⌘↩ builds immediately if you do not want to wait.

Try these:

Select a word and press ⌘B. It becomes \textbf{word}. Press ⌘B again to undo that.
Type \sec and pause. Autocomplete offers \section and friends.
Type \ref{ and it lists the labels that actually exist in your project.
Press ⌘8 for the Insert panel, then click Figure. A complete figure environment lands at your cursor.

4. Move between the source and the PDF

This is the thing worth learning, because it is what makes a long document manageable.

From the PDF to the source: double-click any word in the preview. The editor jumps to the line that produced it, even if that line lives in a different file.

From the source to the PDF: put the cursor anywhere and press ⌘J. The preview scrolls there and flashes the spot.

Citations: click a [Knuth, 1984] in the PDF and the matching .bib entry opens at its exact line.

None of this needs setting up. It works because the engine emits a SyncTeX file alongside the PDF, and OpenLeaf reads it.

5. Add a reference

Press ⌘⇧F and type a paper title, or an author, or a DOI, or an arXiv id.

Results come from DBLP, Crossref, OpenAlex and arXiv at once. Each shows which of those sources agree on it, which is a decent proxy for whether the metadata is right. Press ↩ on the one you want:

The real BibTeX is fetched from the publisher or DBLP, not reconstructed
It is appended to your .bib with a key like knuth1984texbook
\cite{knuth1984texbook} is inserted at your cursor
The document recompiles

Already have a .bib full of entries from elsewhere? Press the ✓ in the References pane and every one is checked against the published record. The most common thing it finds is an author list that got truncated to two names.

6. Look at the graph

Press ⌘3, then the expand icon to fill the window.

Each circle is a file, a label, a citation or an image, and each line is a link between them. Bigger circles have more words. Click one to open it.

The useful part is what shows up in red and amber:

Dashed red circle: something referenced that does not exist. A \ref with no \label, a \cite with no bibliography entry, an image that is not there.
Amber ring: a file that exists but is not reachable from your main document, which usually means a chapter you forgot to \input.

The sidebar lists the same problems as text, and clicking one takes you to where it is used.

7. Bring in an existing project

If you have work in Overleaf:

In Overleaf, Menu → Download → Source
Drag the .zip onto the OpenLeaf window

It becomes a project, keeps its folder structure, and compiles straight away.

A plain folder works the same way, dropped or picked through Import in the Projects pane.

8. Set it up how you like

⌘, opens settings. The ones people change first:

Compile as you type, and how long it waits
Editor text size
Theme: dark, light, or follow the system
LaTeX engine, saved per project

Everything applies immediately. There is no Save button.

Where your files are

In projects/ next to the checkout. They are ordinary folders of ordinary files:

projects/My Paper/
  main.tex
  references.bib
  sections/results.tex
  figures/plot.png
  .openleaf.json      which file is the root, and which engine

Open them in Finder, put them in git, back them up. Build artifacts like .aux and .log go to ~/.cache/openleaf/ instead, so your folder stays readable.

What next

This site is open source. Improve this page.