diff --git a/README.md b/README.md index 38dfd01185..1239d17d5f 100644 --- a/README.md +++ b/README.md @@ -2,73 +2,148 @@ Verso

-**A collaborative, real-time editor for Quarto, LaTeX and Typst — documents and presentations.** +**A collaborative, real-time editor for LaTeX, Quarto and Typst — self-hosted.** -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 | +## What is Verso? -All three coexist on one server; no per-project configuration is required to -pick the engine. +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. --- ## 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. +- **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. -## Output formats +--- -In the YAML frontmatter of a `.qmd` file: +## Releases -```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 -``` +### Alpha 1 -Typst ships inside Quarto, so `format: typst` needs no separate installation. +The initial public release. Established Verso as an Overleaf fork with first-class +multi-language support: -> **Note on display math**: keep `$$ … $$` blocks on a single line. Multi-line -> display-math blocks can trigger YAML parse errors in some Quarto versions. +- 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 *(in progress)* + +- **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. +- **RevealJS thumbnails** — first-slide PNG preview rendered in project cards. +- **Upload reliability** — streaming response fix so large file uploads on slow + connections no longer time out at the proxy layer. + +--- ## Quick start @@ -82,24 +157,23 @@ docker run -d \ registry.alocoq.fr/verso:latest ``` -Open `http://localhost` in your browser, then visit `/launchpad` on first run to -create the admin account. +Open `http://localhost`, 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 +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 OS image — system deps, Quarto (with Typst) and a TeX Live (`latexmk`) toolchain | -| `server-ce/Dockerfile` | Application image — Node services and the compiled frontend | +| `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 @@ -108,10 +182,10 @@ 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: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 @@ -122,64 +196,12 @@ web → CLSI (quarto render / latexmk / typst) → output files → nginx → br | `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 | +| `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 | -## 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 @@ -195,39 +217,35 @@ The most commonly needed: | `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 | +| `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). -The main additions on top of upstream are: +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. -- 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). +Verso is not affiliated with Overleaf Ltd. -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 +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). +Copyright © Overleaf, 2014–2026 (original code). Verso modifications © Aloïs Coquillard, 2026.