Everything needed to use, run, build, deploy, and maintain LatexDo.

System Overview

LatexDo at a glance

The core product lives in the `latexdo` repository. It contains the Electron desktop shell, the shared React and Monaco editor frontend, local file/project operations, LaTeX compilation through `latexmk`, PDF preview, diagnostics, Git tools, importers, and the source for the CLI and website assets that are synced downstream.

Quickstart

Install or open the editor

curl -fsSL https://latexdo.org/install.sh | bash
latexdo doctor
latexdo

Requirements

• Node.js 20 or newer for development and the CLI-managed local editor.
• Git and npm for the CLI cache/update flow.
• A TeX distribution with `latexmk` for local desktop PDF compilation.
• MacTeX on macOS, MiKTeX or TeX Live on Windows, TeX Live on Linux.

Product Matrix

Choose the right LatexDo surface

User Guide

Writing workflow

LatexDo is organized around a source-to-preview workflow. Open or create a project, edit `.tex` and `.bib` files in Monaco, choose the root `.tex` file and engine, compile, inspect diagnostics, then use the PDF preview and side panels to resolve paper-level issues.

Editor and paper tools

Default analysis checks

Desktop App

Native local editing and compilation

The desktop app is an Electron shell around the shared React frontend. It exposes a secure preload API at `window.latexdo` and a terminal API at `window.terminalApi`. The renderer never reaches directly into Node APIs; project operations go through IPC handlers in `electron/main.ts`.

Local compile behavior

`electron/compiler.ts` searches for `latexmk`, preferring common macOS paths such as `/Library/TeX/texbin/latexmk`. It creates an isolated build directory under `.latexdo/build/job-`, runs `latexmk`, enables SyncTeX, uses `-file-line-error` and `-halt-on-error`, then returns a `CompileResult`.

latexmk -pdf|-xelatex|-lualatex \
  -g \
  -synctex=1 \
  -interaction=nonstopmode \
  -file-line-error \
  -halt-on-error \
  -outdir=.latexdo/build/job-<uuid> \
  main.tex

Desktop-only capabilities

• Open local folders and read/write real files.
• Run `latexmk` with local TeX packages and fonts.
• Read generated PDFs and use SyncTeX forward/backward jumps.
• Use a real terminal in the project directory.
• Inspect Git status, stage/unstage, commit, diff, discard, and history.
• Import DOCX and Markdown through desktop import handlers.
• Use local spellchecking and optional LanguageTool-compatible proofreading.

Desktop build commands

npm install
npm run dev
npm run typecheck
npm test
npm run build
npm run package
npm run dist

Web Editor

Browser, local, and cloud runtime modes

The shared frontend installs browser APIs when Electron does not provide `window.latexdo`. The runtime is selected by `VITE_LATEXDO_RUNTIME`. Without the cloud flag, the editor uses a browser workspace stored in `localStorage`. With `cloud`, it uses HTTP APIs served by `editor.latexdo.org`.

Cloudflare hosting

The `editor.latexdo.org` repository deploys a Cloudflare Worker named `editor-latexdo-org`. Static assets come from `dist/`, and all `/api/*` requests are proxied to a Cloudflare Container running the Fastify backend. The Container image is built from `Dockerfile` and includes Node 22, `latexmk`, Pandoc, and TeX Live packages.

Command Line

The `latexdo` CLI

The CLI installs one shell command. Running `latexdo` keeps a cached checkout of `https://github.com/latexdo/latexdo.git` in `~/.latexdo/app`, updates it unless disabled, installs npm dependencies when `package-lock.json` changes, starts Vite, and opens the localhost URL.

CLI environment variables

Website

`latexdo.org` and downloads

The website repository is the published static site. The source version also lives under `latexdo/website`. The main app sync script builds the TypeScript website, copies the CLI install script and command into the website, formats the generated assets, and rsyncs the result to the website repository.

Website responsibilities

• Marketing and product explanation at `latexdo.org`.
• Hosted installer script at `https://latexdo.org/install.sh`.
• CLI binary script at `https://latexdo.org/bin/latexdo`.
• Direct downloads under `/downloads/`.
• Download manifest at `/downloads/manifest.json`.
• Checksums at `/downloads/SHA256SUMS.txt`.
• Update feed at `/updates/latest.json`.

Download manifest shape

{
  "schemaVersion": 1,
  "product": "LatexDo",
  "version": "0.1.0",
  "publishedAt": "ISO timestamp",
  "commit": "git sha",
  "repository": "latexdo/latexdo",
  "downloadsPage": "https://latexdo.org/downloads/",
  "files": [
    {
      "id": "macos-arm64",
      "platform": "macos",
      "arch": "arm64",
      "filename": "LatexDo-macos-arm64.dmg",
      "sha256": "..."
    }
  ]
}

Architecture

How the repositories fit together

`latexdo` is the active development repository. It can run as an Electron desktop application or as a Vite web application. The hosted editor is a cloud deployment of the same frontend built with `VITE_LATEXDO_RUNTIME=cloud`, paired with a backend in `editor.latexdo.org`.

Data boundaries

Desktop project ID

References a local folder selected through Electron. File access stays on the machine.

Browser project ID

References a project object in `localStorage`; suitable for draft editing, not durable storage.

Cloud project ID

References backend files under a session directory. Share tokens can grant another browser access to the same project.

Cloud API

Hosted editor backend reference

Cloud API requests are JSON unless the PDF route returns `application/pdf`. Most routes require the `x-latexdo-session` header. Collaboration-aware project routes can also accept `x-latexdo-share-token`.

Compile request

{
  "projectId": "project-id",
  "rootFile": "main.tex",
  "engine": "pdflatex"
}

Compile response

{
  "ok": true,
  "pdfPath": "main.pdf",
  "durationMs": 1240,
  "output": "latexmk output",
  "diagnostics": [],
  "error": null
}

Development

Set up the repositories

Use Node.js 20 or newer for the app, website, and cloud backend. The app CI uses Node.js 22, so match that locally when debugging build or native-module issues.

cd /Users/omar/Desktop/Github/latexdo
npm install
npm run dev

cd /Users/omar/Desktop/Github/latexdo
npm run web

cd /Users/omar/Desktop/Github/editor.latexdo.org
npm install
LATEXDO_DATA_ROOT=./storage/dev npm run server:dev

Quality commands

Sync downstream repositories

Run `npm run sync:downstream` from the main app repository after changes to CLI, website source, or hosted frontend behavior. The script syncs `../latexdo-cli`, `../latexdo.org`, and `../editor.latexdo.org` by default. Override target paths with `LATEXDO_CLI_REPO`, `LATEXDO_WEBSITE_REPO`, and `LATEXDO_EDITOR_REPO`.

Release And Deploy

Build, package, and publish LatexDo

The main app has two relevant workflows: `latexdo-ci` for validation and installer artifacts, and `latexdo-release` for publishing direct downloads to the website repository.

CI flow

• Runs format, lint, typecheck, tests, coverage, and app build.
• Packages an ad-hoc signed macOS Apple Silicon DMG.
• Packages a Windows x64 NSIS installer.
• Uploads `latexdo-installers-<commit>` with installers and checksums.

Release flow

• Builds macOS Apple Silicon, macOS Intel, and Windows x64 artifacts.
• Uses Developer ID signing and notarization if Apple secrets are present.
• Falls back to ad-hoc signed macOS DMGs if signing secrets are missing.
• Generates `/downloads/manifest.json`, `/downloads/SHA256SUMS.txt`, and `/updates/latest.json`.
• Publishes to `latexdo/latexdo.github.io` when `LATEXDO_WEBSITE_TOKEN` is configured.

Required release secrets

Cloud editor deploy

The current `editor.latexdo.org` repo is configured for Cloudflare Workers Builds. Build command: `npm run build`. Deploy command: `npx wrangler deploy`. If the build logs say Docker is unavailable, push a prebuilt image and update the container image in `wrangler.jsonc`.

Security

Trust boundaries and safeguards

LaTeX compilation can execute complex toolchains and consume large amounts of CPU, memory, and disk. Treat compile services as untrusted-input execution environments.

Path safety

Backend project paths are normalized to relative paths, reject `..`, and are resolved under the project root before file operations. Project IDs and session/share tokens are constrained to safe character sets and lengths.

Troubleshooting

Common problems

Maintenance

Keep docs accurate

Update these docs whenever a command, API route, runtime capability, release artifact, or deployment requirement changes. The safest maintenance pattern is to update docs in the same branch as the product change, then verify that all documented commands still match `package.json`, workflow files, and runtime adapters.

Documentation checklist

• Check `latexdo/package.json` for command changes.
• Check `electron/preload.cts` for desktop API changes.
• Check `src/browserApi.ts` and `src/cloudApi.ts` for runtime boundaries.
• Check `editor.latexdo.org/server/src/index.ts` for backend API changes.
• Check `editor.latexdo.org/wrangler.jsonc` for deploy target changes.
• Check `latexdo/.github/workflows/*.yml` for CI and release changes.
• Check `latexdo/scripts/sync-downstream-repos.sh` for sync behavior.