Outline User Guide

Outline is a fast, collaborative knowledge base and wiki for teams, built with React and Node.js. It organizes your team's documentation into nested collections and documents, edits them in a real-time collaborative rich-text editor, and makes everything instantly searchable. This guide shows you how to get Outline running, how to use every part of the product, and how to integrate it with the rest of your stack.

Note

There are two ways to use Outline. The maintainers offer a fully managed cloud version at getoutline.com — if you just want to use Outline you do not need to run any code. This guide is for people who want to self-host their own copy of Outline and for everyone learning the product's features, which are identical in both editions.

Table of Contents

1. What Outline Is
2. Quick Start (Self-Hosted)
3. Requirements
4. Core Concepts
5. Everyday Usage
6. The Editor
7. Sharing & Permissions
8. Search
9. Importing & Exporting
10. Integrations
11. The API & MCP Server
12. Workflows
13. Troubleshooting
14. FAQ
15. Reference

1. What Outline Is

Outline is a team knowledge base: a place to write, organize, and find your team's documentation, processes, meeting notes, and reference material. It is designed for fast writing and fast retrieval, with a polished editor and an opinionated structure.

What you can do with Outline:

• Organize knowledge into collections (top-level groupings) containing a tree of nested documents.
• Write in a real-time collaborative editor — multiple people can edit the same document simultaneously, with live cursors.
• Use rich formatting: headings, tables, checklists, code blocks with syntax highlighting, math (KaTeX), diagrams (Mermaid and diagrams.net), embeds, images, and /-triggered slash commands.
• Comment on documents and resolve discussion threads.
• Search across everything you have access to, with full-text ranking.
• Share documents publicly via links, or restrict access with groups and per-document permissions.
• Create reusable templates for recurring document types.
• Import existing content from Notion, Confluence, Markdown, and JSON; export to Markdown, HTML, PDF, or JSON.
• Sign in with your existing identity provider (Google, Slack, Microsoft/Azure, Discord, generic OIDC), an email magic link, or a passkey.
• Drive everything programmatically through a complete HTTP API, and connect AI assistants through the built-in Model Context Protocol (MCP) server.

Tip

If you are an end user of a wiki your company already runs on Outline, the day-to-day usage in Section 5 onward applies to you directly — skip the installation sections.

License

Outline's source code is published under the Business Source License 1.1 (BSL 1.1). This is a source-available license, not a traditional OSI-approved open-source license: you may run, modify, and self-host the code, but the BSL places limits on offering Outline as a competing hosted service. Each release converts to the Apache 2.0 license after the change date defined in the LICENSE file.

Important

Read the LICENSE file before building a commercial offering on top of Outline. For internal team use and self-hosting, the BSL imposes no practical restrictions.

2. Quick Start (Self-Hosted)

The fastest way to evaluate a self-hosted Outline is with Docker. Outline needs three things: the application container, a PostgreSQL database, and a Redis server.

Note

The official, always-current hosting instructions live at docs.getoutline.com/s/hosting. The steps below get you to a working instance and explain what each value means.

Step 1 — Generate your secrets

Outline requires two secret keys. Generate each with OpenSSL:

openssl rand -hex 32

4f8a2c9e1b7d3a6f0e5c8b2a9d4f7e1c3b6a8d2f5e9c0b4a7d1f3e6c9b2a5d8f

Run it twice — once for SECRET_KEY and once for UTILS_SECRET.

Caution

SECRET_KEY must be exactly 64 hexadecimal characters. It is used to encrypt data at rest. Do not change it after your first run or existing users will be unable to log in and encrypted data will be unreadable.

Step 2 — Create your environment file

Copy the sample and fill in the required values:

cp .env.sample .env

At minimum set the following (see Section 15 for the full list):

NODE_ENV=production
URL=https://wiki.example.com
SECRET_KEY=<your 64-hex key>
UTILS_SECRET=<your second key>
DATABASE_URL=postgres://user:pass@postgres:5432/outline
REDIS_URL=redis://redis:6379
FILE_STORAGE=local

You must also configure at least one sign-in method (see Section 7 and the authentication entries in Section 15). Without one, you will have no way to log in.

Step 3 — Start the dependencies

The bundled docker-compose.yml defines local Postgres and Redis services for development:

docker compose up -d

[+] Running 2/2
 ✔ Container outline-redis-1     Started
 ✔ Container outline-postgres-1  Started

Warning

The docker-compose.yml shipped in the repository binds Postgres and Redis to 127.0.0.1 with the development credentials user/pass/outline. It is intended for local development, not production. For production, use managed or hardened database servers and strong credentials — see the Admin Guide.

Step 4 — Run database migrations and start Outline

Outline ships as a Docker image. Pull it, run the migrations, then start the server:

docker run --rm --env-file .env outlinewiki/outline yarn db:migrate
docker run -d --env-file .env -p 3000:3000 outlinewiki/outline

Outline is listening on http://localhost:3000

Open your URL in a browser and sign in with the provider you configured.

Tip

The very first user to sign in becomes the workspace admin automatically. Subsequent users join as members (or are matched to your SSO domain rules).

3. Requirements

Note

For email sign-in and notifications you also need an SMTP server. Without SMTP, email-based magic-link login and transactional emails (such as "document updated") are unavailable, but SSO sign-in still works.

4. Core Concepts

Understanding these few entities makes the rest of Outline obvious.

Workspace (Team) : Your entire Outline instance for an organization. All users, collections, and settings belong to one workspace. (Internally this is the Team model.)

Collection : A top-level grouping of documents — for example Engineering, Handbook, or Sales. Collections have their own permissions, color, icon, and a document tree. Think of them as the "drives" or "spaces" of your wiki.

Document : A single page of content. Documents live inside a collection and can be nested arbitrarily deep to form a tree. A document has a title, rich body, revision history, comments, and metadata (author, collaborators, timestamps).

Revision : A saved historical version of a document. Outline keeps a revision history so you can view and restore earlier versions.

Template : A reusable document skeleton. Create a document once, mark it as a template, and start new documents pre-filled with its structure.

Draft : A document that has not yet been published into a collection. Drafts are visible only to you (and people you explicitly invite) until you publish them.

Group : A named set of users (e.g. Marketing) used to grant collection or document access in bulk.

Comment : A threaded discussion attached to a document (and optionally anchored to a text selection). Comments can be resolved.

Tip

The mental model is simple: Collections contain a tree of Documents. Documents have Revisions, Comments, and can become Templates. People and Groups are granted access to Collections and Documents.

5. Everyday Usage

Collections

Collections are managed from the left sidebar.

• Create a collection — Click the + next to Collections in the sidebar. Give it a name, icon, color, and a default permission level.
• Set permissions — A collection can be private (explicit members only) or grant a default access level (read or read-write) to the whole workspace.
• Add members or groups — Open the collection, choose Members, and add individual users or groups with a permission level.
• Sort — Documents within a collection can be ordered manually (drag-and-drop) or sorted by title.
• Archive / delete — Collections can be archived (hidden but recoverable) or deleted. Deleting a collection sends its documents to the trash.
• Export a whole collection — Export every document in a collection at once to Markdown, HTML, or JSON (see Section 9).

Documents

Documents are the heart of Outline.

• Create — Use the New doc button, the + in a collection, or the command bar. New documents start as drafts.
• Nest — Drag a document onto another in the sidebar to make it a child, building a hierarchy.
• Publish — A draft becomes visible to the collection's members when you Publish it.
• Move — Relocate a document (and its children) to another collection or parent.
• Duplicate — Copy a document, optionally including its child documents.
• Pin — Pin important documents to the top of a collection or the home screen for quick access.
• Star — Star documents you personally use often; starred docs appear in your sidebar.
• Subscribe — Subscribe to a document to be notified of changes.
• Archive / Trash — Archive removes a document from active view but keeps it; deleting sends it to the Trash, from which it can be restored or permanently deleted.

Note

The Trash holds deleted documents until they are permanently removed or the trash is emptied. Restoring a trashed document returns it to its original location when possible.

The Command Bar

Press Ctrl/⌘ + K to open the command bar (built on kbar). From here you can search, navigate, create documents, and run almost any action without leaving the keyboard. The command bar is the fastest way to drive Outline.

Tip

Most actions in Outline are also available as keyboard shortcuts. Open the command bar and start typing the name of what you want to do — it will show the shortcut next to each command.

Home, Drafts, and Recent

• Home surfaces recently viewed and updated documents.
• Drafts lists your unpublished documents.
• Search (next section) finds anything.

6. The Editor

Outline's editor is a rich-text editor built on ProseMirror. It writes and reads Markdown under the hood, so your content stays portable.

Formatting

The Slash Menu

Type / at the start of an empty line to open the slash command menu, which lists every block you can insert (headings, tables, images, dividers, embeds, code, math, and more). This is the primary way to add structured content.

Real-Time Collaboration

When two or more people open the same document, edits are merged live using Yjs (a CRDT) coordinated by the collaboration service. You will see other people's cursors and selections in real time, and changes are never lost to conflicts.

Important

Real-time collaboration requires the collaboration and websockets services to be running and reachable (they run by default). If live cursors do not appear, see Troubleshooting.

Comments

Select text and add a comment to start a threaded discussion anchored to that selection, or comment on the document as a whole. Reply to build threads, react with emoji, and resolve a thread when the discussion is settled.

Document History

Every save creates a revision. Open the document History to browse previous versions, see what changed, and restore an earlier version.

7. Sharing & Permissions

Signing In

Outline does not manage passwords. Instead, users sign in through one of the configured providers:

Tip

You can enable several providers at once. Users pick their method on the login screen. Domain rules can automatically assign users from your company domain to the workspace.

Document & Collection Permissions

Access is layered:

1. Collection access — Members of a collection can see its documents according to the collection's permission (read or read-write). Collections can be workspace-wide or private.
2. Document membership — Individual documents can be shared with specific users or groups, independent of the collection default.
3. Groups — Grant access to many people at once by adding a group to a collection or document.

Public Sharing

Any document can be shared via a public link (a Share). Public shares can optionally:

• Publish the document to the web at a /s/{shareId} URL.
• Include or exclude child documents.
• Be revoked at any time.

Caution

A public share makes the document readable by anyone with the link, with no sign-in required. Review what you are exposing before enabling a public share, and revoke shares you no longer need.

Roles

Users have workspace roles (such as admin, member, and viewer). Admins manage workspace settings, members create and edit content per their permissions, and viewers have read-only access.

8. Search

Outline indexes your documents for full-text search, powered by PostgreSQL (pg-tsquery).

• Quick search — Open the command bar (Ctrl/⌘ + K) and type.
• Full search page — The Search scene supports ranked results with snippets and filters (by collection, author, date, and document status).
• Title search — A dedicated fast path matches document titles only.
• Ranking — Results are ordered by relevance, and a popularity signal boosts frequently used content (tunable by the administrator).

Note

Search only ever returns documents you have permission to see — permissions are enforced on every query.

9. Importing & Exporting

Importing

Outline can bring in content you already have:

Workspace-level imports run as background jobs; you will be notified when they finish.

Exporting

You can export at the document, collection, or whole-workspace level:

Warning

A few export edge cases are known: images may be missing from PDF exports in some cases (#12441), and complex Markdown constructs (tables, inline code, LaTeX) can occasionally lose fidelity on round-trip (#12510). For an exact backup, prefer the JSON export.

10. Integrations

Outline integrates with many third-party tools. Each integration is a self-contained plugin; an administrator enables it by supplying the relevant credentials (see the Admin Guide). As a user, you benefit from them automatically once enabled.

Tip

Link previews (also called unfurls) work for any configured provider — just paste a link and Outline turns it into a rich, contextual mention.

11. The API & MCP Server

The HTTP API

Everything you can do in the Outline UI, you can do through its HTTP API. The API uses a simple RPC style: every endpoint is a POST to /api/<resource>.<action> with a JSON body.

curl https://wiki.example.com/api/documents.search \
  -H "Authorization: Bearer ${OUTLINE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query": "onboarding"}'

{
  "data": [
    { "document": { "id": "…", "title": "Onboarding", "url": "/doc/onboarding-…" }, "context": "…onboarding…" }
  ],
  "pagination": { "limit": 25, "offset": 0 }
}

There are around 210 endpoints spanning every resource — documents, collections, comments, shares, users, groups, and more. The documents resource alone exposes dozens of actions, including:

Tip

Get an API key from your account settings (the API Tokens / API Keys screen), then read the complete, always-current API reference at getoutline.com/developers.

The MCP Server

Outline ships a built-in Model Context Protocol (MCP) server, which lets AI assistants (such as Claude) read and act on your knowledge base through a standard protocol. The MCP endpoint is served by the application and exposes Outline's capabilities as MCP tools.

Note

The MCP server is a comparatively new surface and is under active development. If your MCP client fails during the initial handshake, check that you are on a recent Outline release — an issue affecting the notifications/initialized step has been reported (#12572).

12. Workflows

Set up a team handbook

• [ ] Create a Handbook collection with workspace read access.
• [ ] Create top-level documents for each area (HR, Engineering, Sales).
• [ ] Nest detailed pages under each area.
• [ ] Create templates for recurring docs (meeting notes, RFCs, onboarding checklists).
• [ ] Pin the most important entry points.
• [ ] Invite your team and confirm their access.

Run meeting notes

• [ ] Create a Meeting Notes template with sections for agenda, attendees, decisions, and action items.
• [ ] Start each meeting from the template.
• [ ] Collaborate live during the meeting — multiple editors at once.
• [ ] Use checklists for action items and @-mention owners.
• [ ] Resolve comment threads as items are handled.

Migrate from another tool

• [ ] Export your existing content (Notion, Confluence, or Markdown).
• [ ] Use Outline's Import for your source format.
• [ ] Review the imported tree and fix any nesting.
• [ ] Set collection permissions and groups.
• [ ] Announce the new wiki and pin a "Start here" doc.

Automate with the API

• [ ] Generate an API key in account settings.
• [ ] Script document creation/updates against /api/documents.*.
• [ ] Subscribe to webhooks for document events to trigger downstream automation.
• [ ] Or connect Zapier for no-code automation.

13. Troubleshooting

Error: The SECRET_KEY environment variable must be exactly 64 hexadecimal characters

Cause: SECRET_KEY is missing, too short/long, or contains non-hex characters. Solution: Generate a valid value with openssl rand -hex 32 and set it in your .env. Prevention: Generate keys with the documented command; never hand-edit them.

Error: Environment configuration is invalid, please check the following: (then the process exits)

Cause: One or more environment variables failed validation on startup (Outline validates configuration and exits if it is invalid). Solution: Read the listed messages — each line names the offending variable and the constraint it violated — and correct your .env. Common culprits: an invalid URL (must include http:// or https://), an out-of-range enum, or mutually exclusive variables set together (for example, both DATABASE_URL and the individual DATABASE_HOST/DATABASE_PORT values). Prevention: Start from .env.sample and change only what you need.

Error: "<value>" could not be parsed as a boolean, must be "true" or "false"

Cause: A boolean environment variable (such as FORCE_HTTPS or RATE_LIMITER_ENABLED) was given a value other than true/false/1/0. Solution: Set the variable to true or false. Prevention: Quote nothing — just use bare true/false.

Error: A network error occurred, try again? / No internet connection available

Cause: The browser client cannot reach the API server (network drop, server down, or proxy misconfiguration). Solution: Confirm the server is running and reachable at your URL, and that any reverse proxy forwards /api and websocket upgrades correctly. Prevention: Ensure your proxy passes WebSocket upgrade headers; set PROXY_IP_HEADER if behind a proxy.

Error: Request timeout after <n>ms

Cause: A request exceeded REQUEST_TIMEOUT (default 10s) — often a slow import/export or an overloaded server. Solution: Retry; for large imports/exports ensure a worker service is running. Increase REQUEST_TIMEOUT only if necessary. Prevention: Run at least one worker process and size your database/Redis appropriately.

Error: The selected file type is not supported (<type>)

Cause: You tried to upload a file whose MIME type Outline does not accept for that context. Solution: Convert the file to a supported type (e.g. PNG/JPEG for images) and retry. Prevention: Check the upload size and type limits (FILE_STORAGE_UPLOAD_MAX_SIZE).

Live cursors / real-time editing don't work

Cause: The collaboration or websockets service is not running or not reachable through your proxy. Solution: Ensure those services are enabled (they are by default) and that your reverse proxy allows WebSocket upgrades. If the collaboration service runs on a separate host, set COLLABORATION_URL to its public wss:// URL. Prevention: Keep all default services running, or scale them deliberately (see the Admin Guide).

Images missing from PDF export

Cause: A known limitation in some PDF export paths (#12441). Solution: Export to HTML or JSON instead, or open the document in the browser and print to PDF. Prevention: Use JSON export for archival fidelity.

A code block renders as a diagram in Safari

Cause: A reported Safari-specific rendering issue (#12596). Solution: Reload the document; verify the fenced block's language tag. Try another browser to confirm. Prevention: Keep your Outline instance updated.

Sidebar lags with a very large document tree

Cause: Rendering very large collection trees can be slow (#12589). Solution: Split oversized collections into smaller ones; collapse branches you are not using. Prevention: Keep collections reasonably scoped.

I can't log in / no sign-in options appear

Cause: No authentication provider is configured. Solution: Configure at least one provider (Google, Slack, Azure, Discord, OIDC, email, or passkeys) and restart. Prevention: Always set up a sign-in method before inviting users.

14. FAQ

Q: Do I have to self-host to use Outline? No. A fully managed version is available at getoutline.com. Self-hosting is for teams that want to run their own copy.

Q: Is Outline open source? Outline is source-available under the BSL 1.1. You can read, modify, and self-host the code, with restrictions on offering it as a competing hosted service. Each release later converts to Apache 2.0.

Q: What databases does Outline need? PostgreSQL for data and search, plus Redis for queues, caching, websockets, and collaboration.

Q: Can multiple people edit the same document at once? Yes — real-time collaborative editing is built in, using Yjs and the collaboration service.

Q: How is content stored — is it locked into a proprietary format? Documents are edited in a ProseMirror editor backed by Markdown, and you can export to Markdown, HTML, PDF, or JSON at any time. Your content is portable.

Q: Can I sign in with my company's SSO? Yes — Google, Slack, Microsoft/Azure, Discord, and any generic OIDC provider are supported, as well as email magic links and passkeys.

Q: Where do uploaded files and images go? To your configured file storage: local disk (FILE_STORAGE=local) or any S3-compatible object store (FILE_STORAGE=s3).

Q: Can I share a document publicly? Yes — create a public share link. Anyone with the link can read it (no login). You can revoke it anytime.

Q: How do I back up my wiki? Back up the PostgreSQL database (and your file storage if using local disk). For portable archives, use the workspace JSON export.

Q: Does Outline have an API? Yes — a comprehensive RPC-style HTTP API (POST /api/<resource>.<action>) with around 210 endpoints. See getoutline.com/developers.

Q: Can AI assistants connect to my Outline? Yes — Outline ships a built-in MCP server, so MCP-compatible AI clients can read and act on your knowledge base.

Q: How do I change the default language? Set DEFAULT_LANGUAGE (e.g. en_US). Outline is translated into many languages via the community translation project.

Q: Can I run the web, worker, and collaboration parts separately? Yes — use the SERVICES variable or --services flag to choose which services each process runs. This is covered in the Admin Guide.

Q: What happens to deleted documents? They go to the Trash, where they can be restored or permanently deleted.

Q: How do I upgrade my self-hosted instance? Pull the new image (or git pull for a source build), run yarn db:migrate, and restart. Migrations run automatically on Heroku-style deploys.

15. Reference

Essential Environment Variables

These are the variables most users need. The complete reference (including advanced tuning) is in the Admin Guide.

Note

Any variable can be loaded from a file by appending _FILE and pointing it at a path (e.g. SECRET_KEY_FILE=/run/secrets/outline_secret_key) — useful for Docker secrets.

Authentication Provider Variables (set at least one)

Keyboard

Tip

Open the command bar and type a command name to discover its exact keyboard shortcut on your platform.

Useful Links

• Hosted product & sign-up: getoutline.com
• End-user usage guide: docs.getoutline.com/s/guide
• Self-hosting docs: docs.getoutline.com/s/hosting
• API reference: getoutline.com/developers
• Source & discussions: github.com/outline/outline