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 Quarto, LaTeX and Typst — documents and presentations.**

Verso is a fork of [Overleaf](https://github.com/overleaf/overleaf) that adds
first-class [Quarto](https://quarto.org) and [Typst](https://typst.app) support
alongside Overleaf's LaTeX toolchain. It keeps Overleaf's real-time
collaboration infrastructure and runs **three compilers side by side**, chosen
automatically from the root file's extension:

| Root file | Compiler | Typical output |
|-----------|----------|----------------|
| `.qmd`    | Quarto   | PDF (via Typst or LaTeX), or an HTML/RevealJS deck |
| `.tex`    | `latexmk` / TeX Live | PDF |
| `.typ`    | Typst    | PDF |

All three coexist on one server; no per-project configuration is required to
pick the engine.

---

## Features

- **Real-time collaboration** — multiple people editing the same file at once,
  powered by Overleaf's operational-transformation engine, with live cursors
  and full project history.
- **Three compilers, auto-dispatched** — Quarto, LaTeX and Typst projects live
  side by side; the runner is selected from the root file's extension.
- **Language-aware editor for all three**:
  - *LaTeX* — syntax highlighting, command/environment/reference autocomplete,
    linting (inherited from Overleaf).
  - *Quarto (`.qmd`)* — Markdown highlighting plus Quarto-aware completions:
    code chunks (```` ```{python} ````, `{r}`, `{julia}`, `{ojs}`…), callouts
    and fenced divs (`::: {.callout-note}`, columns, tabsets) and
    cross-references (`@fig-`, `@tbl-`, `@sec-`, `@eq-`).
  - *Typst (`.typ`)* — syntax highlighting and completions for the common
    functions and markup (`#import`, `#let`, `#set`, `#show`, `#figure`,
    `#table`, `#cite`, …).
- **Document outline** — section headings are extracted into the sidebar
  outline panel for LaTeX, Quarto (`#`, `##`, …) and Typst (`=`, `==`, …).
- **Format at a glance** — the project dashboard shows a per-project format
  badge (Quarto / Typst / LaTeX), and the compiler dropdown greys out engines
  that don't apply to the current root file.
- **Publish & share compiled output** — publish the compiled result as a
  standalone page at `/p/:token`, with three independent access tiers (project
  members / any logged-in user / public). Works for both HTML/RevealJS decks
  (served live) and PDFs (embedded inline). HTML decks also get a one-click
  **Present** button in the toolbar.
- **Quarto Python cells** — optional per-project virtual environment built from
  the project's `requirements.txt`, so Python code chunks run during render
  (gated to the project owner and invited collaborators).
- **Auto-compile** — the preview refreshes automatically shortly after you stop
  typing.

## Output formats

In the YAML frontmatter of a `.qmd` file:

```yaml
format: typst     # → PDF preview, rendered via Typst (no LaTeX required)
format: pdf       # → PDF preview, rendered via LaTeX
format: revealjs  # → interactive HTML slideshow preview
format: html      # → a static HTML page
```

Typst ships inside Quarto, so `format: typst` needs no separate installation.

> **Note on display math**: keep `$$ … $$` blocks on a single line. Multi-line
> display-math blocks can trigger YAML parse errors in some Quarto versions.

## 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` in your browser, then visit `/launchpad` on first run to
create the admin account.

### Build from source

```bash
# Build the base image (system deps + Quarto + TeX Live)
cd server-ce
make build-base

# Build the application image
make build-community
```

| File | Purpose |
|------|---------|
| `server-ce/Dockerfile-base` | Base OS image — system deps, Quarto (with Typst) and a TeX Live (`latexmk`) toolchain |
| `server-ce/Dockerfile` | Application image — Node services and the compiled 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` (`.qmd`), `latexmk` (`.tex`) or `typst` (`.typ`) and serves output |
| `docstore` | Document text storage (MongoDB) |
| `filestore` | Binary file storage (S3 or local) |
| `project-history` | Change history and version tracking |

## Writing documents

### Quarto (`main.qmd`)

```markdown
---
title: My Presentation
author: Your Name
date: today
format: revealjs
---

## Slide one

Write **Markdown** here.

## Mathematics

$$\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}$$
```

Switch `format: revealjs` to `format: typst` (or `pdf`) for a PDF preview.

### LaTeX (`main.tex`)

LaTeX works exactly as in Overleaf: a project whose root file is a `.tex` file
compiles with `latexmk`/TeX Live, no setting required. The **Example LaTeX
project** in the *New project* menu is a ready-made starting point.

> The bundled TeX Live is a minimal install. Documents that need extra packages
> may not build out of the box — see `server-ce/Dockerfile-base` for how to
> switch to a fuller TeX Live scheme.

### Typst (`main.typ`)

A project whose root file is a `.typ` file compiles directly to PDF with
[Typst](https://typst.app) — fast, modern markup with a real scripting
language. Verso drives the Typst bundled with Quarto, so no extra install is
needed. Use the **Blank Typst project** entry in the *New project* menu to get
started.

## Publishing compiled output

From **Share → Publish**, Verso compiles the project and snapshots the result to
a standalone page at `/p/:token`:

- **HTML / RevealJS** decks are served as a live page (the **Present** toolbar
  button is a one-click shortcut to this).
- **PDF** output is embedded inline; the raw file stays reachable at
  `/p/:token/output.pdf`.

Three stable links are issued, one per access tier — project members, any
logged-in user, or anyone — and each can be copied or independently reset.

## 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 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).
The main additions on top of upstream are:

- Quarto and Typst compilers running alongside LaTeX, dispatched by the root
  file's extension.
- Editor language support (highlighting, autocomplete, outline) for Quarto and
  Typst.
- A per-project format badge on the dashboard and a root-file-aware compiler
  selector.
- Publishing/sharing of compiled output (HTML decks and PDFs) via `/p/:token`
  with tiered access links, and a toolbar **Present** shortcut.
- Optional per-project Python virtual environments for Quarto code execution.
- Verso branding (name, logo, palette, loading animation).

All other infrastructure — real-time collaboration, history, auth, file
storage, project management — is unchanged from Overleaf.

## Contributing

Contributions are welcome — open an issue or pull request on the
[Verso repository](https://git.alocoq.fr/alois/verso). The upstream Overleaf
contribution guidelines are in [CONTRIBUTING.md](CONTRIBUTING.md).

## License

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

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