# Joplin — User Guide Joplin is a free, open-source note-taking and to-do application with end-to-end encryption, cross-device synchronization, and Markdown-native editing. It runs on desktop (Windows, macOS, Linux), mobile (Android, iOS), the terminal (CLI), and extends into the browser via the Web Clipper extension. Notes are stored locally in Markdown format and can be synchronized across devices through Joplin Cloud, Joplin Server, Nextcloud, WebDAV, OneDrive, Dropbox, Amazon S3, or a local filesystem. This guide covers every user-facing feature — from first install through advanced workflows — written from the Joplin source code. --- ## 1. Quick Start Get up and running in under five minutes. ### 1.1 Install Download the latest release for your platform: | Platform | Method | |----------|--------| | **Windows** | `.exe` installer from [joplinapp.org](https://joplinapp.org) or `winget install Joplin.Joplin` | | **macOS** | `.dmg` from [joplinapp.org](https://joplinapp.org) or `brew install --cask joplin` | | **Linux** | AppImage: `wget -O - https://raw.githubusercontent.com/laurent22/joplin/dev/Joplin_install_and_update.sh \| bash` | | **Android** | Google Play Store or F-Droid | | **iOS** | Apple App Store | | **CLI** | `npm install -g joplin` | ### 1.2 Create Your First Note 1. Launch Joplin. 2. Click the **New Note** button (or press `Ctrl+N` / `Cmd+N`). 3. Type a title and start writing in Markdown. 4. Your note saves automatically. ### 1.3 Create Your First Notebook 1. Click **New Notebook** in the sidebar (or press `Ctrl+Shift+B`). 2. Name it (e.g., "Work", "Personal", "Projects"). 3. Drag existing notes into the notebook, or create new ones inside it. ### 1.4 Set Up Sync 1. Open **Tools → Options → Synchronisation** (desktop) or **Settings → Sync** (mobile). 2. Choose a sync target (Joplin Cloud is the simplest). 3. Enter your credentials and click **Apply**. 4. Press **Synchronise** (or wait for auto-sync). > [!TIP] > Start with Joplin Cloud if you want zero-config sync. It handles encryption key management, sharing, and publishing out of the box. You can always switch to a self-hosted target later — your notes stay in open Markdown format regardless. ### 1.5 Install the Web Clipper 1. Install the browser extension from the [Chrome Web Store](https://chrome.google.com/webstore) or [Firefox Add-ons](https://addons.mozilla.org). 2. Open Joplin desktop — the clipper connects automatically via the local REST API. 3. Navigate to any web page, click the Joplin icon, and choose **Clip simplified page**, **Clip complete page**, **Clip selection**, **Clip screenshot**, or **Clip URL**. ### 1.6 Enable Encryption 1. Open **Tools → Options → Encryption**. 2. Click **Enable encryption** and set a master password. 3. All devices using the same sync target will prompt for this password on next sync. > [!TIP] > Write down your master password and store it somewhere safe. If you lose it and have no decrypted device, your encrypted notes cannot be recovered. --- ## 2. Installation ### 2.1 Desktop (Electron) #### Windows **Installer (recommended):** ``` # Download from joplinapp.org and run the .exe installer # Or use winget: winget install Joplin.Joplin ``` **Portable mode:** When Joplin detects the `PORTABLE_EXECUTABLE_FILE` environment variable (set automatically when running from certain portable launchers), it stores all data next to the executable instead of in the user profile directory. **Default data directory:** `%APPDATA%\Joplin` > [!IMPORTANT] > On Windows, the installer requires administrator privileges. If you cannot elevate, use the portable `.zip` release instead. #### macOS ```bash # Homebrew brew install --cask joplin # Or download the .dmg from joplinapp.org ``` **Default data directory:** `~/.config/joplin-desktop` #### Linux **AppImage (recommended):** ```bash wget -O - https://raw.githubusercontent.com/laurent22/joplin/dev/Joplin_install_and_update.sh | bash ``` This installs the AppImage to `~/.joplin/` and creates a desktop entry. **Default data directory:** `~/.config/joplin-desktop` When running as an AppImage, the `APPIMAGE` environment variable is set automatically, enabling portable detection logic. > [!WARNING] > The AppImage requires FUSE to run. On Ubuntu 22.04+, install it with `sudo apt install libfuse2`. Without FUSE, the AppImage will fail to launch with a cryptic error. ### 2.2 Mobile #### Android - **Google Play Store:** Search "Joplin" by Laurent Cozic. - **F-Droid:** Available in the default repository. Data is stored in the app's internal storage. Notes sync via the configured sync target. #### iOS - **App Store:** Search "Joplin" by Laurent Cozic. Data is stored in the app sandbox. iCloud is *not* used for sync — configure a sync target in Settings. ### 2.3 CLI (Terminal) ```bash # Install globally via npm npm install -g joplin # Launch the terminal UI joplin # Or run a single command joplin help ``` **Requirements:** Node.js 18+, npm. **Default data directory:** `~/.config/joplin` (Linux/macOS), `%APPDATA%\Joplin` (Windows). The CLI provides a full terminal user interface (TUI) built on terminal-kit, with a note list, editor pane, and notebook sidebar. It also supports non-interactive single-command execution for scripting. ### 2.4 Web Clipper (Browser Extension) The Web Clipper is a companion browser extension that communicates with the Joplin desktop application via its local REST API (port 41184 by default). **Installation:** 1. Install the extension from Chrome Web Store or Firefox Add-ons. 2. Ensure Joplin desktop is running with the Web Clipper service enabled (**Tools → Options → Web Clipper → Enable Web Clipper Service**). 3. The extension auto-detects the running Joplin instance. **Clipping modes:** | Mode | What it captures | |------|-----------------| | Simplified page | Article content with formatting, images removed from nav/ads | | Complete page | Full HTML including styles and images | | Selection | Only the highlighted text/content | | Screenshot | Visual screenshot of the visible page | | URL | Just the page URL and title as a new note | ### 2.5 Building from Source ```bash git clone https://github.com/laurent22/joplin.git cd joplin # Install dependencies yarn install # Build all packages yarn build # Run desktop app in development mode cd packages/app-desktop yarn start ``` The monorepo uses Yarn workspaces. Key packages: | Package | Path | |---------|------| | Desktop app | `packages/app-desktop` | | Mobile app | `packages/app-mobile` | | CLI app | `packages/app-cli` | | Web Clipper | `packages/app-clipper` | | Core library | `packages/lib` | | Server | `packages/server` | ### 2.6 Updating - **Desktop:** Auto-update checks on launch (Windows/macOS). Linux AppImage: re-run the install script. - **Mobile:** Standard app store updates. - **CLI:** `npm update -g joplin` > [!IMPORTANT] > After a major version update, run a full sync before making changes on other devices. Database migrations may alter the sync format. --- ## 3. Configuration ### 3.1 General Settings Access settings via **Tools → Options** (desktop), **Settings** gear icon (mobile), or the `config` CLI command. #### Language & Locale | Setting | Key | Values | |---------|-----|--------| | Language | `locale` | ISO language codes (`en_US`, `fr_FR`, `de_DE`, `ja_JP`, etc.) | | Date format | `dateFormat` | `DD/MM/YYYY`, `MM/DD/YYYY`, `YYYY-MM-DD`, and other standard patterns | | Time format | `timeFormat` | `HH:mm`, `h:mm A` (12-hour) | The locale auto-detects from the system `LANG` environment variable on first launch. #### Note Display | Setting | Key | Default | Description | |---------|-----|---------|-------------| | Show note counts | `showNoteCounts` | Enabled | Display note count next to each notebook | | Incomplete todos on top | `uncompletedTodosOnTop` | Enabled | Sort uncompleted to-dos above completed ones | | Show completed todos | `showCompletedTodos` | Enabled | Whether completed to-dos appear in the list | | Note sort field | `notes.sortOrder.field` | `user_updated_time` | Options: `user_updated_time`, `user_created_time`, `title`, `order`, `todo_due`, `todo_completed` | | Notebook sort field | `folders.sortOrder.field` | `title` | Options: `title`, `last_note_user_updated_time` | ### 3.2 Themes Joplin ships with 8 built-in themes: | Theme | Style | Best for | |-------|-------|----------| | **Light** | Clean white background, dark text | Daytime use, well-lit environments | | **Dark** | Dark grey background, light text | Reduced eye strain in dim lighting | | **Dracula** | Purple-tinted dark theme | Developers familiar with Dracula palette | | **Solarised Light** | Warm cream tones | Extended reading sessions | | **Solarised Dark** | Dark blue-green tones | Low-light coding/writing | | **Nord** | Arctic blue-grey palette | Minimalist aesthetic | | **Aritim Dark** | High-contrast dark | AMOLED-friendly, high readability | | **OLED Dark** | Pure black background | True OLED screens, maximum battery savings | **Theme settings:** | Setting | Key | Description | |---------|-----|-------------| | Theme | `theme` | Select from the 8 built-in themes | | Auto-detect theme | `themeAutoDetect` | Follow system light/dark mode | | Preferred light theme | `preferredLightTheme` | Theme used when system is in light mode | | Preferred dark theme | `preferredDarkTheme` | Theme used when system is in dark mode | To enable automatic theme switching based on your operating system's light/dark mode: 1. Set `themeAutoDetect` to enabled. 2. Choose your `preferredLightTheme` (e.g., Light or Solarised Light). 3. Choose your `preferredDarkTheme` (e.g., Dark, OLED Dark, or Nord). ### 3.3 Editor Settings Joplin's desktop editor supports two modes: a **Markdown code editor** (CodeMirror-based) and a **Rich Text / WYSIWYG editor** (TinyMCE-based). | Setting | Key | Default | Description | |---------|-----|---------|-------------| | Code view | `editor.codeView` | Enabled | Toggle between Markdown source and Rich Text editing | | Auto-matching braces | `editor.autoMatchingBraces` | Enabled | Automatically pair braces `{}`, parentheses `()`, brackets `[]`, and quotes | | Autocomplete markup | `editor.autocompleteMarkup` | Enabled | Auto-close HTML tags, continue lists on Enter | | HTML to Markdown banner | `editor.enableHtmlToMarkdownBanner` | Enabled | Show a prompt when opening HTML-formatted notes offering to convert to Markdown | | Preserve paste colors | `editor.pastePreserveColors` | Disabled | Keep color formatting when pasting rich text | | Text patterns | `editor.enableTextPatterns` | Enabled | Auto-format Markdown syntax in the Rich Text editor (e.g., `**bold**` becomes **bold**) | **Editor layout modes:** The `layoutButtonSequence` setting controls which editor layout buttons appear in the toolbar. Available layouts: | Layout | Description | |--------|-------------| | **Editor** | Markdown source code only | | **Viewer** | Rendered preview only | | **Split View** | Side-by-side editor and preview | Toggle between layouts using the toolbar buttons or the keyboard shortcut `Ctrl+L`. ### 3.4 Synchronisation Settings | Setting | Key | Default | Description | |---------|-----|---------|-------------| | Sync target | `sync.target` | None | Which service to sync with (see Section 3.5) | | Max concurrent connections | `sync.maxConcurrentConnections` | 5 | Number of simultaneous sync connections (1-20) | | Resource download mode | `sync.resourceDownloadMode` | `always` | How attachments are downloaded: `always` (all immediately), `manual` (on demand), `auto` (as needed) | **Resource download modes explained:** - **Always:** All attachments download immediately during sync. Uses more bandwidth and storage but ensures offline access. - **Manual:** Attachments download only when you click on them. Saves bandwidth on metered connections. - **Auto:** Joplin decides based on file size and available resources. A balanced default for most users. ### 3.5 Sync Target Setup #### Joplin Cloud (Target 10) The simplest option — managed hosting by the Joplin team. 1. Create an account at [joplincloud.com](https://joplincloud.com). 2. In Joplin: **Tools → Options → Synchronisation**. 3. Set **Synchronisation target** to **Joplin Cloud**. 4. The path defaults to `api.joplincloud.com`. 5. Enter your Joplin Cloud email and password. 6. Click **Check synchronisation configuration** to verify. Benefits: managed encryption, note sharing, note publishing, email-to-note. #### Joplin Server (Target 9) — Self-Hosted For users who want full control with Joplin-specific features (sharing, publishing). ```yaml # docker-compose.yml for Joplin Server version: '3' services: joplin-server: image: joplin/server:latest ports: - "22300:22300" environment: - APP_BASE_URL=https://joplin.yourdomain.com - APP_PORT=22300 - DB_CLIENT=pg - POSTGRES_PASSWORD=changeme - POSTGRES_DATABASE=joplin - POSTGRES_USER=joplin - POSTGRES_PORT=5432 - POSTGRES_HOST=db depends_on: - db db: image: postgres:16 volumes: - ./data/postgres:/var/lib/postgresql/data environment: - POSTGRES_PASSWORD=changeme - POSTGRES_USER=joplin - POSTGRES_DB=joplin ``` Configuration in Joplin: | Setting | Key | Value | |---------|-----|-------| | Sync target | `sync.target` | Joplin Server | | Server URL | `sync.9.path` | `https://joplin.yourdomain.com` | | Username | `sync.9.username` | Your email | | Password | `sync.9.password` | Your password | #### Nextcloud (Target 5) ``` Sync target: Nextcloud WebDAV URL: https://your-nextcloud.com/remote.php/webdav/Joplin Username: your-nextcloud-user Password: your-nextcloud-password (or app password) ``` | Setting | Key | Value | |---------|-----|-------| | Sync target | `sync.target` | Nextcloud | | WebDAV URL | `sync.5.path` | `https://your-nextcloud.com/remote.php/webdav/Joplin` | | Username | `sync.5.username` | Nextcloud username | | Password | `sync.5.password` | Nextcloud password or app-specific password | Create the `Joplin` directory in your Nextcloud first via the Nextcloud web interface or WebDAV. #### WebDAV (Target 6) Any WebDAV-compatible server works. | Setting | Key | Value | |---------|-----|-------| | Sync target | `sync.target` | WebDAV | | WebDAV URL | `sync.6.path` | `https://webdav.example.com/joplin/` | | Username | `sync.6.username` | Your username | | Password | `sync.6.password` | Your password | Compatible services include Apache mod_dav, Nginx with ngx_http_dav_module, Synology NAS, and any standards-compliant WebDAV implementation. #### OneDrive (Target 3) 1. Set sync target to **OneDrive**. 2. Click **Authorise** — a browser window opens for Microsoft OAuth. 3. Sign in with your Microsoft account and grant permissions. 4. Joplin stores the auth token in `sync.3.auth`. 5. Notes sync to `Apps/Joplin` in your OneDrive. No manual URL or credential entry required. The OAuth flow handles everything. #### Dropbox (Target 7) 1. Set sync target to **Dropbox**. 2. Click **Authorise** — a browser window opens for Dropbox OAuth. 3. Sign in and grant permissions. 4. Joplin stores the auth token in `sync.7.auth`. 5. Notes sync to `Apps/Joplin` in your Dropbox. #### Amazon S3 (Target 8) For users with AWS infrastructure or S3-compatible storage (MinIO, Wasabi, Backblaze B2). | Setting | Key | Value | |---------|-----|-------| | Sync target | `sync.target` | Amazon S3 | | S3 bucket | `sync.8.path` | Your bucket name | | S3 URL | `sync.8.url` | `https://s3.amazonaws.com` (or custom endpoint) | | Region | `sync.8.region` | `us-east-1` (or your region) | | Access key | `sync.8.username` | AWS access key ID | | Secret key | `sync.8.password` | AWS secret access key | | Force path style | `sync.8.forcePathStyle` | Enable for MinIO/non-AWS S3 providers | **For S3-compatible providers (MinIO, Wasabi):** ``` S3 URL: https://s3.wasabisys.com (Wasabi example) Force path style: Enabled Region: us-east-1 ``` #### Filesystem (Target 2) Sync to a local directory — useful for USB drives, network shares, or manual backup. | Setting | Key | Value | |---------|-----|-------| | Sync target | `sync.target` | Filesystem | | Directory | `sync.2.path` | `/path/to/sync/directory` | The directory must exist and be writable. Joplin creates its own internal structure inside it. ### 3.6 OCR Settings (Desktop Only) Optical Character Recognition extracts searchable text from image attachments and PDFs. | Setting | Key | Default | Description | |---------|-----|---------|-------------| | Enable OCR | `ocr.enabled` | Disabled | Turn on OCR processing for attachments | | PDF mode | `ocr.pdfMode` | `normal` | `normal` or `accessible` — accessible mode extracts text layers first | | Handwritten text | `ocr.handwrittenTextDriverEnabled` | Disabled | Experimental; requires Joplin Server or Joplin Cloud | | Language data path | `ocr.languageDataPath` | Default | Custom path or URL for Tesseract language data | | Search extracted content | `ocr.searchInExtractedContent` | Enabled | Include OCR-extracted text in search results | To enable OCR: 1. Go to **Tools → Options → General**. 2. Enable **OCR**. 3. Wait for existing attachments to process (progress shown in note panel). 4. New attachments are processed automatically. ### 3.7 Proxy Settings Joplin respects standard proxy environment variables for all network operations including sync: | Variable | Purpose | |----------|---------| | `http_proxy` | HTTP proxy URL | | `https_proxy` | HTTPS proxy URL | | `HTTP_PROXY` | Alternative HTTP proxy (uppercase) | | `HTTPS_PROXY` | Alternative HTTPS proxy (uppercase) | Set these before launching Joplin: ```bash export https_proxy=http://proxy.example.com:8080 joplin ``` On desktop, you can also configure proxy settings in the application preferences. ### 3.8 CLI Configuration The CLI `config` command manages all settings from the terminal: ```bash # View a setting joplin config sync.target # Set a value joplin config sync.target 9 joplin config sync.9.path https://joplin.example.com joplin config sync.9.username [email removed] # List all settings joplin config # Reset a setting to default joplin config locale --reset ``` --- ## 4. Core Usage ### 4.1 Notes #### Creating Notes - **Desktop:** `Ctrl+N` (Windows/Linux) or `Cmd+N` (macOS), or click **New Note** in the toolbar. - **Mobile:** Tap the **+** button. - **CLI:** `joplin mknote "My Note Title"` #### Editing Notes Notes are written in **GitHub-flavoured Markdown** with extensions: **Standard Markdown:** ```markdown # Heading 1 ## Heading 2 ### Heading 3 **Bold text** *Italic text* ~~Strikethrough~~ - Bullet list - Second item - Nested item 1. Numbered list 2. Second item [Link text](https://example.com) ![Image alt](:/resource_id) > Blockquote `inline code` ``` **Fenced code blocks with syntax highlighting:** ````markdown ```python def hello(): print("Hello, Joplin!") ``` ```` **Tables:** ```markdown | Column 1 | Column 2 | |----------|----------| | Cell 1 | Cell 2 | ``` **Joplin-specific Markdown extensions:** | Syntax | Renders as | |--------|-----------| | `$...$` | Inline KaTeX math | | `$$...$$` | Block KaTeX math | | `:emoji_name:` | Emoji | | `==highlighted==` | Highlighted text | | `- [ ] Task` | Unchecked checkbox | | `- [x] Task` | Checked checkbox | | `:[resource_id](/resource_id)` | Internal resource link | | `[note title](:/{note_id})` | Internal note link | | `@mention` | Mention (in shared notebooks) | #### Rich Text (WYSIWYG) Editor Toggle between Markdown and Rich Text mode via **View → Toggle editor layout** or `Ctrl+L`. The Rich Text editor provides familiar word-processor controls: - Bold, italic, underline, strikethrough formatting buttons - Heading level dropdown - Bullet and numbered list buttons - Insert table, horizontal rule, link, image - Code block insertion - Text alignment When `editor.enableTextPatterns` is on, typing Markdown syntax in the Rich Text editor auto-formats it (e.g., `**text**` becomes bold text). > [!TIP] > If you prefer a word-processor experience, switch to Rich Text mode and enable text patterns. You get auto-formatting of Markdown syntax with a visual editing surface — the best of both worlds. #### Note Properties Each note has metadata accessible via the note info panel (click the **i** icon or **Note → Properties**): | Property | Description | |----------|-------------| | Title | Note title (also the first line if using inline title) | | Created | Creation timestamp | | Updated | Last modification timestamp | | Source URL | Original URL if clipped from the web | | Location | Geolocation (if enabled) | | ID | Unique note identifier | | Markup language | Markdown or HTML | #### Note Sorting Notes can be sorted by any of these fields: | Sort field | Description | |------------|-------------| | `user_updated_time` | Last time you edited the note (default) | | `user_created_time` | When you created the note | | `title` | Alphabetical by title | | `order` | Custom drag-and-drop order | | `todo_due` | To-do due date | | `todo_completed` | To-do completion date | Set the sort order in **View → Sort notes by** or via `joplin config notes.sortOrder.field title` in the CLI. ### 4.2 Notebooks Notebooks are the primary organisational unit. They can be nested to any depth. #### Creating Notebooks - **Desktop:** `Ctrl+Shift+B` or **File → New Notebook** - **Mobile:** Tap the sidebar → **New Notebook** - **CLI:** `joplin mkbook "Notebook Name"` #### Nested Notebooks Drag a notebook onto another notebook to create a sub-notebook. The tree structure is unlimited in depth. In the CLI, use `joplin use "Parent/Child"` to navigate to a nested notebook. #### Notebook Sorting | Sort field | Description | |------------|-------------| | `title` | Alphabetical (default) | | `last_note_user_updated_time` | Most recently modified note in notebook | ### 4.3 To-Dos To-dos are notes with a checkbox. They appear with a checkbox icon in the note list and can have due dates and alarms. #### Creating To-Dos - **Desktop:** Click the **New To-Do** button (checkbox icon) or **File → New To-Do** - **CLI:** `joplin mktodo "Buy groceries"` #### Managing To-Dos - **Mark complete:** Click the checkbox in the note list, or use `joplin done "Buy groceries"` (CLI). - **Mark incomplete:** Click the checkbox again, or use `joplin undone "Buy groceries"` (CLI). - **Set due date:** Open the note, click the alarm icon, set date/time. - **Set alarm:** Due date reminders trigger desktop notifications. #### To-Do Display Settings | Setting | Effect | |---------|--------| | `uncompletedTodosOnTop` | Float incomplete to-dos to the top of the list | | `showCompletedTodos` | Show or hide completed to-dos entirely | | Sort by `todo_due` | Order notes by upcoming due date | | Sort by `todo_completed` | Order by completion date (newest completed first) | ### 4.4 Tags Tags provide cross-notebook organisation. A note can have unlimited tags, and tags work across all notebooks. #### Managing Tags - **Desktop:** Click the tag icon on a note, type a tag name, press Enter. - **CLI:** ```bash # Add a tag to a note joplin tag add "important" "My Note Title" # Remove a tag from a note joplin tag remove "important" "My Note Title" # List all tags joplin tag list # List notes with a specific tag joplin tag notetags "important" ``` Tags are shown in the sidebar. Click a tag to filter notes across all notebooks. ### 4.5 Search #### Desktop Search Press `Ctrl+F` (note search) or `Ctrl+G` / `F6` (global search) to search across all notes. **Search syntax:** | Operator | Example | Finds | |----------|---------|-------| | Plain text | `meeting notes` | Notes containing both "meeting" and "notes" | | Exact phrase | `"meeting notes"` | Notes containing the exact phrase | | Title only | `title:budget` | Notes with "budget" in the title | | Body only | `body:important` | Notes with "important" in the body | | Tag filter | `tag:work` | Notes tagged "work" | | Notebook filter | `notebook:Projects` | Notes in the "Projects" notebook | | Any | `any:1 cat dog` | Notes containing "cat" OR "dog" | | Negation | `-tag:archive` | Notes NOT tagged "archive" | | To-do filter | `type:todo` | Only to-do notes | | Note filter | `type:note` | Only regular notes | | Completed | `iscompleted:1` | Completed to-dos | | Due date | `due:20260101` | To-dos due on or before date | | Created | `created:20260101` | Notes created on or after date | | Updated | `updated:20260501` | Notes updated on or after date | | Wildcard | `meet*` | Notes containing words starting with "meet" | | Resource type | `resource:image/jpeg` | Notes with JPEG attachments | | Source URL | `sourceurl:example.com` | Notes clipped from example.com | | Latitude | `latitude:48` | Notes geolocated near latitude 48 | | Longitude | `longitude:2` | Notes geolocated near longitude 2 | | Altitude | `altitude:100` | Notes at approximately 100m altitude | **Combine operators freely:** ``` tag:work title:budget -tag:archive type:note created:20260101 ``` This finds regular notes (not to-dos) tagged "work" with "budget" in the title, not tagged "archive", created in 2026 or later. #### CLI Search ```bash joplin search "query text" ``` The CLI search command supports the same search syntax as the desktop. #### OCR Search When OCR is enabled (`ocr.enabled` and `ocr.searchInExtractedContent`), search results include text extracted from: - Image attachments (PNG, JPEG, etc.) - PDF documents - Scanned documents This means you can search for text visible in photos, screenshots, or scanned papers. ### 4.6 Attachments & Resources #### Adding Attachments - **Drag and drop:** Drop files onto the editor. - **Menu:** **Edit → Attach file** or click the paperclip icon. - **CLI:** `joplin attach ` - **Paste:** Paste images directly from clipboard (`Ctrl+V`). Supported formats include images (PNG, JPEG, GIF, SVG, WebP), documents (PDF, DOCX, XLSX), audio, video, and any other file type. #### Attachment Storage Attachments (called "resources" internally) are stored locally and synced alongside notes. They are referenced in Markdown via Joplin's resource ID syntax: ```markdown ![Image description](:/abc123def456) [Document.pdf](:/abc123def456) ``` #### Resource Download Modes Control how attachments sync with `sync.resourceDownloadMode`: | Mode | Behaviour | |------|-----------| | `always` | Download all attachments during sync | | `manual` | Download only when you open/view the attachment | | `auto` | Download based on size and recency | ### 4.7 Geolocation Joplin can record the geographic location where a note was created (with your permission). - **Mobile:** Uses device GPS. - **Desktop:** Uses IP-based geolocation. - **CLI:** Use `joplin geoloc ` to set or view geolocation. Click the geolocation link in note properties to open the location in your default maps application. ### 4.8 Note History Joplin keeps a version history of your notes. Access it via **Note → History** or the history icon. Previous versions show a diff view highlighting what changed. You can restore any previous version, which creates a new revision (the current version is preserved in history). ### 4.9 External Editor #### Desktop Click the external editor button (pencil-with-arrow icon) or use `Ctrl+E` to open the current note in your system's default text editor or a configured external editor. Changes saved in the external editor are reflected in Joplin immediately (file watch). #### CLI The CLI `edit` command opens a note in your `$EDITOR`: ```bash # Set your preferred editor export EDITOR=vim # Edit a note joplin edit "My Note Title" ``` The `EDITOR` environment variable determines which editor launches. Common values: `vim`, `nano`, `code --wait`, `subl --wait`. ### 4.10 CLI Command Reference The CLI provides 42 commands, each accessible as `joplin `: | Command | Description | |---------|-------------| | `apidoc` | Generate API documentation | | `attach` | Attach a file to a note | | `batch` | Run batch operations on notes | | `cat` | Display the content of a note | | `clear` | Clear the terminal screen | | `config` | View or set configuration values | | `cp` | Copy a note to a notebook | | `done` | Mark a to-do as completed | | `dump` | Dump the database for debugging | | `e2ee` | Manage end-to-end encryption | | `edit` | Open a note in an external editor | | `exit` | Exit the CLI application | | `export-sync-status` | Export synchronisation status information | | `export` | Export notes to a file or directory | | `geoloc` | View or set note geolocation | | `help` | Display help for a command | | `import` | Import notes from a file | | `keymap` | View or edit keyboard shortcuts | | `ls` | List notes in the current notebook | | `mkbook` | Create a new notebook | | `mknote` | Create a new note | | `mktodo` | Create a new to-do | | `mv` | Move a note to a different notebook | | `publish` | Publish a note (Joplin Cloud/Server) | | `ren` | Rename a note | | `restore` | Restore a note from the trash | | `rmbook` | Delete a notebook | | `rmnote` | Delete a note | | `search` | Search notes | | `server` | Start the API server | | `set` | Set a note property | | `settingschema` | Output the settings schema as JSON | | `share` | Share a notebook with a user | | `status` | Display sync and encryption status | | `sync` | Synchronise with the sync target | | `tag` | Manage tags (add, remove, list) | | `testing` | Run internal testing commands | | `todo` | Manage to-do properties | | `undone` | Mark a to-do as incomplete | | `unpublish` | Unpublish a note | | `use` | Switch to a notebook | | `version` | Display the Joplin version | Use `joplin help ` for detailed usage of any command. --- ## 5. Common Tasks ### 5.1 Migrating from Evernote Joplin has first-class Evernote import support via the ENEX format. 1. In Evernote, select the notebook(s) to export. 2. Choose **File → Export Notes** → **ENEX format**. 3. In Joplin, go to **File → Import → ENEX - Evernote Export File**. 4. Select the `.enex` file. 5. Choose a target notebook (or let Joplin create one matching the Evernote notebook name). **What transfers:** | Content | Preserved? | |---------|-----------| | Note text | Yes (HTML converted to Markdown) | | Attachments | Yes (images, files, audio) | | Tags | Yes | | Created/updated dates | Yes | | Notebooks | Yes (one ENEX per notebook) | | Internal links | Partially (re-linked by title matching) | | Reminders | No (recreate manually) | For large Evernote libraries, export one notebook at a time to avoid memory issues. **CLI import:** ```bash joplin import /path/to/export.enex ``` ### 5.2 Migrating from OneNote Joplin includes a OneNote importer that converts `.onepkg` files using a Rust-based WASM converter. 1. Export notebooks from OneNote as `.onepkg` files. 2. In Joplin: **File → Import → OneNote Export File**. 3. Select the file and wait for conversion. > [!WARNING] > The OneNote importer is computationally intensive. Large notebooks may take significant time to process, and the import process may appear to hang during the postprocessing stage (known issue #15132). Allow ample time and do not interrupt the process. ### 5.3 Importing Markdown Files ```bash # Import a single Markdown file joplin import /path/to/notes/file.md # Import a directory of Markdown files (desktop: File → Import → Markdown directory) joplin import /path/to/markdown/directory/ ``` Each `.md` file becomes a note. Sub-directories become sub-notebooks. ### 5.4 Importing JEX (Joplin Export) JEX files are Joplin's native export format — they preserve everything including encryption, attachments, and note IDs. 1. **File → Import → JEX - Joplin Export File**. 2. Select the `.jex` file. CLI: `joplin import /path/to/export.jex` ### 5.5 Exporting Notes #### JEX (Joplin Export) — Recommended for Backup **File → Export all → JEX - Joplin Export File** Exports everything: notes, notebooks, tags, resources, metadata. This is the recommended backup format. #### Markdown **File → Export all → Markdown** Exports notes as `.md` files with attachments in `_resources/` directories. Notebook structure is preserved as a directory hierarchy. #### HTML **File → Export all → HTML File** Exports rendered HTML versions of notes. **CLI export:** ```bash # Export all notes joplin export /path/to/output --format jex # Export a specific notebook joplin export /path/to/output --format md --notebook "Work" ``` ### 5.6 Setting Up End-to-End Encryption (E2EE) E2EE ensures that your notes are encrypted before leaving your device. Only devices with the master password can decrypt them. **Enable E2EE:** 1. Go to **Tools → Options → Encryption**. 2. Click **Enable encryption**. 3. Enter a strong master password. 4. Click **OK**. 5. Sync immediately to propagate the encryption configuration. **On additional devices:** 1. Sync the device. 2. Joplin will detect that encryption is enabled. 3. Enter the master password when prompted. 4. Notes decrypt automatically. **Key management:** - **Master keys** encrypt/decrypt notes. Created automatically. - **Public-private key pairs (PPK)** are used for sharing encrypted notes between users (Joplin Cloud/Server only). **CLI E2EE:** ```bash # Enable encryption joplin e2ee enable # Decrypt all notes (disable E2EE) joplin e2ee disable # Show E2EE status joplin status ``` > [!CAUTION] > If you lose your master password and have no device with decrypted notes, your encrypted notes are permanently lost. There is no recovery mechanism. Store your master password securely — ideally in a separate password manager. ### 5.7 Sharing Notes (Joplin Cloud / Joplin Server) Sharing requires Joplin Cloud or Joplin Server. Share individual notes or entire notebooks with other users. **Share a notebook:** 1. Right-click a notebook → **Share notebook**. 2. Enter the recipient's email (must have a Joplin Cloud/Server account). 3. Choose permission level: **Can view** or **Can edit**. **Share a note by link (publish):** 1. Right-click a note → **Publish note**. 2. A public URL is generated. 3. Anyone with the link can view the rendered note (read-only). **CLI publishing:** ```bash # Publish a note joplin publish "My Note Title" # Unpublish a note joplin unpublish "My Note Title" # Share a notebook (Joplin Cloud/Server only) joplin share "Notebook Name" [email removed] ``` ### 5.8 Using the Web Clipper Effectively **Clip a simplified article:** 1. Navigate to an article. 2. Click the Joplin Clipper icon. 3. Select **Clip simplified page**. 4. Choose the destination notebook. 5. Optionally add tags. 6. Click **Confirm**. **Clip a selection:** 1. Select text/images on a page. 2. Click the Joplin Clipper icon. 3. Select **Clip selection**. **Clip multiple pages into one note:** Use the **Clip URL** mode repeatedly — each clip creates a separate note that you can later merge. **Keyboard shortcut:** Configure a browser keyboard shortcut for quick clipping (browser extension settings). ### 5.9 Working with To-Do Lists **Create a project task list:** 1. Create a new to-do: **File → New To-Do**. 2. Title it with the project name. 3. In the body, use Markdown checkboxes for sub-tasks: ```markdown ## Sprint 14 Tasks - [ ] Design database schema - [ ] Implement API endpoints - [x] Set up CI/CD pipeline - [ ] Write integration tests ``` 4. Set a due date via the alarm icon. 5. Tag with project tags. 6. Sort the note list by `todo_due` to see upcoming deadlines. ### 5.10 Creating Templates Joplin supports note templates for frequently used note structures. 1. Create a note with your template content. 2. Save it in a "Templates" notebook. 3. When you need it, use **File → New note from template** and select the template. Templates support variables: | Variable | Expands to | |----------|-----------| | `{{date}}` | Current date | | `{{time}}` | Current time | | `{{datetime}}` | Current date and time | | `{{#custom}}` | Custom template variables | ### 5.11 Using Keyboard Shortcuts **Global shortcuts (desktop):** | Action | Windows/Linux | macOS | |--------|--------------|-------| | New note | `Ctrl+N` | `Cmd+N` | | New to-do | `Ctrl+T` | `Cmd+T` | | New notebook | `Ctrl+Shift+B` | `Cmd+Shift+B` | | Global search | `Ctrl+G` or `F6` | `Cmd+G` or `F6` | | Note search | `Ctrl+F` | `Cmd+F` | | Toggle sidebar | `Ctrl+Shift+L` | `Cmd+Shift+L` | | Toggle editor layout | `Ctrl+L` | `Cmd+L` | | Sync | `Ctrl+S` | `Cmd+S` | | Bold | `Ctrl+B` | `Cmd+B` | | Italic | `Ctrl+I` | `Cmd+I` | | Insert link | `Ctrl+K` | `Cmd+K` | | Insert checkbox | `Ctrl+Shift+C` | `Cmd+Shift+C` | | Strikethrough | `Ctrl+Shift+S` | `Cmd+Shift+S` | | External editor | `Ctrl+E` | `Cmd+E` | | Focus note list | `Ctrl+Shift+N` | `Cmd+Shift+N` | | Print note | `Ctrl+P` | `Cmd+P` | Customise shortcuts via **Tools → Options → Keyboard Shortcuts** or the CLI `keymap` command. ### 5.12 Using Internal Links Link between notes using their unique ID: 1. Right-click a note in the note list → **Copy Markdown link**. 2. Paste the link in another note. 3. Clicking the link opens the target note. The Markdown syntax is: ```markdown [Note Title](:/{note_id}) ``` Links survive note renames because they reference the immutable note ID. ### 5.13 Using Markdown Plugins and Math **KaTeX Math:** ```markdown Inline: $E = mc^2$ Block: $$ \int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2} $$ ``` **Mermaid Diagrams:** ````markdown ```mermaid graph TD A[Start] --> B{Decision} B -->|Yes| C[Action 1] B -->|No| D[Action 2] ``` ```` ### 5.14 Batch Operations (CLI) The CLI `batch` command runs operations across multiple notes. **Copy notes between notebooks:** ```bash joplin cp "Note Title" "Destination Notebook" ``` **Move notes:** ```bash joplin mv "Note Title" "Destination Notebook" ``` **Rename notes:** ```bash joplin ren "Old Title" "New Title" ``` **Delete notes and notebooks:** ```bash # Delete a note joplin rmnote "Note Title" # Delete a notebook (and all notes inside) joplin rmbook "Notebook Name" ``` ### 5.15 Using the REST API (Plugins & Automation) Joplin desktop exposes a local REST API (default port 41184) used by plugins and the Web Clipper. **Enable the API:** 1. Go to **Tools → Options → Web Clipper**. 2. Enable **Web Clipper Service**. 3. Note the API token shown. **Example API calls:** ```bash # List all notes curl http://localhost:41184/notes?token=YOUR_TOKEN # Get a specific note curl http://localhost:41184/notes/NOTE_ID?token=YOUR_TOKEN&fields=id,title,body # Create a note curl -X POST http://localhost:41184/notes?token=YOUR_TOKEN \ -H "Content-Type: application/json" \ -d '{"title": "API Note", "body": "Created via API"}' # Search notes curl "http://localhost:41184/search?query=my+search&token=YOUR_TOKEN" # List folders curl http://localhost:41184/folders?token=YOUR_TOKEN # List tags curl http://localhost:41184/tags?token=YOUR_TOKEN # Get resources (attachments) curl http://localhost:41184/resources?token=YOUR_TOKEN # Create a tag curl -X POST http://localhost:41184/tags?token=YOUR_TOKEN \ -H "Content-Type: application/json" \ -d '{"title": "my-tag"}' # Attach a tag to a note curl -X POST http://localhost:41184/tags/TAG_ID/notes?token=YOUR_TOKEN \ -H "Content-Type: application/json" \ -d '{"id": "NOTE_ID"}' ``` **Plugin API objects:** | Object | Endpoint | Description | |--------|----------|-------------| | Notes | `/notes` | Create, read, update, delete notes | | Folders | `/folders` | Manage notebooks | | Tags | `/tags` | Manage tags and tag-note associations | | Resources | `/resources` | Manage attachments | | Search | `/search` | Full-text search | | Events | `/events` | Event-driven updates | ### 5.16 Organizing Large Note Collections **Notebook hierarchy strategy:** ``` Work Projects Project Alpha Project Beta Meetings 2026 Q1 2026 Q2 Reference Personal Journal Recipes Travel Archive ``` **Tag taxonomy:** Use a consistent tag scheme: - Status tags: `active`, `done`, `blocked`, `review` - Priority tags: `p1-critical`, `p2-high`, `p3-normal` - Context tags: `@home`, `@office`, `@errands` - Project tags: `project-alpha`, `project-beta` **Combine search with tags and notebooks:** ``` notebook:Work tag:active title:standup ``` ### 5.17 Using Note Alarms and Reminders 1. Open a to-do note. 2. Click the **alarm/bell** icon. 3. Set the date and time. 4. Joplin will display a desktop notification at the scheduled time. Alarms require the desktop app to be running. Mobile notifications depend on the mobile app's background process. ### 5.18 Custom CSS Styling Customize the rendered note appearance with custom CSS: 1. Go to **Tools → Options → Appearance → Custom stylesheet for rendered Markdown**. 2. Click **Edit** to open the file (typically `userstyle.css`). 3. Add CSS rules. 4. Restart Joplin for changes to take effect. **Example custom CSS:** ```css /* Increase base font size */ body { font-size: 16px; line-height: 1.6; } /* Custom heading colors */ h1 { color: #2c3e50; } h2 { color: #34495e; } /* Code block styling */ pre code { font-family: 'JetBrains Mono', monospace; font-size: 14px; } /* Table styling */ table { border-collapse: collapse; width: 100%; } th { background-color: #3498db; color: white; } ``` You can also customize the editor appearance with a separate stylesheet for the editor panel. ### 5.19 Backup Strategies **JEX backup (recommended):** ```bash # Full backup via CLI joplin export /backup/joplin-$(date +%Y%m%d).jex --format jex ``` **Filesystem sync as backup:** Configure filesystem sync (Target 2) to a second location as a backup of your primary sync target: 1. Primary sync: Joplin Cloud. 2. Secondary: Filesystem to an external/cloud-synced drive. **Database backup:** The Joplin database is SQLite. On desktop, copy: - Linux/macOS: `~/.config/joplin-desktop/database.sqlite` - Windows: `%APPDATA%\Joplin\database.sqlite` > [!WARNING] > Do not copy the SQLite database while Joplin is running — you may get a corrupted backup. Close Joplin first, or use the JEX export which handles locking correctly. ### 5.20 Note Printing and PDF Export **Print a note:** 1. Open the note. 2. **File → Print** or `Ctrl+P`. 3. Choose your printer or "Save as PDF". **Export to PDF:** 1. **File → Export PDF**. 2. Choose the output file. The PDF reflects the rendered Markdown view, including images and formatting. ### 5.21 Multi-Window Mode (Desktop) Open multiple notes in separate windows: 1. Right-click a note → **Open in new window**. 2. Each window is independent, with its own editor. > [!IMPORTANT] > There is a known issue (#15106) where note focus may behave unexpectedly when multiple windows are open. If you experience focus problems, close extra windows and try again. ### 5.22 Setting Up Plugins Joplin's plugin system extends functionality with JavaScript/TypeScript plugins. **Installing plugins:** 1. Go to **Tools → Options → Plugins**. 2. Browse the plugin directory or search by name. 3. Click **Install**. 4. Restart Joplin. **Popular plugin categories:** | Category | Examples | |----------|---------| | Editors | Rich Markdown, Inline TODO | | Productivity | Note Tabs, Quick Links | | Integration | GitHub, Todoist, Calendar | | Appearance | Custom themes, Font size | | Tools | Backup, Kanban, Templates | **Plugin specifications:** - Plugins are JavaScript bundles with a `manifest.json`. - Plugin IDs must be 16-256 characters, starting and ending with a letter or number. - Plugins access the Joplin API through `JoplinData` (note/folder/tag CRUD) and `JoplinImaging` (image manipulation). - Plugins can register content scripts, custom dialogs, menu items, and CodeMirror editor extensions. ### 5.23 Using Content Scripts Content scripts are plugin-provided scripts that run within the note viewer or editor: - **Markdown-it plugins:** Extend Markdown rendering (custom syntax, diagrams). - **CodeMirror plugins:** Extend the code editor (custom commands, key bindings). ### 5.24 Working with Large Attachments **Attachment size considerations:** - Large files (videos, archives) sync fine but increase sync time. - Use `sync.resourceDownloadMode: manual` on devices with limited storage. - S3 sync targets handle large attachments best due to chunked uploads. **Optimizing images:** - Joplin does not resize images on import — resize before attaching if size is a concern. - OCR processing time increases with image resolution. ### 5.25 Using Joplin on Multiple Devices **Recommended workflow:** 1. Set up the same sync target on all devices. 2. If using E2EE, enter the master password on each device. 3. Let each device complete a full initial sync before making edits. 4. Avoid editing the same note simultaneously on two devices — conflict notes may be created. **Conflict resolution:** When two devices edit the same note offline: - Joplin keeps both versions. - A "Conflicts" notebook appears with the alternate version. - Manually merge the two versions and delete the conflict note. ### 5.26 Using the CLI as a Daily Driver The CLI offers a complete TUI experience: ```bash # Launch the TUI joplin # Navigation within TUI: # - Tab: switch between sidebar, note list, editor # - Arrow keys: navigate lists # - Enter: open a note # - q: quit (from sidebar) ``` **Scriptable CLI workflows:** ```bash # Quick-capture a note from the terminal joplin mknote "$(date): Quick thought" # List all notes in a notebook joplin use "Work" joplin ls # Search and display joplin search "meeting" # Dump note content to stdout joplin cat "Note Title" # Sync and exit joplin sync ``` ### 5.27 Configuring Keyboard Shortcuts View and customize keybindings: **Desktop:** 1. **Tools → Options → Keyboard Shortcuts**. 2. Click a command, press the desired key combination, click **Save**. **CLI:** ```bash # View current keymap joplin keymap ``` Custom keymaps override default bindings. Changes take effect immediately without restart. ### 5.28 Email-to-Note (Joplin Cloud) Joplin Cloud subscribers can forward emails to a unique email address that creates notes automatically: 1. Go to the Joplin Cloud web dashboard. 2. Find your unique email-to-note address. 3. Forward any email to that address. 4. The email appears as a new note on next sync. ### 5.29 Geolocation Workflows **Travel journaling:** 1. Enable geolocation on mobile. 2. Create notes at each location — GPS coordinates are saved automatically. 3. Search notes by location: ``` latitude:48 longitude:2 ``` This finds notes created near Paris (48N, 2E). **View on map:** Click the geolocation coordinates in note properties to open the location in Google Maps, OpenStreetMap, or your configured maps application. ### 5.30 Restoring Deleted Notes Deleted notes go to the Trash notebook: 1. Open the **Trash** notebook in the sidebar. 2. Find the deleted note. 3. Right-click → **Restore**. The note returns to its original notebook. If the original notebook was also deleted, the note restores to the root level. **CLI restore:** ```bash joplin restore "Deleted Note Title" ``` **Permanent deletion:** To permanently delete notes from Trash, right-click → **Delete permanently**. This action is irreversible. > [!CAUTION] > Emptying the Trash permanently deletes all notes in it. There is no undo for permanent deletion, and the notes cannot be recovered from sync targets after the next sync completes. ### 5.31 Table of Contents Insert a table of contents into any note by placing the `[[toc]]` tag. Joplin automatically generates a linked table of contents from all headings in the note. ```markdown [[toc]] # Section 1 Content here... ## Section 1.1 More content... # Section 2 Even more content... ``` The table of contents updates automatically as you add or modify headings. ### 5.32 Note Linking and Wiki-Style Navigation Build a personal wiki by linking notes together: 1. **Create a hub note** that serves as your index or dashboard. 2. **Link to topic notes** using the Markdown link syntax: ```markdown # Knowledge Base ## Development - [Python Tips](:/{python_tips_id}) - [Docker Cheatsheet](:/{docker_cheat_id}) - [Git Workflows](:/{git_workflows_id}) ## Projects - [Project Alpha Status](:/{alpha_id}) - [Project Beta Roadmap](:/{beta_id}) ``` 3. **Back-link** from topic notes to the hub for easy navigation. 4. Use a **Backlinks plugin** for automatic bi-directional link discovery. ### 5.33 Daily Notes and Journaling **Set up a daily notes workflow:** 1. Create a "Journal" notebook. 2. Use a template with date variables: ```markdown # {{date}} — Daily Log ## Tasks - [ ] ## Notes ## Gratitude ``` 3. Each morning: **File → New note from template → Daily Log**. 4. Sort the Journal notebook by `user_created_time` to see entries chronologically. ### 5.34 Using Joplin for Meeting Notes **Meeting note template:** ```markdown # Meeting: {{date}} **Attendees:** **Agenda:** ## Discussion Points 1. ## Action Items - [ ] @person — task — due date ## Decisions Made - ## Follow-up - Next meeting: ``` After the meeting, tag the note with the project name and attendee names for easy retrieval. ### 5.35 Code Snippet Management Use Joplin as a code snippet library: 1. Create a "Snippets" notebook. 2. Create notes for each language or topic. 3. Use fenced code blocks with language tags for syntax highlighting: ````markdown # Python — File Operations ## Read a file ```python with open('file.txt', 'r') as f: content = f.read() ``` ## Write JSON ```python import json with open('data.json', 'w') as f: json.dump(data, f, indent=2) ``` ```` 4. Tag with the programming language for quick filtering: `tag:python`, `tag:javascript`. 5. Search with `notebook:Snippets tag:python` to find Python snippets. ### 5.36 Clipping Research from the Web **Research workflow with Web Clipper:** 1. Clip articles with **Simplified page** mode (strips ads and navigation). 2. Use a consistent tag scheme: `research`, `topic-name`, `source-type`. 3. Add your own annotations at the top of the clipped note. 4. The source URL is preserved automatically in note properties. 5. Search clipped content later with `sourceurl:example.com` or by tag. ### 5.37 Collaborative Workflows (Joplin Cloud/Server) **Team knowledge base:** 1. Create a shared notebook (Joplin Cloud or Server required). 2. Invite team members with **Can edit** permission. 3. Everyone syncs the shared notebook alongside their private notebooks. 4. Use tags consistently for cross-team discoverability. 5. Publish important notes as public links for external stakeholders. **Limitations:** - Real-time collaboration (Google Docs-style) is not supported — changes sync on intervals. - Conflicts can arise from simultaneous edits (see Section 5.25 for resolution). ### 5.38 Exporting for Publishing **Export to blog or website:** 1. Write your post in Joplin with standard Markdown. 2. Export as Markdown (**File → Export → Markdown**). 3. Copy the `.md` file to your static site generator (Hugo, Jekyll, Gatsby, etc.). 4. Images export to `_resources/` — update paths as needed. **Export to HTML for email:** 1. Export as HTML. 2. Open the HTML file. 3. Copy the rendered content into your email client. ### 5.39 Automating with Cron Jobs **Automated daily backup:** ```bash # crontab entry: backup every night at 2 AM 0 2 * * * /usr/local/bin/joplin export /backup/joplin-$(date +\%Y\%m\%d).jex --format jex ``` **Automated sync:** ```bash # Sync every 30 minutes */30 * * * * /usr/local/bin/joplin sync >> /var/log/joplin-sync.log 2>&1 ``` > [!WARNING] > Automated CLI sync must not run while the TUI or desktop app is active — only one process should access the Joplin database at a time. Schedule cron jobs for times when the interactive app is closed. ### 5.40 Portable Installation on USB 1. Download the portable release for your OS. 2. Extract to a USB drive. 3. Set the `PORTABLE_EXECUTABLE_FILE` environment variable to the Joplin executable path. 4. Launch Joplin — all data stores next to the executable on the USB drive. 5. Configure filesystem sync (Target 2) pointing to a directory on the same USB drive for a fully self-contained setup. --- ## 6. Troubleshooting ### 6.1 Sync Not Working **Symptoms:** Notes do not appear on other devices; sync button shows errors. **Solutions:** 1. **Check connectivity:** Ensure the device has internet access and can reach the sync target. 2. **Verify credentials:** Re-enter username and password in sync settings. 3. **Check sync target URL:** Ensure the URL is correct and includes the full path (e.g., Nextcloud needs `/remote.php/webdav/Joplin`). 4. **Test configuration:** Use the "Check synchronisation configuration" button in sync settings. 5. **Reduce concurrent connections:** Lower `sync.maxConcurrentConnections` from 5 to 1 and try again. 6. **Check logs:** **Help → Toggle development tools → Console** (desktop) or `joplin status` (CLI). 7. **Re-sync from scratch:** Delete the local sync state (not your notes) and force a full re-sync. ### 6.2 Encryption Errors **"Cannot decrypt item":** - You need the master password. Go to **Tools → Options → Encryption** and enter it. - If you changed your master password, all devices need the new password. - Old encrypted notes remain encrypted with the old key — supply both passwords if prompted. **"Master key not loaded":** - The master key file may be corrupted. Re-enter the password. - If the master key was created on another device, sync first to receive it. ### 6.3 Missing Notes After Sync **Notes exist on one device but not another:** 1. Ensure both devices sync to the same target. 2. Complete a full sync on the source device first. 3. Wait for the sync to finish on the destination device (large libraries take time). 4. Check the Conflicts notebook for duplicates. **Notes disappeared entirely:** 1. Check the Trash notebook. 2. Check the Conflicts notebook. 3. Look at note history for recovery. 4. If using filesystem sync, check the sync directory directly. ### 6.4 App Won't Start **Desktop:** 1. Reset the window state: delete `window-state.json` from the data directory. 2. Delete the cache folder (`Cache/` in the data directory). 3. Rename the database file to force a re-sync (keep a backup). 4. On Linux, ensure FUSE is installed for AppImage. **Data directory locations:** - Windows: `%APPDATA%\Joplin` - macOS: `~/.config/joplin-desktop` - Linux: `~/.config/joplin-desktop` ### 6.5 Performance Issues **Slow with many notes:** - Disable `showNoteCounts` if you have thousands of notebooks. - Set `sync.resourceDownloadMode` to `manual` to avoid downloading all attachments. - Disable OCR if not needed — it processes every image in the background. - Close unused plugins — each adds overhead. **Slow sync:** - Reduce `sync.maxConcurrentConnections` if the server throttles connections. - Switch to a faster sync target (S3 or Joplin Server handle large libraries best). - Use Joplin Cloud or Joplin Server rather than Dropbox/OneDrive for note-heavy accounts. ### 6.6 Web Clipper Not Connecting 1. Ensure Joplin desktop is running. 2. Enable the Web Clipper service: **Tools → Options → Web Clipper → Enable Web Clipper Service**. 3. Check that port 41184 is not blocked by a firewall or antivirus. 4. Restart Joplin desktop and the browser. 5. Reinstall the browser extension. ### 6.7 Mobile App Issues **Scrolling/rendering issues (known issue #15141):** Some users experience rendering glitches on mobile. Current workarounds: - Restart the mobile app. - Toggle between editor and viewer modes. - Clear the app cache (Android: Settings → Apps → Joplin → Storage → Clear Cache). **Sync issues on mobile:** - Background sync may be killed by the OS battery optimizer. Add Joplin to the battery optimization exclusion list. - On iOS, background refresh must be enabled in Settings. ### 6.8 Search Crashes (Known Issue #13322) If search crashes with an older profile: 1. Back up your data (JEX export). 2. Delete the search index: remove `search.sqlite` from the data directory. 3. Restart Joplin — the index rebuilds automatically. 4. If the crash persists, try upgrading to the latest version. ### 6.9 OCR Not Working **OCR stops after processing a few resources (known issue #14805):** - Restart Joplin to resume processing. - Check that `ocr.enabled` is still on after restart. - Verify the `ocr.languageDataPath` is accessible. - For handwritten text recognition, ensure you have a Joplin Server or Cloud connection — the `ocr.handwrittenTextDriverEnabled` setting requires server-side processing. ### 6.10 Image Context Menu Missing "Cut" (Known Issue #13895) The right-click context menu on images does not include a "Cut" option. Workaround: 1. Use "Copy" instead. 2. Delete the original image. 3. Paste at the new location. ### 6.11 OneNote Import Hangs (Known Issue #15132) The OneNote importer may hang during the postprocessing stage: 1. Allow extra time — processing can take much longer than the initial import. 2. If it genuinely hangs (no CPU/disk activity for 10+ minutes), force-close Joplin and try importing a smaller export. 3. Convert the OneNote notebook to PDF first, then clip or attach the PDF as an alternative. ### 6.12 Plugin Compatibility Issues **Plugin causes crashes or errors:** 1. Start Joplin in safe mode: **Help → Toggle safe mode** (or rename the plugins directory temporarily). 2. Disable plugins one at a time to identify the offending plugin. 3. Update the plugin or report the issue to the plugin developer. 4. Rollback: delete the plugin from the `plugins/` directory in the data folder. ### 6.13 Database Errors **"Database is locked" or "SQLITE_BUSY":** - Only one instance of Joplin should access the database at a time. - Close any other Joplin processes. - On shared filesystems (NFS, network drives), ensure only one device accesses the database file directly. **"Database disk image is malformed":** 1. Close Joplin. 2. Back up the database file. 3. Run SQLite integrity check: ```bash sqlite3 database.sqlite "PRAGMA integrity_check;" ``` 4. If corrupted, export via JEX (if possible) and reimport into a fresh profile. 5. Alternatively, delete the database and re-sync from the sync target. ### 6.14 Markdown Rendering Issues **Notes look different between desktop and mobile:** - The desktop and mobile renderers have minor differences. Stick to standard Markdown for maximum compatibility. - Custom CSS (`userstyle.css`) only applies to the desktop. **Math (KaTeX) not rendering:** - Ensure the math plugin is enabled (it is built-in). - Use `$...$` for inline and `$$...$$` for block math. - Complex LaTeX commands may not be supported — KaTeX covers a subset of LaTeX. ### 6.15 External Editor Not Working **The external editor does not launch:** 1. Check the `EDITOR` environment variable is set correctly. 2. The editor must support being launched from the command line. 3. For GUI editors, use the `--wait` flag: `export EDITOR="code --wait"` or `export EDITOR="subl --wait"`. 4. On Windows, ensure the editor is in your `PATH`. ### 6.16 Proxy Issues **Behind a corporate proxy:** 1. Set proxy environment variables before launching: ```bash export https_proxy=http://proxy.corp.com:8080 export http_proxy=http://proxy.corp.com:8080 joplin ``` 2. For authenticated proxies: `export https_proxy=http://user:[email removed]:8080` 3. Some sync targets (OneDrive, Dropbox) may not work through proxies that intercept HTTPS. Use Joplin Server or WebDAV instead. ### 6.17 Attachment Download Failures **"Resource not downloaded" errors:** 1. Check your internet connection. 2. Verify the sync target is accessible. 3. Switch `sync.resourceDownloadMode` to `always` temporarily. 4. Run a full sync. 5. Check that the resource exists on the sync target (especially if switching between targets). ### 6.18 Desktop Notifications Not Working **Alarms/reminders do not appear:** - Ensure desktop notifications are enabled in your OS settings. - Joplin must be running (not just minimized to tray). - On Linux, ensure `libnotify` is installed: `sudo apt install libnotify-bin`. - Check that the alarm time is set correctly (timezone matters). ### 6.19 High Memory Usage **Joplin consuming excessive RAM:** 1. Disable unused plugins — each plugin runs in its own process. 2. Close the note viewer pane (use Editor-only layout) for very large notes. 3. Reduce the number of open windows (multi-window mode uses more memory). 4. Clear the cache: delete the `Cache/` directory. ### 6.20 Sync Conflict Resolution **Many notes in the "Conflicts" notebook:** 1. Open each conflict note. 2. Compare with the original (the non-conflict version in its original notebook). 3. Merge changes manually. 4. Delete the conflict note. 5. To prevent future conflicts: sync before and after editing, and avoid editing the same note on multiple devices simultaneously. ### 6.21 Cannot Find Notes **Notes seem to have vanished:** 1. Use global search (`Ctrl+G` / `F6`) — it searches across all notebooks. 2. Check if a filter is active (tag filter, notebook filter). 3. Look in the Trash notebook. 4. Look in the Conflicts notebook. 5. Check the "All Notes" view (click the notebook header in the sidebar). 6. If using E2EE, ensure all master keys are loaded — encrypted notes may not appear in search. ### 6.22 Portable Mode Issues **Data stored in wrong location:** - On Windows, portable mode activates when `PORTABLE_EXECUTABLE_FILE` is set. - On Linux AppImage, `APPIMAGE` is set automatically. - Data is stored next to the executable in portable mode. - If switching between portable and installed modes, your data will be in different locations. ### 6.23 SSL Certificate Errors **When syncing with self-hosted servers:** 1. Ensure the server has a valid SSL certificate. 2. For self-signed certificates, Joplin may not connect. Use a proper certificate (e.g., Let's Encrypt). 3. On some platforms, adding the CA certificate to the system trust store resolves the issue. ### 6.24 Command-Line Sync Automation **Automate sync via cron:** ```bash # Sync every 30 minutes */30 * * * * /usr/local/bin/joplin sync >> /var/log/joplin-sync.log 2>&1 ``` > [!CAUTION] > The CLI `sync` command must not run while the TUI or desktop app is also running — only one process should access the database at a time. Schedule automated sync for periods when no interactive instance is active. ### 6.25 Data Recovery from Sync Target If all local data is lost: 1. Install a fresh copy of Joplin. 2. Configure the same sync target. 3. Sync — all notes download from the sync target. 4. If E2EE was enabled, enter the master password when prompted. 5. Attachments download according to `sync.resourceDownloadMode`. ### 6.26 Slow Initial Sync **First sync taking hours:** - This is normal for large libraries with many attachments. - Set `sync.resourceDownloadMode` to `manual` during initial sync to skip attachment downloads. Switch back to `always` or `auto` afterward. - Increase `sync.maxConcurrentConnections` (up to 20) if the sync target can handle it. - Use a wired connection instead of Wi-Fi for the initial sync. ### 6.27 "Too Many Requests" Errors Cloud sync targets (OneDrive, Dropbox, Joplin Cloud) may rate-limit frequent requests: 1. Reduce `sync.maxConcurrentConnections` to 1 or 2. 2. Wait a few minutes and try again. 3. For persistent issues, increase the sync interval to reduce request frequency. --- ## 7. FAQ ### General **Q1: Is Joplin free?** Yes. Joplin is free and open source (AGPL-3.0 for the apps / MIT for libraries). The desktop, mobile, and CLI apps are free. Joplin Cloud is a paid service for sync and sharing, but you can use free alternatives (Nextcloud, Dropbox, OneDrive, filesystem, etc.). **Q2: What format are notes stored in?** Markdown. Notes are plain text Markdown files with metadata. Attachments are stored as separate resource files referenced by ID. **Q3: Can I access my notes without Joplin?** Yes. Export to Markdown (**File → Export all → Markdown**) to get plain `.md` files. You can also read the SQLite database directly or access the sync target files (though they are in Joplin's internal format). **Q4: Is Joplin available in my language?** Joplin supports dozens of languages via community translations. Set the locale in **Tools → Options → General → Language**. If your language is missing or incomplete, you can contribute translations on GitHub. **Q5: Can I use Joplin offline?** Yes. Joplin is an offline-first application. All notes are stored locally. Sync is optional and only needed for multi-device access. **Q6: What platforms does Joplin support?** Windows, macOS, Linux (desktop via Electron), Android, iOS (mobile via React Native), and any platform with Node.js (CLI). The Web Clipper extension supports Chrome, Firefox, and Chromium-based browsers. **Q7: How do I check my Joplin version?** Desktop: **Help → About Joplin**. CLI: `joplin version`. The version number is also shown in the title bar. ### Notes & Editing **Q8: Can I use HTML in notes?** Yes. Joplin supports mixed Markdown and HTML. You can also import HTML notes directly. The `editor.enableHtmlToMarkdownBanner` setting offers to convert HTML notes to Markdown. **Q9: What Markdown flavour does Joplin use?** GitHub-flavoured Markdown (GFM) with extensions for KaTeX math, checkboxes, highlighted text, and Joplin-specific link syntax. **Q10: Can I embed videos in notes?** Attach video files like any other resource. They render as a download link. For embedded playback, use an HTML `