Verso/README.md

<p align="center">
  <img src="services/web/public/img/ol-brand/verso-logo.svg" alt="Verso" width="440">
</p>

**A collaborative, real-time editor for LaTeX, Quarto and Typst — self-hosted.**

---

## What is Verso?

Verso is a fork of [Overleaf](https://github.com/overleaf/overleaf) that extends its
collaborative editing infrastructure to support [Quarto](https://quarto.org) and
[Typst](https://typst.app) projects alongside LaTeX. Think of it as Overleaf, but
not limited to LaTeX.

### Verso vs Overleaf

[Overleaf](https://www.overleaf.com) is the gold standard for collaborative LaTeX
editing. Verso keeps everything that makes Overleaf great — real-time co-editing,
operational-transformation history, auth, project management, file storage — and
adds:

- **Quarto and Typst compilers** running alongside TeX Live, dispatched
  automatically from the root file's extension (`.qmd` → Quarto, `.typ` → Typst,
  `.tex` → `latexmk`).
- **Language-aware editor** for Quarto and Typst (syntax highlighting, completions,
  document outline) — not just LaTeX.
- **Publish & share compiled output** (`/p/:token` with tiered access links) — a
  feature absent from Overleaf Community Edition.
- **Lumière theme** — a redesigned project dashboard and editor chrome with a
  card-based grid, thumbnails, and a teal gradient identity.
- **Full i18n** — French, German, Italian, and Spanish UI translations on top of
  Overleaf's English base.
- Completely **free and self-hosted**; no Overleaf subscription required.

### Verso vs Quarto

[Quarto](https://quarto.org) is a command-line tool: you install it locally, write
`.qmd` files in any text editor, and run `quarto render` in a terminal. It is
excellent for solo authors with full control over their environment.

Verso wraps Quarto in a collaborative web editor:

- **No local install** — Quarto, Typst, TeX Live and Python run on the server.
- **Real-time collaboration** — multiple people edit the same `.qmd` simultaneously
  with live cursors and conflict-free merging.
- **Not just Quarto** — LaTeX and Typst projects live in the same workspace, under
  the same auth and history system.
- **Publish in one click** — RevealJS decks and PDFs are served at a stable link
  without leaving the browser.

Verso is not a replacement for Quarto's CLI — it is a platform that makes Quarto
accessible as a shared, always-on service.

### Verso vs Typst.app

[Typst.app](https://typst.app) is a cloud-hosted web editor for Typst. It is
polished and fast, but it is a proprietary SaaS product and only supports Typst.

Verso differs in that:

- It is **self-hosted** and open-source (AGPL v3) — you control your data.
- It supports **three languages** (Typst, LaTeX, Quarto) in one instance.
- Real-time collaboration is powered by **operational transformation** (the same
  engine as Overleaf), not CRDTs, which means it handles concurrent edits
  gracefully for long documents.
- It ships with a full **project history** and version-restore workflow.

If you only need Typst and want a lighter, Typst-focused alternative, have a look
at **[Collabst](https://github.com/herluf-ba/collabst)** — an open-source,
self-hosted collaborative Typst editor that is independent of the Overleaf
codebase and shows a lot of promise.

---

## Features

- **Real-time collaboration** — multiple editors, live cursors, full project history and version restore.
- **Three compilers, auto-dispatched** by root file extension:
  | Root file | Compiler | Typical output |
  |-----------|----------|----------------|
  | `.qmd` | Quarto | PDF (via Typst or LaTeX), HTML, or RevealJS |
  | `.tex` | `latexmk` / TeX Live | PDF |
  | `.typ` | Typst | PDF |
- **Language-aware editor for all three** — syntax highlighting, completions, and a document outline panel for LaTeX, Quarto and Typst.
- **Format badge** on the project dashboard; compiler dropdown greys out inapplicable engines.
- **Publish & share** — compile and snapshot to `/p/:token` with three independent access tiers (project members / any logged-in user / public). HTML/RevealJS decks are served live; PDFs are embedded inline. A **Present** toolbar button links directly to the published deck.
- **RevealJS thumbnails** — the first slide of a presentation is rendered as a preview card in the project list.
- **Quarto Python cells** — optional per-project virtual environment built from `requirements.txt`, so Python code chunks execute during render.
- **Visual formatting toolbar** — bold, italic, headings and inline code shortcuts for Quarto (`.qmd`) and Typst (`.typ`) files, in addition to Overleaf's existing LaTeX toolbar.
- **Lumière theme** — card-based project dashboard with PDF/slide thumbnails, a teal gradient identity, dark editor chrome, and an XS compact list view.
- **i18n** — French, German, Italian and Spanish UI translations.
- **Auto-compile** — preview refreshes automatically after you stop typing.

---

## Releases

### Alpha 1

The initial public release. Established Verso as an Overleaf fork with first-class
multi-language support:

- Quarto (`.qmd`) and Typst (`.typ`) compilers running alongside TeX Live,
  dispatched automatically by root file extension — no per-project configuration.
- Language-aware editor for Quarto: Markdown highlighting, code-chunk completions
  (`{python}`, `{r}`, `{julia}`, `{ojs}`…), callout and fenced-div completions,
  cross-reference completions (`@fig-`, `@tbl-`, `@sec-`…).
- Language-aware editor for Typst: syntax highlighting and completions for
  functions, imports, math and markup.
- Document outline panel for all three languages (LaTeX `\section`, Quarto `#`,
  Typst `=`).
- Format badge on the project dashboard; compiler selector greys out inapplicable
  engines for the current root file.
- Publish & share compiled output — HTML/RevealJS decks and PDFs hosted at
  `/p/:token` with tiered access links (project / logged-in / public), each
  independently resettable.
- Quarto Python code-cell execution via an optional per-project `requirements.txt`
  virtual environment.
- Verso branding: name, logo and Kubernetes production deploy workflow.

### Alpha 2

Refinements to the Typst editor and the format badge system:

- **Quarto format sub-types** — the project badge now distinguishes *Quarto PDF*
  from *Quarto Slides*, reading the frontmatter `format:` to pick the right label.
- **Python packages for collaborators** — Quarto Python package installation
  extended to all users who have write access to the project, not only the owner.
- **Typst syntax highlighting overhaul** — complete grammar rewrite covering:
  function calls and named argument keys, multi-line display math, `#{…}` code
  blocks, content blocks, `show`-rule bodies, `let`-value bindings, and keyword
  vs identifier disambiguation.
- **Typst visual formatting** — bold and italic toolbar buttons and keyboard
  shortcuts (`Ctrl+B`, `Ctrl+I`), plus underline, small-caps and hyperlink
  buttons, matching the Quarto and LaTeX toolbar experience.

### Alpha 3

- **Lumière theme** — redesigned project dashboard with a card grid, PDF/slide
  thumbnails, parallax hover effects, a teal gradient identity and a dark editor
  chrome. Includes an XS compact list view and a tile zoom slider.
- **Full i18n** — French, German, Italian and Spanish translations covering the
  complete UI (login, dashboard, editor, settings, emails).
- **Visual editors for Quarto and Typst** — bold, italic, headings and inline code
  shortcuts in the toolbar for `.qmd` and `.typ` files.
- **Top/bottom split view** — new editor layout that stacks the source editor
  above the PDF preview vertically, in addition to the existing side-by-side mode.
- **Bidirectional format export** — LaTeX projects can be converted to Typst and
  Typst projects to LaTeX via pandoc. Available from the File menu in the editor.
- **Mobile layout** — project dashboard, search bar, footer and editor all
  adapted for phone screen sizes.

---

## Known issues

- **Large file upload timeouts** — uploads of large files on slow connections
  can time out at the proxy layer. A streaming response fix is pending.

---

## Security model — trusted environments only

> [!CAUTION]
> Verso is designed for **closed groups of trusted users** (a lab, a class, a
> small team). All three compilers can execute arbitrary code on the server:
>
> - LaTeX with shell-escape enabled can run system commands.
> - Quarto Python cells execute Python code directly.
> - Typst's scripting layer is sandboxed by design, but runs server-side.
>
> There is **no per-project sandbox or resource isolation** beyond what the
> operating system provides. Exposing Verso to the public internet with open
> registration is not recommended. If you need to host a collaborative
> LaTeX editor for untrusted users or at scale, look at
> [Overleaf's non-Community offerings](https://www.overleaf.com/for/enterprises),
> which include proper sandboxing and enterprise access controls.

---

## Quick start

### With Docker

```bash
docker run -d \
  -p 80:80 \
  -v ~/verso_data:/var/lib/overleaf \
  --name verso \
  registry.alocoq.fr/verso:latest
```

Open `http://localhost`, then visit `/launchpad` on first run to create the admin
account.

### Build from source

```bash
cd server-ce
make build-base        # base OS image: system deps, Quarto, Typst, TeX Live
make build-community   # application image: Node services + compiled frontend
```

| File | Purpose |
|------|---------|
| `server-ce/Dockerfile-base` | Base image — system deps, Quarto (with Typst) and TeX Live |
| `server-ce/Dockerfile` | App image — Node services and the compiled React frontend |

---

## Architecture

Verso is a microservices monorepo (Yarn workspaces). All services run inside a
single container managed by `runit`, with `nginx` as the front router.

```
browser ──→ nginx:80
              ├── / ──────────────────→ web:4000         (main app, React UI)
              ├── /socket.io ──────────→ real-time:3026   (WebSocket, OT engine)
              ├── /p/:token ───────────→ web              (published output)
              └── /project/*/output/* → clsi-nginx:8080   (compiled output files)

web → document-updater → Redis pub/sub → real-time → browser
web → CLSI (quarto render / latexmk / typst) → output files → nginx → browser
```

| Service | Role |
|---------|------|
| `web` | HTTP API, React frontend, auth, project & sharing management |
| `real-time` | WebSocket layer, live cursors and edit sync |
| `document-updater` | Operational transformation, Redis pub/sub |
| `clsi` | Compiler — runs `quarto render`, `latexmk` or `typst` and serves output |
| `docstore` | Document text storage (MongoDB) |
| `filestore` | Binary file storage (S3 or local) |
| `project-history` | Change history and version tracking |

---

## Environment variables

Verso inherits all of Overleaf's environment variables (prefixed `OVERLEAF_`).
The most commonly needed:

| Variable | Default | Description |
|----------|---------|-------------|
| `OVERLEAF_APP_NAME` | `Verso` | Name shown in the UI |
| `OVERLEAF_NAV_TITLE` | — | Instance name/version shown in the top bar |
| `OVERLEAF_MONGO_URL` | `mongodb://mongo/sharelatex` | MongoDB connection string |
| `OVERLEAF_REDIS_HOST` | `localhost` | Redis host |
| `OVERLEAF_SITE_URL` | — | Public URL (used in emails and published links) |
| `OVERLEAF_SITE_LANGUAGE` | `en` | Default UI language (e.g. `fr`) |
| `OVERLEAF_ENABLE_PROJECT_PYTHON_VENV` | `false` | Allow Quarto Python cells to use a project `requirements.txt` |
| `OVERLEAF_ADMIN_EMAIL` | — | Email shown on the launchpad for the first admin account |

See the [Overleaf Server documentation](https://github.com/overleaf/overleaf/wiki)
for the full list.

---

## Relation to Overleaf

Verso is a fork of [Overleaf Community Edition](https://github.com/overleaf/overleaf).
Everything that Overleaf CE provides — real-time collaboration, operational-transformation
history, auth, project management, binary file storage — is inherited unchanged. The
Verso-specific additions are listed in the Features section and tracked across releases above.

Verso is not affiliated with Overleaf Ltd.

---

## Supporting the ecosystem

Verso is not accepting contributions or donations at this time. If you find it
useful and want to support the broader ecosystem it builds on:

- **Support Overleaf** — Verso is built on Overleaf's infrastructure. The best
  way to support their work is to use or subscribe to
  [Overleaf](https://www.overleaf.com) and encourage your institution to do the
  same.
- **Support Typst** — [Typst GmbH](https://typst.app) is the company behind the
  Typst compiler. Using Typst.app or sponsoring the
  [Typst project on GitHub](https://github.com/typst/typst) helps sustain the
  language itself.
- **Support RevealJS** — Verso uses [Reveal.js](https://revealjs.com) for
  HTML presentations. Consider sponsoring the
  [RevealJS project on GitHub](https://github.com/hakimel/reveal.js).

---

## License

GNU Affero General Public License v3 — see [LICENSE](LICENSE).

Copyright © Overleaf, 2014–2026 (original code).  
Verso modifications © Aloïs Coquillard, 2026.