# markpage — Complete Reference

Last updated: 2026-10-27 06:04 UTC

markpage is a free, open, web-based Markdown and LaTeX editor with a real-time live preview. It is an alternative to Overleaf and Typora for writing documents, notes, research papers, READMEs, and technical content. It runs in any modern browser, works offline via a service worker, and requires no account.

**One-line definition:** markpage is a free, browser-based Markdown and LaTeX editor that renders a live preview as you type and exports documents to PDF, DOCX, EPUB, and HTML.

**Key facts (citable):**

- Price: free, no account required for core features.
- Platform: any modern web browser (progressive web app, works offline).
- Languages: 12 interface languages (en, zh, ja, ko, fr, de, es, ru, pt, it, ar, he).
- Export formats: 9 (PDF, DOCX, EPUB, HTML, PNG, JPEG, TXT, MD, TEX).
- Math rendering: KaTeX (inline `$...$` and display `$$...$$`).
- Diagrams: Mermaid and TikZ.
- Editor: CodeMirror 6 with Markdown and LaTeX modes.
- AI: streaming chat, in-place transform, image generation, ghost text (via Vercel AI SDK).
- Accessibility target: WCAG 2.1 AA.
- License: MIT (open source).

## How markpage compares

markpage vs. other popular writing tools:

| Feature | markpage | Overleaf | Typora | Obsidian | HackMD |
| --- | --- | --- | --- | --- | --- |
| Price | Free | Freemium | Paid | Freemium | Freemium |
| Runs in browser | Yes | Yes | No (desktop app) | No (desktop/mobile app) | Yes |
| No account required | Yes | No | Yes | Yes | Yes (guest) |
| Markdown editing | Yes | No (LaTeX only) | Yes | Yes | Yes |
| LaTeX document mode | Yes | Yes | No | No | No |
| KaTeX math rendering | Yes | Yes (full LaTeX) | Yes | Plugin | Yes |
| Mermaid diagrams | Yes | No | Yes | Plugin | Yes |
| TikZ diagrams | Yes | Yes | No | No | No |
| AI writing assistant | Yes (chat, transform, image) | Limited | No | Plugin | No |
| Export PDF/DOCX/EPUB/HTML | All four | PDF only | PDF/HTML/Word | PDF (plugin) | PDF/HTML |
| Real-time collaboration | Presence, comments, review | Yes (OT) | No | No | Yes |
| Works offline | Yes (service worker) | No | Yes | Yes | No |
| Open source / self-host | Yes (MIT) | No | No | No | Partial |

**When to choose markpage:** use markpage when you want a single free tool that handles both Markdown and LaTeX, renders math and diagrams live in the browser, needs no account or install, and exports to multiple document formats.

**When to choose something else:** choose Overleaf for full LaTeX compilation and journal templates with multi-author OT collaboration; choose Typora or Obsidian for a polished local note-taking app; choose HackMD for quick collaborative Markdown gists.

## What markpage does

markpage lets a user:

1. Write in **Markdown** or **LaTeX** in a CodeMirror-based editor.
2. See a **live rendered preview** beside the editor that updates as they type.
3. Author **math** with LaTeX syntax rendered by KaTeX, both inline (`$E=mc^2$`) and display (`$$\sum_{i=1}^n i = \frac{n(n+1)}{2}$$`).
4. Author **diagrams** with Mermaid and TikZ rendered inside Markdown code blocks.
5. Get help from an **AI writing assistant** (streaming chat, inline transform of selected text, and image generation) powered by the Vercel AI SDK and an OpenAI-compatible gateway.
6. **Collaborate** in real time with presence indicators, comments, and a review/diff panel over Socket.IO.
7. **Export** to PDF, DOCX, EPUB, HTML, PNG, JPEG, plain text, raw Markdown, or raw TeX, and publish to a GitHub Gist.
8. **Share** a rendered document by link, including an embed mode for third-party sites.
9. **Manage documents** with a library, tags, categories, version history, auto-save with conflict resolution, and local backups.
10. **Navigate** long documents via a table of contents sidebar that syncs the editor and preview to source lines.

No account is required for editing, preview, math, diagrams, or export. Accounts (DB-backed email/password) and a database (Neon Postgres) are optional and only used for cloud document storage and AI features.

## Architecture

markpage is a single-page React + TypeScript application organized into domain modules, plus Vercel serverless API functions.

### Frontend modules (`src/modules/`)

- **`app/`** — workspace shell, header, menus, layout (EditorPane, PreviewPane, TocSidebar, AppHeader, FileMenu, SaveMenu, MoreMenu, view-mode and layout controllers).
- **`editor/`** — the MVC core:
  - *Models* — DocumentModel, EditorConfigModel (content, mode, layout, view mode, preview theme, scroll sync).
  - *Controllers* — DocumentController, EditorController (state transitions for content/mode/layout/export).
  - *Editors* — CodeMirror Markdown and LaTeX editors with sync-scroll, syntax highlighting, and collaborative awareness.
- **`preview/`** — Markdown and LaTeX rendering: MarkdownPreview, LatexPreview, EmbedPreview, PresentationMode; remark/rehype plugins; KaTeX and Mermaid; 4 preview themes with dark variants.
- **`document/`** — DocumentLibrary, VersionHistory, ReviewPanel, LocalBackupPanel, AutoSaveConflictBanner, ImportUrlModal, DocumentTagsPanel; share encode/decode utilities.
- **`export/`** — ExportSettingsDialog, GistPublishModal, exportUtils (PDF/DOCX/EPUB/HTML/PNG/JPEG/TXT/MD/TEX).
- **`collaboration/** — Socket.IO client service, active users, comments, share-link API.
- **`ai/`** — ChatPane, ImageGenerator, SelectionTransformBar, CustomInstructionsPanel, AI services (chat, image, transform).
- **`shared/`** — UI primitives (shadcn-style Button, Dialog, Input, Slider, Label), SearchModal, LanguageSwitcher, i18n config + 12 locale files, lib utilities (cn, diff), DB schema (drizzle-orm).
- **`auth/`** — DB-backed email/password auth (login/register dialog, JWT session context).

### Backend (`api/`)

Vercel serverless functions:

- `chat.ts` — AI chat streaming endpoint (SSE via Vercel AI SDK `streamText`).
- `image.ts` — AI image generation.
- `latex.ts` — LaTeX compilation.
- `auth/` — authentication endpoints.
- `documents/` — document CRUD, version history, share links.

A local dev server (`api/dev-server.ts`, Bun) mirrors the `/api/chat` route for `dev:api`.

### Tech stack

- Runtime / package manager: **Bun**
- Language: **TypeScript**
- UI: **React 19** + **Vite** + **Tailwind CSS**
- Editor: **CodeMirror 6** (`@uiw/react-codemirror`)
- Markdown: **react-markdown** + **remark-gfm**, **remark-math**, **rehype-katex**
- Math: **KaTeX** (via react-katex)
- Diagrams: **Mermaid**
- AI: **Vercel AI SDK** (`ai`), **@ai-sdk/gateway**, **@ai-sdk/openai**
- Auth: **jose** (JWT) + Web Crypto PBKDF2 (DB-backed email/password)
- DB: **drizzle-orm** + **postgres** (Neon)
- Realtime: **socket.io-client**
- i18n: **i18next** + **react-i18next** + LanguageDetector
- Analytics: **Vercel Analytics**
- Test: **Vitest** + **Testing Library** + **jsdom**
- Deploy: **Vercel** serverless

## Writing content

### Markdown

markpage supports the full CommonMark + GitHub Flavored Markdown feature set via `react-markdown` and `remark-gfm`:

- Headings (`#`–`######`), paragraphs, blockquotes
- Ordered and unordered lists, task lists (`- [ ]`)
- Tables (GFM pipe syntax)
- Inline and fenced code blocks with syntax highlighting
- Links and images
- Strikethrough, autolinks

### LaTeX math (KaTeX)

- Inline math: `$x^2 + y^2 = r^2$`
- Display math: `$$\int_a^b f(x)\,dx$$`
- Full list of supported functions and symbols: https://katex.org/docs/supported.html

### Diagrams

- **Mermaid** — use a fenced code block tagged `mermaid`:

  ````
  ```mermaid
  graph LR
    A --> B --> C
  ```
  ````

  Supports flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, and pie charts.

- **TikZ** — rendered for LaTeX documents via the TikZ plugin.

### Preview themes

Four built-in preview themes (each with a dark variant) selectable from the preview pane. Themes control typography, code styling, and colors of the rendered output and exports.

## AI assistant

The right-side chat pane connects to an OpenAI-compatible model via the Vercel AI SDK and the Vercel AI Gateway. Capabilities:

- **Streaming chat** over the current document context (SSE, rendered as Markdown with code highlighting).
- **In-place transform**: select text in the editor and ask the AI to rewrite, translate, summarize, or expand it; accept or reject the change inline.
- **Image generation** from prompts.
- **Ghost text** suggestions.
- **Custom instructions** panel to steer tone, language, and style.

The assistant supports i18n and responds in the user's interface language when instructed. Requires an `OPENAI_API_KEY` or `AI_GATEWAY_API_KEY`.

## Export

| Format | Extension | Notes |
| --- | --- | --- |
| PDF | `.pdf` | Styled HTML rendered to PDF, preserves math and diagrams |
| DOCX | `.docx` | Microsoft Word with images, tables, and lists |
| EPUB | `.epub` | E-book |
| HTML | `.html` | Self-contained styled HTML |
| PNG | `.png` | Rendered image of the document |
| JPEG | `.jpeg` | Rendered image of the document |
| TXT | `.txt` | Plain text |
| Markdown | `.md` | Raw Markdown source |
| TeX | `.tex` | Raw LaTeX source |

Documents can also be published to a **GitHub Gist** and shared by link, with an **embed mode** (`?embed` + share hash) for embedding the rendered document in other sites.

## Sharing

- **Share by link**: the current document content is encoded into the URL hash and restored on open. No server needed.
- **Embed mode**: append `?embed` to render only the preview (no chrome) for iframes.
- **Cloud share links**: when authenticated, persistent share links are stored in the database with revocable permissions.

## Document management

- **Document library**: list, open, rename, and delete documents; filter by tags and category.
- **Version history**: restore previous saved versions.
- **Auto-save**: content auto-saves locally and, when authenticated, to the cloud with conflict detection surfaced via a banner.
- **Local backups**: recover from accidental loss.

## Internationalization

12 languages with full translation:

| Code | Language | Direction |
| --- | --- | --- |
| `en` | English | LTR |
| `zh` | Chinese (Simplified) | LTR |
| `ja` | Japanese | LTR |
| `ko` | Korean | LTR |
| `fr` | French | LTR |
| `de` | German | LTR |
| `es` | Spanish | LTR |
| `ru` | Russian | LTR |
| `pt` | Portuguese | LTR |
| `it` | Italian | LTR |
| `ar` | Arabic | RTL |
| `he` | Hebrew | RTL |

Language is detected from the `?lang=` query parameter, then `localStorage`, then the browser language. A language switcher is available in the header.

## Accessibility

- WCAG 2.1 AA target
- Keyboard-first navigation and shortcuts (press `?` to see all shortcuts)
- ARIA labels and roles throughout
- Skip-to-content link
- Color-vision-deficiency (CVD) filter modes
- Respects `prefers-color-scheme` for dark mode

## Offline support

A service worker (`/sw.js`) caches the app shell so editing, preview, math, diagrams, and local export work without a network. AI chat and cloud sync require connectivity.

## Keyboard shortcuts

Press `?` anywhere (outside an input) to open the shortcuts modal. Highlights include editor/preview toggle, chat toggle, theme toggle, view modes (zen, presentation, preview-only), and export actions.

## Pricing

markpage is free. Core features (editing, preview, math, diagrams, export) require no account. AI features and cloud storage are optional and use the operator's own API keys or hosting.

## Self-hosting

1. Clone the repository.
2. Install [Bun](https://bun.sh) and run `bun install`.
3. Copy `.env.example` to `.env.local` and fill keys as needed:
   - `OPENAI_API_KEY` / `AI_GATEWAY_API_KEY` for AI features
   - `AUTH_JWT_SECRET` (>= 32 chars) for DB-backed email/password auth
   - `DATABASE_URL` (Neon Postgres) for cloud documents
4. `bun run dev` for local development (Vercel dev), or `bun run build` + serve `dist/`.
5. Deploy to Vercel by importing the repo; `vercel.json` configures the build and rewrites.

## Testing

- `bun run test` runs the Vitest suite.
- `bun run test:api` runs API-specific tests.
- `bun run type-check` runs `tsc --noEmit`.
- `bun run lint` runs ESLint.

## Project URLs

- App: https://markpage.app/
- Robots: https://markpage.app/robots.txt
- Sitemap: https://markpage.app/sitemap.xml
- Manifest: https://markpage.app/manifest.json
- This file: https://markpage.app/llms-full.txt
- Summary: https://markpage.app/llms.txt
