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-<uuid>, 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

FAQ

Frequently asked questions

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.