Skip to content

Getting started ​

bbtex adds a set of LaTeX — commands to BBEdit's Scripts menu, all backed by one small bbtex binary. This page gets you from nothing to a compiled PDF in about ten minutes, most of it spent waiting for MacTeX to download.

TIP

Current release: v0.2.0. It's early, and it's totally vibe coded. It works well on my Mac; if it doesn't on yours, please open an issue.

Requirements ​

  • An Apple Silicon Mac. Packages are built and tested on the macOS version of the Mac that ran the release checks; Intel builds are not verified.
  • BBEdit.
  • A TeX distribution: MacTeX or TinyTeX, which provide latexmk, pdflatex, xelatex and lualatex. With Biber, use version 2.21 or later with a matching biblatex.
  • Skim for PDF viewing and SyncTeX.

Optional:

  • Tectonic, if you prefer it to latexmk.
  • Poppler's pdftoppm (brew install poppler), for equation previews.
  • TexLab, for completion and Go to Definition in BBEdit.

Install ​

From a release package ​

  1. Download bbtex-macos-arm64.bbpackage.zip from the Releases page and unzip it.
  2. Double-click bbtex.bbpackage. BBEdit installs it into ~/Library/Application Support/BBEdit/Packages/.
  3. Clear the download quarantine, or macOS blocks the unsigned binary with "Apple could not verify “bbtex” is free of malware". Quit BBEdit, then run xattr -dr com.apple.quarantine ~/Library/Application\ Support/BBEdit/Packages/bbtex.bbpackage.
  4. Run Scripts → LaTeX — Doctor to check the TeX tools, Skim and the package layout.

Starting from a brand-new Mac? The clean install walkthrough goes step by step, with a test document and uninstall instructions.

Preview on Save and the right-click Preview Selection service are optional installs; see equation previews.

From source ​

You need opam with OCaml 4.14 or later (CI builds with 5.4.1).

sh
git clone https://github.com/LouLouLibs/bbtex.git
cd bbtex
opam install . --deps-only   # dune, uucp and uunf
scripts/install.sh

This builds the binary, links it to ~/.local/bin/bbtex, and links the scripts into BBEdit's Scripts folder. Install either the development scripts or the release package, not both, or the menu shows duplicates.

Set up BBEdit ​

Keyboard shortcuts ​

Assign shortcuts in BBEdit → Settings → Menus & Shortcuts, in the Scripts section:

ScriptSuggested shortcut
LaTeX — Compile⌘K
LaTeX — Forward Search⇧⌘J
LaTeX — Compile With…⇧⌘K
LaTeX — Cleannone

Remove any existing binding for those keys first. You can also assign keys in Window → Palettes → Scripts.

In Skim → Settings → Sync:

FieldValue
PresetCustom
Command/usr/local/bin/bbedit
Arguments--line %line "%file"

Now ⌘-click in Skim jumps back to the source line in BBEdit.

First build ​

  1. Open a .tex file in BBEdit.
  2. Press ⌘K. bbtex saves the document and any modified project inputs, compiles the root, and opens the PDF in Skim at the cursor.
  3. Errors appear in the LaTeX Results browser. Click one to reach its line, fix it, and press ⌘K again. A successful build closes old results without opening a window. Under errors it recognises, bbtex adds a short explanation starting with [bbtex], such as "A command isn't defined: check for a typo, or a missing \usepackage." TeX's own message is never changed.
  4. Press ⇧⌘J to show the cursor's position in the PDF.
  5. LaTeX — Show Build Results lists warnings and bad boxes without rebuilding; LaTeX — Open Build Log shows the full compiler output.

A silent notification reports the root, engine, duration and diagnostic counts.

The compiled demo paper open in Skim

LaTeX Results listing an undefined control sequence in model.tex, line 7

Choose the engine and main file ​

Put TeXShop-style comments near the top of a file (bbtex reads the first 50 lines). These two choose the engine and the main file:

latex
%!TEX program = xelatex
%!TEX root = ../main.tex
  • program is pdflatex (the default), xelatex, lualatex or tectonic. The first three run through latexmk, which handles passes and BibTeX/Biber; Tectonic runs directly.
  • root points an included chapter or table at the main document, relative to the file that contains it. Without it, bbtex builds the one document in the same folder or one folder up that includes the file, as in an Overleaf project, and says so in the notification (details).
  • LaTeXTools' options and output_directory, TeXShop's parameter and % !BIB TS-program are read too; see build settings in comments.

Rather than typing these, press ⇧⌘K and choose Configure Document…. The same Compile With… picker also runs a one-off build with another engine or a named profile. For settings shared across a project, such as the output directory, extra options and profiles, add a .bbtex file.

Next steps ​

MIT licensed. Vibe coded with Claude Code. Part of LouLouLibs.