Clean install walkthrough
This takes a Mac with nothing LaTeX-related on it to a working bbtex: a compiled PDF, SyncTeX in both directions and an equation preview. It's also the check I want every release to pass on a fresh macOS account before I call it done. It takes about half an hour, most of it waiting for MacTeX to download.
Install the tools
BBEdit. Download it from barebones.com and move it to
/Applications. The free mode is enough.MacTeX. Download
MacTeX.pkgfrom tug.org/mactex and run the installer. It provides pdfLaTeX, XeLaTeX, LuaLaTeX, latexmk, BibTeX, Biber andpreview.sty. Open a new Terminal window afterwards and check:shlatexmk -v | head -1 biber --version # 2.21 or laterSkim. Download it from skim-app.sourceforge.io and move it to
/Applications.Optional, for equation previews and completion: with Homebrew installed,
shbrew install poppler texlabpopplerprovidespdftoppm, which turns previews into images.texlabgives BBEdit LaTeX completion and Go to Definition.
Install bbtex
Download
bbtex-macos-arm64.bbpackage.zipfrom the latest release and double-click it to unzip. If you want to check the download, compareshasum -a 256 bbtex-macos-arm64.bbpackage.zipwithSHA256SUMS-arm64.txtfrom the same release.Move
bbtex.bbpackageinto BBEdit's packages folder:shmkdir -p ~/Library/Application\ Support/BBEdit/Packages mv ~/Downloads/bbtex.bbpackage ~/Library/Application\ Support/BBEdit/Packages/Clear the download quarantine. bbtex isn't signed with an Apple Developer ID yet, so macOS blocks a copy downloaded with a web browser and shows "Apple could not verify “bbtex” is free of malware…". With BBEdit quit, run:
shxattr -dr com.apple.quarantine ~/Library/Application\ Support/BBEdit/Packages/bbtex.bbpackageOnly do this for a package you downloaded from the release page above.
Open BBEdit. The Scripts menu now has a set of LaTeX — commands and a LaTeX Editing submenu.
Run Scripts → LaTeX — Doctor. It checks the TeX tools, Skim, the package and BBEdit's setup, without changing anything. Items marked
OPTIONALare fine to skip; fix anything markedWARN. If it prints a[bbtex]quarantine message instead, repeat step 3.
Set up BBEdit and Skim
Shortcuts. In BBEdit → Settings → Menus & Shortcuts, scroll to Scripts and assign:
Script Shortcut LaTeX — Compile ⌘K LaTeX — Forward Search ⇧⌘J LaTeX — Compile With… ⇧⌘K Remove any existing command that already uses one of those keys.
Inverse search. In Skim → Settings → Sync, choose the Custom preset, command
/usr/local/bin/bbedit, arguments--line %line "%file". If/usr/local/bin/bbeditdoesn't exist, install BBEdit's command-line tools from BBEdit → Install Command Line Tools….TexLab (optional). If you installed
texlab, open BBEdit → Settings → Languages, select TeX, and check that the language server is enabled and findstexlab.
First build
Make a test folder with one file,
test.tex:latex\documentclass{article} \usepackage{amsmath} \begin{document} \section{Hello}\label{sec:hello} Energy is \begin{equation}\label{eq:energy} E = mc^2 \end{equation} See Section~\ref{sec:hello}. \end{document}Open it in BBEdit and press ⌘K. The first time, macOS may ask whether BBEdit may control Skim; allow it. Skim opens the PDF at the cursor without taking focus, and a notification reports the build.
Errors. Change
\sectionto\sectoinand press ⌘K. LaTeX Results opens with an error on line 4; click it to jump there. Fix it and build again: the error is gone.SyncTeX. Put the cursor on the equation and press ⇧⌘J; Skim highlights it. ⌘-click a word in Skim to jump back to BBEdit.
Preview (needs Poppler). Select
E = mc^2and run Scripts → LaTeX — Preview Selection. A small window shows the rendered equation, and your selection stays in place.Outline. Run Scripts → LaTeX — Project Outline Window, search for
energy, and press Return to jump to the equation.
If each step works, the install is good.
Optional extras
Preview on save. Install the save attachment, then turn it on per file with LaTeX — Toggle Preview on Save:
sh"$HOME/Library/Application Support/BBEdit/Packages/bbtex.bbpackage/Contents/Resources/install-preview-save-hook.sh" --applyIt refuses to replace another tool's save attachment.
Right-click preview. Add LaTeX — Preview Selection to BBEdit's Services menu:
sh"$HOME/Library/Application Support/BBEdit/Packages/bbtex.bbpackage/Contents/Resources/bbtex" preview-service installLive selection preview needs nothing extra: run LaTeX — Toggle Live Selection Preview.
See equation previews for details.
Upgrade or roll back
- Quit BBEdit.
- Move the installed
bbtex.bbpackagesomewhere safe (it's your rollback copy). - Install the new release as above, including the quarantine step.
- Open BBEdit and run LaTeX — Doctor and one build.
To roll back, quit BBEdit, put the old package back in Packages, and reopen BBEdit.
Uninstall
Turn off Preview on Save and Live Selection Preview if you use them, close any bbtex preview windows, and quit BBEdit.
Remove the package:
shrm -rf ~/Library/Application\ Support/BBEdit/Packages/bbtex.bbpackageIf you installed the save attachment, remove
~/Library/Application Support/BBEdit/Attachment Scripts/Document.documentDidSave.scptandDocument.documentDidSave.scpt.bbtex-receipt, but only if Doctor still identifies it as bbtex's unchanged hook. If another tool shares it, leave it for manual review.If you installed the right-click service, remove
~/Library/Services/LaTeX — Preview Selection.workflow.Optionally delete bbtex's cache and state,
~/.local/state/bbtex.
Your documents, PDFs and TeX installation are never touched.
If something goes wrong
Start with troubleshooting. If a step here doesn't match what you see, that's a bug in these instructions: open an issue and include the Doctor report, plus your macOS, BBEdit and MacTeX versions.