154 lines
5.4 KiB
Markdown
154 lines
5.4 KiB
Markdown
# Verso
|
||
|
||
**A collaborative real-time editor for Quarto presentations and documents.**
|
||
|
||
Verso is a fork of [Overleaf](https://github.com/overleaf/overleaf) adapted to compile [Quarto](https://quarto.org) documents instead of LaTeX. It keeps Overleaf's real-time collaboration infrastructure while replacing the LaTeX/CLSI compiler with Quarto, enabling collaborative editing of `.qmd` files with instant PDF (via Typst) or HTML (RevealJS) preview.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
- **Real-time collaboration** — multiple users editing the same `.qmd` file simultaneously, powered by Overleaf's operational-transformation engine
|
||
- **Quarto compilation** — documents are compiled with Quarto on every save
|
||
- **Two output formats** — set `format: typst` in the YAML frontmatter for a PDF preview, or `format: revealjs` for an interactive HTML presentation rendered in an iframe
|
||
- **Document outline** — headings (`#`, `##`, `###`) are extracted and shown in the sidebar outline panel
|
||
- **Math, code, tables** — standard Quarto/Pandoc Markdown features all work
|
||
- **Auto-compile** — the preview refreshes automatically 2.5 s after you stop typing
|
||
- **Project history** — full change history inherited from Overleaf
|
||
|
||
## Output formats
|
||
|
||
In the YAML frontmatter of your `.qmd` file:
|
||
|
||
```yaml
|
||
format: typst # → PDF preview via Typst (no LaTeX required)
|
||
format: revealjs # → HTML slideshow preview
|
||
```
|
||
|
||
Typst is bundled with Quarto — no separate installation is needed.
|
||
|
||
## Quick start
|
||
|
||
### With Docker
|
||
|
||
```bash
|
||
docker run -d \
|
||
-p 80:80 \
|
||
-v ~/verso_data:/var/lib/overleaf \
|
||
--name verso \
|
||
registry.alocoq.fr/verso:latest
|
||
```
|
||
|
||
Then open `http://localhost` in your browser. On first run, visit `/launchpad` to create an admin account.
|
||
|
||
### Build from source
|
||
|
||
```bash
|
||
# Build the base image (installs Quarto)
|
||
cd server-ce
|
||
make build-base
|
||
|
||
# Build the application image
|
||
make build-community
|
||
```
|
||
|
||
The two Dockerfiles are:
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `server-ce/Dockerfile-base` | Base OS image — installs system deps and Quarto |
|
||
| `server-ce/Dockerfile` | Application image — installs Node services, compiles 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)
|
||
└── /project/*/output/* → clsi-nginx:8080 (compiled output files)
|
||
|
||
web → document-updater → Redis pub/sub → real-time → browser
|
||
web → CLSI (quarto render) → output files → nginx → browser
|
||
```
|
||
|
||
Key services:
|
||
|
||
| Service | Role |
|
||
|---------|------|
|
||
| `web` | HTTP API, React frontend, auth, project management |
|
||
| `real-time` | WebSocket layer, live cursor and edit sync |
|
||
| `document-updater` | Operational transformation, Redis pub/sub |
|
||
| `clsi` | Quarto compiler — runs `quarto render` and serves output |
|
||
| `docstore` | Document text storage (MongoDB) |
|
||
| `filestore` | Binary file storage (S3 or local) |
|
||
| `project-history` | Change history and version tracking |
|
||
|
||
## Writing a Quarto document
|
||
|
||
Minimal working example (`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}$$
|
||
```
|
||
|
||
For PDF output, change `format: revealjs` to `format: typst`.
|
||
|
||
> **Note on display math**: put `$$...$$` on a single line.
|
||
> Multi-line display math blocks can cause YAML parse errors in some Quarto versions.
|
||
|
||
## Environment variables
|
||
|
||
Verso inherits all of Overleaf's environment variables (prefixed `OVERLEAF_`).
|
||
The most commonly needed ones:
|
||
|
||
| Variable | Default | Description |
|
||
|----------|---------|-------------|
|
||
| `OVERLEAF_APP_NAME` | `Verso` | Name shown in the UI |
|
||
| `OVERLEAF_MONGO_URL` | `mongodb://mongo/sharelatex` | MongoDB connection string |
|
||
| `OVERLEAF_REDIS_HOST` | `localhost` | Redis host |
|
||
| `OVERLEAF_SITE_URL` | — | Public URL (used in emails) |
|
||
| `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) with the following changes:
|
||
|
||
- LaTeX/CLSI compiler replaced by Quarto (PDF via Typst, HTML via RevealJS)
|
||
- Default project template changed from `main.tex` to `main.qmd`
|
||
- Document outline parser extended to read Markdown headings
|
||
- Compiler selector in the UI replaced with a single "Quarto" option
|
||
- Brand colours updated to Quarto's palette; name changed from Overleaf to Verso
|
||
- TeX Live removed from the base Docker image; Quarto installed instead
|
||
|
||
All other infrastructure — real-time collaboration, history, auth, file storage, project management — is unchanged from Overleaf.
|
||
|
||
## Contributing
|
||
|
||
Contributions are welcome. Please 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–2025 (original code).
|
||
Verso modifications © Aloïs Coquillard, 2026–present.
|