README.md

---
title: Research Article Template Editor
emoji: ✏️
colorFrom: purple
colorTo: blue
sdk: docker
app_port: 8080
pinned: false
hf_oauth: true
hf_oauth_scopes:
  - manage-repos
  - inference-api
---

# Research Article Template Editor

A collaborative, real-time editor for web-native scientific articles. It lets multiple authors co-write a paper with rich text, math, citations, figures and interactive D3 embeds, then publishes the result as a static HTML page (or a PDF) aligned with the [research-article-template](https://github.com/huggingface/research-article-template).

## What it gives you

- **Real-time collaboration** over WebSocket (Y.js + Hocuspocus), with visible cursors and per-user selection colors
- **Rich article authoring**: headings, lists, tables, code blocks with syntax highlighting, LaTeX math (KaTeX), footnotes, sidenotes, block quotes, callouts
- **Research-specific blocks**: citations + bibliography (BibTeX), figures with captions, stacks / wide / full-width layouts, glossary terms, Mermaid/Wardley/architecture diagrams
- **Interactive D3 embeds** authored inline: each embed is a self-contained HTML file the editor can generate and iterate on via an **AI-assisted "embed studio"**
- **Comments & discussion** anchored on any selection
- **Slash menu** (`/`) and drag/drop block handles, in the spirit of Notion
- **Click-to-edit frontmatter**: title, subtitle, authors, affiliations, links, banner color
- **Publishing pipeline**: one-click export to a standalone static HTML bundle, plus PDF generation (Puppeteer) and an `llms.txt` Markdown twin for LLM agents/crawlers (served at `/llms.txt`, advertised in `/robots.txt`)
- **Persistence**:
  - Local mode: documents stored on disk under `DATA_DIR`
  - HF mode: documents pushed/pulled from a Hugging Face dataset via OAuth
- **Dark mode**, responsive layout (TOC drawer on mobile), live table of contents with scroll-spy
- **AI chat side-panel** that can edit the article via structured tool calls (agent loop over the current TipTap doc)

## Stack

| Layer | Tech |
|---|---|
| Editor | React 18, TypeScript, TipTap v3, ProseMirror |
| Collaboration | Y.js, Hocuspocus (WebSocket), y-tiptap |
| Backend | Node.js, Express, Vite (dev proxy), Hocuspocus server |
| Publishing | Custom TipTap-JSON → HTML renderer, Puppeteer for PDF |
| AI | Vercel AI SDK v6 (`ai`, `@ai-sdk/react`) → Hugging Face Inference Providers (OpenAI-compatible router) |
| Styling | Plain CSS with custom properties, no framework |
| Storage | Local FS or Hugging Face datasets (via `@huggingface/hub`) |
| Container | Single-image Docker build, runs on port 8080 |

Around **3.6k LOC backend** and **9.5k LOC frontend** (TypeScript/TSX, excluding generated code).

## Repo layout

```
collab-editor/
├── backend/              # Express + Hocuspocus server, publisher, AI agent routes
│   └── src/
│       ├── server.ts             # Entry point
│       ├── create-app.ts         # App factory (routes, middleware, Hocuspocus)
│       ├── publisher/            # TipTap-JSON → HTML + PDF
│       ├── agent/                # LLM agent (tool calls over the doc)
│       ├── shared/               # Component defs shared with the frontend
│       └── hf-storage.ts         # HF dataset sync
├── frontend/             # Vite + React + TipTap editor
│   └── src/
│       ├── App.tsx               # Top-level shell
│       ├── editor/               # TipTap editor + extensions + components
│       ├── components/           # Shared UI pieces (TOC, Chat, Dialog, ...)
│       ├── hooks/                # React hooks (agent chat, selection, ...)
│       ├── styles/               # CSS layers (see docs/ARCHITECTURE.md)
│       └── utils/
├── docs/
│   ├── ARCHITECTURE.md           # Deep dive on layers, data flow, CSS
│   ├── SPECIFICATION.md          # Feature spec and contracts
│   ├── TESTS.md                  # Testing strategy
│   └── embed-studio.md           # How the AI-authored embeds pipeline works
└── Dockerfile            # Production multi-stage build
```

See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for a diagram and the full tour.

## Getting started

### Prerequisites

- Node.js 20+
- A Hugging Face token with the `Make calls to Inference Providers` permission for the AI features (embed studio, chat agent). Generate one at https://huggingface.co/settings/tokens. On a HF Space the logged-in user's OAuth token is used instead - no manual setup needed.
- A Hugging Face OAuth app (client id/secret) if you want login + HF dataset persistence

### Local development

Backend and frontend run as two separate processes in dev (Vite proxies `/api`, `/collab`, `/uploads`, `/published`, `/oauth`, `/auth` to the backend).

```bash
# terminal 1 — backend (Express + Hocuspocus on :8080)
cd backend
cp .env.example .env          # set HF_TOKEN, optional OAUTH_* and HF_DATASET_ID
npm install
npm run dev

# terminal 2 — frontend (Vite on :5678)
cd frontend
npm install
npm run dev
```

Then open http://localhost:5678. Open a second tab or browser to see collaboration in action.

### Production (Docker / HF Spaces)

The `Dockerfile` builds both frontend and backend into a single image listening on port 8080. This is the image used by the Hugging Face Space.

```bash
docker build -t collab-editor .
docker run -p 8080:8080 --env-file backend/.env collab-editor
```

Then open http://localhost:8080.

### Run your own copy on a Hugging Face Space

Want your own editor? One step:

1. **Duplicate the Space.** On https://huggingface.co/spaces/tfrere/research-article-template-editor, click `⋯ → Duplicate this Space`. Pick your namespace and visibility. HF copies the Dockerfile, the OAuth wiring and rebuilds the image automatically.

That's it. No API key to wire up. The AI features (chat agent + embed studio) call **Hugging Face Inference Providers** at `https://router.huggingface.co/v1` using the OAuth token of whoever is currently logged in. As long as your duplicated Space requests the `inference-api` scope (already declared in the README frontmatter as `hf_oauth_scopes`), every editor gets AI for free under their own Inference Providers quota.

Optional public variable: `HF_INFERENCE_MODEL` (e.g. `meta-llama/Llama-3.3-70B-Instruct`) to override the default model id. The full list of supported chat-completion models lives at https://huggingface.co/models?inference_provider=all&other=conversational.

## Scripts

### Backend (`cd backend`)

| Command | What it does |
|---|---|
| `npm run dev` | Start Express + Hocuspocus in watch mode |
| `npm run build` | Compile TypeScript to `dist/` |
| `npm start` | Run the compiled server |
| `npm run test` | Unit + integration tests (Vitest) |
| `npm run test:e2e` | End-to-end tests (Playwright) |

### Frontend (`cd frontend`)

| Command | What it does |
|---|---|
| `npm run dev` | Start Vite dev server on :5678 |
| `npm run build` | Production bundle to `dist/` |
| `npm run preview` | Preview the built bundle |
| `npm run test` | Unit tests (Vitest) |
| `npm run typecheck` | `tsc --noEmit` on the whole frontend |

## Environment variables

Copy `backend/.env.example` to `backend/.env` and fill the relevant values. Key ones:

| Variable | Purpose |
|---|---|
| `OAUTH_CLIENT_ID` / `OAUTH_CLIENT_SECRET` | HF OAuth app for user login (required to edit when running on a Space) |
| `OAUTH_SCOPES` | OAuth scopes (default `openid profile`). Add `manage-repos` for dataset persistence and `inference-api` to power the AI features with the user's token |
| `HF_TOKEN` | Server-side Hugging Face token. Used as a fallback when no user OAuth token is present (e.g. local dev). Needs the `Make calls to Inference Providers` permission to enable the chat agent + embed studio |
| `HF_INFERENCE_MODEL` | Override the default chat-completion model id (defaults to `openai/gpt-oss-120b`). Any tool-calling-capable model exposed by HF Inference Providers works |
| `HF_DATASET_ID` | Target HF dataset repo for document persistence (when not running on a Space) |
| `SPACE_ID` / `SPACE_HOST` | Auto-set by HF Spaces; drive dataset id + secure cookies in production |
| `DATA_DIR` | Where documents, uploads and published bundles are stored on disk (default: `./data`) |
| `PUBLISH_BASE_URL` | Absolute base URL used when publishing (defaults to `http://127.0.0.1:${PORT}`) |
| `ENABLE_PDF` | Set to `false` to disable Playwright-based PDF export |
| `PORT` | Server port (default 8080) |

## Testing

- **Backend unit tests**: Vitest covers the publisher (HTML renderer, frontmatter, bibliography), storage, auth utilities.
- **Backend E2E**: Playwright drives the full editor against a real backend.
- **Frontend unit tests**: Vitest covers chat persistence and a handful of utilities.
- **Type checking**: `npm run typecheck` in both workspaces.

See [`docs/TESTS.md`](docs/TESTS.md) for the current strategy and gaps.

## Known technical debt

These are tracked explicitly so new contributors don't trip on them:

- **`useEmbedChat` still lacks dedicated unit tests**; the rest of the stores (frontmatter, comments, embeds) and the agent undo batching primitive are now covered.
- **Bundle size warning**: the frontend bundle is over the 500 kB Vite warning threshold. Code-splitting the Mermaid / KaTeX / D3 stacks via dynamic imports would help.
- **`addToolOutput` typing**: the ai-sdk v6 `ChatAddToolOutputFunction` is a generic over the tool name union. We currently cast to a plain signature at the two call sites because we don't export a typed tool registry yet.
- **`backend/src/publisher/html-renderer.ts` is ~1000 LOC**: a per-node-type registry would make it more maintainable.

## License

Follow the upstream [research-article-template](https://github.com/huggingface/research-article-template) license.