# AFFiNE User Guide

## 1. Quick Start

AFFiNE is an open-source, privacy-focused workspace that combines documents, whiteboards, and databases into a single unified application. It provides local-first data ownership with optional cloud sync, real-time collaboration, and an AI-powered copilot — all in one platform.

**Key features:**

- **Page mode** — rich-text documents with blocks for paragraphs, lists, code, tables, images, bookmarks, LaTeX, callouts, and embedded documents
- **Edgeless mode** — infinite canvas whiteboard with shapes, connectors, freehand drawing, text, mind maps, and frames
- **Database views** — structured data with table, kanban, and custom property types
- **Collections** — smart document groups with filter rules and manual pinning
- **AI Copilot** — built-in AI assistant for writing, summarization, translation, and image generation
- **Real-time collaboration** — CRDT-based sync for simultaneous multi-user editing
- **Cross-platform** — web, desktop (Windows, macOS, Linux), and mobile (Android, iOS)
- **Self-hostable** — run your own AFFiNE Cloud server with Docker

**Prerequisites:** A modern web browser, or the desktop/mobile app installed.

**Get started in 30 seconds:**

1. Visit [affine.pro](https://affine.pro) and click **Get Started Free**
2. Create a workspace
3. Click **New Page** to start writing, or switch to **Edgeless** mode for whiteboarding

> [!TIP]
> For the fastest experience, download the desktop app — it works offline and syncs when connected.

**What to try next:**

- Create your first edgeless whiteboard (see Core Usage)
- Set up a database to track tasks (see Common Tasks)
- Explore the AI Copilot (see Core Usage)

---

## 2. Installation

### System Requirements

| Requirement | Minimum |
|---|---|
| **Browser** | Chrome 100+, Firefox 100+, Safari 16+, Edge 100+ |
| **Desktop** | Windows 10+, macOS 12+, Linux (AppImage/deb) |
| **Mobile** | Android 10+, iOS 16+ |
| **Self-hosted server** | Node.js <23.0.0, PostgreSQL, Redis |

### Installation Methods

=== "Desktop (Recommended)"
    Download the desktop app for your platform from [affine.pro/download](https://affine.pro/download):
    - **Windows** — `.exe` installer or Microsoft Store
    - **macOS** — `.dmg` disk image
    - **Linux** — `.AppImage` or `.deb` package

    ```bash
    # Linux AppImage
    chmod +x AFFiNE-*.AppImage
    ./AFFiNE-*.AppImage
    ```

=== "Web App"
    Access AFFiNE directly at [app.affine.pro](https://app.affine.pro) — no installation required.

=== "Mobile"
    - **Android** — [Google Play Store](https://play.google.com/store/apps/details?id=app.affine.pro)
    - **iOS** — [Apple App Store](https://apps.apple.com/app/affine/id6444706688)

=== "Self-Hosted"
    See the Admin Guide for full deployment instructions. Quick start:
    ```bash
    docker pull ghcr.io/toeverything/affine-graphql:stable
    ```

### Post-Install Verification

Launch the application. You should see the AFFiNE welcome screen with options to create a new workspace or sign in.

> [!IMPORTANT]
> The desktop app works fully offline. Cloud sync requires creating an AFFiNE Cloud account or connecting to a self-hosted server.

### Install Troubleshooting

| Problem | Solution |
|---|---|
| Desktop app won't launch on Linux | Ensure `libfuse2` is installed: `sudo apt install libfuse2` |
| Blank screen on startup | Clear the app cache: delete `~/.config/AFFiNE` and relaunch |
| Native binding version mismatch | Reinstall dependencies: delete `node_modules` and run `yarn install` |
| Browser shows blank page | Clear browser cache and ensure JavaScript is enabled |
| Mobile app crashes on launch | Update to the latest version from your app store |

---

## 3. Configuration

AFFiNE's user-facing configuration is managed through the in-app settings panel. Access it via the gear icon in the sidebar.

### General Settings

| Setting | Description |
|---|---|
| **Language** | UI language (30+ languages supported via i18n) |
| **Appearance** | Light, dark, or system theme |
| **Font family** | System font or custom font for documents |
| **Full-width layout** | Expand document content to full viewport width |
| **Date format** | Preferred date display format |
| **Start page** | What to show when the app opens (last visited, all pages, journal) |

### Editor Settings

| Setting | Description |
|---|---|
| **Spell check** | Enable/disable browser spell checking |
| **Default code block language** | Pre-selected language for new code blocks |
| **New doc default mode** | Page mode or Edgeless mode for new documents |
| **Display bi-directional links** | Show backlinks at the bottom of pages |

### Cloud & Sync

| Setting | Description |
|---|---|
| **AFFiNE Cloud** | Enable cloud sync and collaboration |
| **Custom server** | Connect to a self-hosted AFFiNE server |
| **Workspace sync** | Per-workspace cloud sync toggle |

> [!TIP]
> For full server configuration options (environment variables, authentication providers, storage backends), see the Admin Guide Configuration Reference.

---

## 4. Core Usage

### Working with Pages

Pages are rich-text documents built from composable blocks. Every page starts in **Page mode** — a vertical document layout optimized for writing.

**Creating a page:**

1. Click **New Page** in the sidebar (or press `Ctrl/Cmd + N`)
2. Type a title and press `Enter` to begin writing
3. Use the slash menu (`/`) to insert any block type

**Block types available via slash menu:**

| Block | Trigger | Description |
|---|---|---|
| Text | `/text` | Standard paragraph |
| Heading 1–6 | `/h1` to `/h6` | Section headings |
| To-do | `/todo` | Checkbox list item |
| Bulleted list | `/bullet` | Unordered list |
| Numbered list | `/numbered` | Ordered list |
| Code block | `/code` | Syntax-highlighted code |
| Quote | `/quote` | Block quote |
| Divider | `/divider` | Horizontal rule |
| Image | `/image` | Upload or embed image |
| Bookmark | `/bookmark` | Web page link preview |
| Table | `/table` | Structured data table |
| Database | `/database` | Inline database view |
| LaTeX | `/latex` | Mathematical formula |
| Callout | `/callout` | Highlighted information box |
| Linked doc | `/linked` | Embed or link another page |
| File attachment | `/file` | Upload any file |
| Embed iframe | `/embed` | Embed external content (YouTube, Figma, etc.) |

> [!NOTE]
> Block types are managed by the BlockSuite editor framework. Each block type supports drag-and-drop reordering, copy/paste, and conversion between types.

**Inline formatting:**

| Format | Shortcut |
|---|---|
| Bold | `Ctrl/Cmd + B` |
| Italic | `Ctrl/Cmd + I` |
| Underline | `Ctrl/Cmd + U` |
| Strikethrough | `Ctrl/Cmd + Shift + S` |
| Inline code | `Ctrl/Cmd + E` |
| Link | `Ctrl/Cmd + K` |
| Highlight | Select text → choose color from toolbar |

**Inline elements:** Beyond basic formatting, AFFiNE supports inline LaTeX (`$formula$`), inline mentions (`@`), footnotes, and linked document references.

### Working with Edgeless (Whiteboard)

Switch any page to **Edgeless mode** using the toggle at the top of the page. Edgeless provides an infinite canvas for visual thinking.

**Edgeless tools:**

| Tool | Description |
|---|---|
| **Select** (default) | Click, drag, and resize elements |
| **Pen/Brush** | Freehand drawing with pressure sensitivity |
| **Shape** | Rectangles, ellipses, triangles, diamonds, rounded rectangles |
| **Connector** | Arrow lines connecting shapes (auto-routing) |
| **Text** | Edgeless text blocks |
| **Note** | Document note blocks on the canvas |
| **Frame** | Group canvas elements into presentation frames |
| **Mind map** | Hierarchical mind map nodes |
| **Template** | Pre-built canvas templates |

> [!TIP]
> Hold `Space` and drag to pan the canvas. Use `Ctrl/Cmd + scroll` to zoom in and out. Double-click empty canvas to create a text element.

**Frames and presentations:** Group elements into frames for slide-like presentations. Navigate between frames sequentially using the frame panel.

### Databases

AFFiNE includes a built-in database system for structured data. Insert a database from the slash menu (`/database`).

**Database views:**

| View | Description |
|---|---|
| **Table** | Spreadsheet-style rows and columns |
| **Kanban** | Card-based board grouped by a property |

**Property types:** Text, number, date, select, multi-select, checkbox, link, progress, and more. Each row in a database is also a full AFFiNE page that can be opened and edited.

> [!WARNING]
> Database columns share property definitions across views. Renaming or deleting a property affects all views of that database.

### Collections

Collections organize pages into logical groups. Access them from the sidebar.

- **Manual collections** — drag pages into a collection to organize them
- **Smart collections** — define filter rules (by tag, creation date, property values) to auto-populate
- **Pinned collections** — pin frequently-used collections to the sidebar

### Search and Quick Search

Press `Ctrl/Cmd + K` to open Quick Search. Search across all pages by title and content. Results update as you type.

**Search features:**

- Full-text search across all workspace pages
- Recent pages list
- Quick actions (create new page, navigate to settings)
- Linked doc insertion from search results

### Journal

The Journal feature provides a daily-entry interface. Each day gets its own page, accessible from the sidebar calendar. Journal pages are regular pages with date-based organization.

### AI Copilot

AFFiNE integrates an AI assistant (Copilot) for content creation and editing. The AI button appears in the editor toolbar and sidebar.

**AI capabilities:**

| Feature | Description |
|---|---|
| **Write with AI** | Generate content from a prompt |
| **Summarize** | Create a summary of selected content |
| **Translate** | Translate text to another language |
| **Improve writing** | Polish grammar and style |
| **Make shorter/longer** | Adjust content length |
| **Change tone** | Rewrite in a different voice (professional, casual, etc.) |
| **Explain** | Provide an explanation of selected content |
| **Generate image** | Create images from text descriptions |

> [!IMPORTANT]
> AI features require an AFFiNE Cloud Pro subscription or a self-hosted server with configured AI providers (OpenAI, Google Gemini, or Cloudflare Workers AI). See the Admin Guide for provider configuration.

### Import and Export

**Supported import formats:**

- Markdown (`.md`)
- HTML
- Notion export (`.zip`)
- DOCX (via native parser)

**Supported export formats:**

- Markdown
- HTML
- PDF
- PNG (edgeless snapshots)

Access import/export from the page menu (three-dot menu at the top of a page).

### Keyboard Shortcuts

| Action | Windows/Linux | macOS |
|---|---|---|
| New page | `Ctrl + N` | `Cmd + N` |
| Quick search | `Ctrl + K` | `Cmd + K` |
| Bold | `Ctrl + B` | `Cmd + B` |
| Italic | `Ctrl + I` | `Cmd + I` |
| Undo | `Ctrl + Z` | `Cmd + Z` |
| Redo | `Ctrl + Shift + Z` | `Cmd + Shift + Z` |
| Slash menu | `/` | `/` |
| Indent | `Tab` | `Tab` |
| Outdent | `Shift + Tab` | `Shift + Tab` |
| Turn into heading | `Ctrl + Shift + 1-6` | `Cmd + Shift + 1-6` |

---

## 5. Common Tasks

### Create a Project Tracker Database

**Goal:** Set up a kanban-style project board with custom properties.

1. Create a new page and type a title (e.g., "Project Board")
2. Type `/database` and select **Database — Full Page**
3. Add properties: **Status** (select: To Do, In Progress, Done), **Priority** (select: High, Medium, Low), **Due Date** (date)
4. Add rows for each task
5. Switch to **Kanban** view and group by **Status**

**Verify:** Tasks appear as cards in their respective status columns.

### Set Up a Team Workspace with Cloud Sync

**Goal:** Create a shared workspace for your team.

1. Sign in to AFFiNE Cloud (or your self-hosted server)
2. Create a new workspace
3. Open **Settings → Members**
4. Invite team members by email
5. Set permissions: **Owner**, **Admin**, **Editor**, or **Viewer**

> [!TIP]
> Workspace members see all pages by default. Use doc-level permissions to restrict access to sensitive documents.

**Verify:** Invited members can see and edit workspace content after accepting the invitation.

### Create a Presentation with Edgeless Frames

**Goal:** Build a slide deck using the whiteboard canvas.

1. Open a page and switch to **Edgeless** mode
2. Select the **Frame** tool from the toolbar
3. Draw a frame for each slide
4. Add content inside each frame: text, shapes, images, embedded docs
5. Use the **Frame Panel** (sidebar) to reorder slides
6. Present by clicking the play button in the frame panel

**Verify:** Frames navigate sequentially in presentation mode.

### Import Notes from Notion

**Goal:** Migrate your Notion workspace to AFFiNE.

1. In Notion: **Settings → Export** → choose **Markdown & CSV**
2. In AFFiNE: open the page menu → **Import** → **Notion**
3. Select the exported `.zip` file
4. Pages, databases, and nested structure are preserved

**Verify:** Imported pages appear in the sidebar with their original hierarchy.

### Organize Pages with Collections

**Goal:** Create a smart collection that auto-groups pages by tag.

1. In the sidebar, click **Collections** → **New Collection**
2. Choose **Rules-based** collection
3. Add a filter rule: **Tag** → **contains** → "meeting-notes"
4. Name the collection "Meeting Notes"

**Verify:** All pages tagged "meeting-notes" automatically appear in the collection.

### Use AI Copilot for Writing

**Goal:** Draft a blog post outline with AI assistance.

1. Create a new page
2. Click the **AI** button in the toolbar (or type `/ai`)
3. Enter a prompt: "Write an outline for a blog post about remote work productivity"
4. Review the generated content
5. Select sections and use **Make longer** to expand them

**Verify:** AI-generated content appears in the editor and can be edited like any other content.

### Set Up Daily Journaling

**Goal:** Use the journal feature for daily reflections.

1. Click **Journal** in the sidebar
2. Today's journal page opens (or is created)
3. Write your daily entry
4. Use the calendar widget to navigate to past entries
5. Link journal entries to relevant project pages using `@` mentions

**Verify:** Each day has its own dedicated page accessible via the calendar.

### Connect to a Self-Hosted Server

**Goal:** Use the desktop app with your organization's AFFiNE server.

1. Open **Settings → Account**
2. Click **Custom Server**
3. Enter the server URL (e.g., `https://affine.yourcompany.com`)
4. Sign in with your credentials (email/password or SSO)

> [!WARNING]
> Switching servers may require creating a new local workspace. Existing local data is not automatically migrated to the new server.

**Verify:** The server name appears in the app header, confirming the connection.

---

## 6. Troubleshooting

### Diagnostic Decision Tree

```text
Problem?
├─ Can't sign in → Check credentials, server URL, network
├─ Sync not working → Check cloud connection, server status
├─ Editor performance → Check document size, browser resources
├─ Desktop app issues → Check app version, clear cache
└─ Mobile issues → Update app, check OS compatibility
```

### Error: `Native binding package version mismatch`

**Cause:** The native Rust modules are out of sync with the JavaScript packages after a partial update.

**Solution:**
1. Delete `node_modules` across the monorepo
2. Run `yarn install` to reinstall all dependencies
3. Rebuild native modules

**Prevention:** Always run `yarn install` after pulling updates. The app expects native binding version `0.26.3`.

### Sync fails silently with no user prompt

**Cause:** Network interruption or server-side error during CRDT sync. (Community issue [#14846](https://github.com/toeverything/AFFiNE/issues/14846))

**Solution:**
1. Check your network connection
2. Open **Settings → Sync** to verify cloud status
3. If status shows error, try signing out and back in
4. As a last resort, export your pages and reimport

**Prevention:** Monitor the sync status indicator in the bottom bar. Enable notifications for sync failures when available.

### Desktop app: Link preview and image proxy broken on self-hosted server

**Cause:** The Electron app's link preview and image proxy rely on the server's external URL configuration. (Community issue [#14865](https://github.com/toeverything/AFFiNE/issues/14865))

**Solution:**
1. Verify `AFFINE_SERVER_EXTERNAL_URL` is set correctly on the server
2. Ensure the server is accessible from the desktop app's network
3. Check that HTTPS certificates are valid if using SSL

**Prevention:** Configure `AFFINE_SERVER_EXTERNAL_URL` to the publicly accessible URL during initial server setup.

### Self-hosting: Unable to connect

**Cause:** Server configuration or network misconfiguration. (Community issue [#14872](https://github.com/toeverything/AFFiNE/issues/14872))

**Solution:**
1. Verify the server is running: check container logs
2. Confirm the port (default `3010`) is accessible
3. Check `AFFINE_SERVER_HOST` and `AFFINE_SERVER_PORT` environment variables
4. Verify Redis and PostgreSQL connectivity

**Prevention:** Use the `/info` health endpoint to verify the server is responding correctly.

### Keyboard shortcuts conflict with Polish (and other) language input

**Cause:** AFFiNE's keyboard shortcuts can interfere with input methods for certain languages. (Community issue [#14519](https://github.com/toeverything/AFFiNE/issues/14519))

**Solution:**
1. Switch to an English keyboard layout temporarily for shortcut use
2. Use the slash menu (`/`) instead of keyboard shortcuts where possible

### OIDC sign-in fails with "email required"

**Cause:** The OIDC provider is not returning an email address in the token claims. (Community issue [#14683](https://github.com/toeverything/AFFiNE/issues/14683))

**Solution:**
1. Configure your OIDC provider to include `email` in the token scope
2. Ensure the user account has a verified email address
3. Check the OIDC provider's claim mapping configuration

**Prevention:** Verify OIDC configuration includes `email` scope before deploying.

### Mobile: Text entered twice on Samsung keyboard

**Cause:** Composing-event handling issue with Samsung keyboard input method. (Community issues [#12806](https://github.com/toeverything/AFFiNE/issues/12806), [#14021](https://github.com/toeverything/AFFiNE/issues/14021))

**Solution:**
1. Switch to Gboard or another keyboard app
2. Disable predictive text temporarily
3. Update the AFFiNE app to the latest version

### Markdown export: Inconsistent table format

**Cause:** Table column alignment metadata may not round-trip correctly during markdown export. (Community issue [#14860](https://github.com/toeverything/AFFiNE/issues/14860))

**Solution:**
1. After export, manually adjust table alignment markers (`|---|:---:|---:|`)
2. Use the HTML export format as an alternative for complex tables

### Error 500 on Mac Desktop and iOS

**Cause:** Server-side error during client communication. (Community issue [#14868](https://github.com/toeverything/AFFiNE/issues/14868))

**Solution:**
1. Check server logs for the specific error
2. Verify the server version matches the client version
3. Clear the app cache and retry

### Comment feature unavailable in Firefox/Safari

**Cause:** Browser-specific rendering differences in the comment overlay. (Community issue [#14852](https://github.com/toeverything/AFFiNE/issues/14852))

**Solution:**
1. Use Chrome or Edge for full feature support
2. Check for browser updates
3. Disable browser extensions that may interfere

### Audio transcription ignores OpenAI config on self-hosted

**Cause:** The copilot audio transcription feature may attempt to use Gemini models instead of configured OpenAI provider. (Community issue [#14859](https://github.com/toeverything/AFFiNE/issues/14859))

**Solution:**
1. Verify the copilot provider configuration in server settings
2. Ensure the OpenAI API key is correctly set
3. Update to the latest server version with the fix

---

## 7. FAQ

**Q: Is AFFiNE free?**

AFFiNE is open-source (MIT licensed) and free to use. The desktop, web, and mobile apps are free. AFFiNE Cloud offers a free tier with limited storage, and Pro/Team plans for additional features like unlimited cloud storage, AI copilot, and team collaboration.

**Q: Can I use AFFiNE completely offline?**

Yes. The desktop app works fully offline with local data storage. Pages, whiteboards, and databases are all stored locally. Cloud sync is optional and only activates when configured.

**Q: How does AFFiNE sync data between devices?**

AFFiNE uses CRDT (Conflict-free Replicated Data Type) technology via the y-octo library (a Rust implementation of the Yjs protocol). Changes merge automatically without conflicts, even when multiple users edit simultaneously.

**Q: Can I self-host AFFiNE?**

Yes. AFFiNE provides Docker images for self-hosting. You need PostgreSQL, Redis, and Node.js. See the Admin Guide for detailed deployment instructions.

**Q: What data formats does AFFiNE support for import?**

Markdown, HTML, Notion exports (`.zip`), and DOCX files. The import system preserves document structure, formatting, and embedded content where possible.

**Q: How do I back up my data?**

- **Local data:** Back up the AFFiNE data directory (`~/.config/AFFiNE` on Linux, `~/Library/Application Support/AFFiNE` on macOS, `%APPDATA%/AFFiNE` on Windows)
- **Cloud data:** Export workspaces from **Settings → Workspace → Export**
- **Self-hosted:** Back up the PostgreSQL database and blob storage

**Q: Can I use my own AI models with AFFiNE?**

Yes, on a self-hosted server. Configure custom OpenAI-compatible API endpoints in the server's copilot provider settings. Supported providers include OpenAI, Google Gemini, Anthropic, and Cloudflare Workers AI. See the Admin Guide for provider configuration.

**Q: What is BlockSuite?**

BlockSuite is AFFiNE's open-source editor framework. It provides the block-based editing engine that powers both Page mode and Edgeless mode. BlockSuite is developed by the same team and is designed to be reusable in other applications.

**Q: How do I recover deleted pages?**

Deleted pages go to **Trash** in the sidebar. You can restore them from there within 30 days. After that, they are permanently deleted.

**Q: Can I embed external content?**

Yes. Use the `/embed` slash command to embed content from supported services (YouTube, Figma, Google Maps, etc.) via iframe. You can also embed other AFFiNE pages using the `/linked` command.

**Q: Does AFFiNE support MCP (Model Context Protocol)?**

Yes. AFFiNE supports MCP for AI integration, allowing AI tools to create and interact with workspace documents via WebSocket API. Note: documents created via MCP may not appear in the workspace doc list until synced. (Community issue [#14582](https://github.com/toeverything/AFFiNE/issues/14582))

**Q: How do workspace permissions work?**

Workspace roles: **Owner** (full control), **Admin** (manage members, settings), **Editor** (create and edit), **Viewer** (read only). Document-level permissions can further restrict or grant access to specific pages.

---

_Generated May 2026 from toeverything/AFFiNE at df482c9. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._