Troubleshooting and FAQ

WYSIWYG is automatically disabled for files larger than about 500 KB. The underlying editor (ProseMirror) does not handle very large documents well; keeping it on would make every keystroke noticeably slower.

Use the Plain-text view to edit the file, and Reading view to preview it. You can still split Plain with the rendered preview to write and watch the result at the same time. See split view.

If you switched to WYSIWYG, made an edit, and switched back to Plain to find that some of your formatting characters look different, this is expected. The two views agree on meaning but not on every byte. See Markdown round-trip for the full story.

The short version: *italic* may become _italic_, list indentation can shift, table padding may be redistributed, and trailing whitespace gets trimmed. Nothing about the document's structure or content changes.

If you really need byte-exact preservation (for example, a tool downstream reads your file in a fragile way), stay in the Plain-text view.

Scroll sync in split view is best-effort. On long documents with mixed content (large code blocks, tall images, complex tables), the editor and the preview will drift apart, sometimes by a screen or two.

The fastest fix is to use the outline panel to jump straight to a heading. Both panes re-align on the heading you pick, so you get back in sync immediately.

Slate watches the files you have open and the folders you have added as workspace roots. Most of the time it sees external changes within a fraction of a second. There are a few cases where it can be slower or miss events entirely.

• Network filesystems. NFS and SMB shares do not always send file-change notifications. Slate polls these as a fallback, but the delay can be a few seconds.
• Cloud sync folders that move files around. If a sync tool atomically replaces a file with a new one, the watcher sees a delete followed by a create. Slate handles this, but you may see a brief blink as the editor refreshes.
• Files outside the workspace. Only files Slate has open or files inside an added workspace root are watched. A file you opened via Open dialog gets watched; a file in some random folder that was never opened or rooted will not.

If you suspect a missed change, switching tabs away and back forces a reload check.

On Linux, Slate sometimes panics at launch with a message like:

thread 'main' panicked at ...
Failed to setup app: error encountered during setup hook:
Too many open files (os error 24)

This is almost never your regular file-descriptor limit. It is the Linux kernel's per-user inotify instance quota, controlled by fs.inotify.max_user_instances. Slate needs one inotify instance to notice when files change on disk; long-running apps like VS Code, Chrome, Slack, and Dropbox each hold one or more, and the default on many distros (Ubuntu, Debian) is only 128. Once that ceiling is hit, the next app to start cannot create a watcher.

Fix. Raise the quota and reload sysctl:

echo 'fs.inotify.max_user_instances=512' \
  | sudo tee /etc/sysctl.d/40-inotify.conf
sudo sysctl --system

Then relaunch the AppImage. 512 is a generous headroom for the apps a typical desktop runs; you can go higher if you keep many editors and sync clients open.

You may also see a related ceiling, max_user_watches, when working in very large repositories (it limits how many pathsone watcher can observe, not how many watchers exist). The same file accepts both knobs:

echo 'fs.inotify.max_user_watches=524288' \
  | sudo tee -a /etc/sysctl.d/40-inotify.conf
sudo sysctl --system

Pasting an image into an untitled document embeds it as a base64 data: URL, because there is no folder to write the image to yet. A few high-resolution screenshots can balloon the file size quickly.

The fix is to save the document with a name first. Future pastes will land in an assets/ folder next to your file as real PNG (or GIF, depending on the source) files, and your Markdown will link to them by path. See pasting and dragging images.

To clean up an existing oversized file, find the long base64 strings in the plain-text view and replace them with real images, either by editing the Markdown by hand or by deleting the data URLs and re-pasting after saving.

File-tree operations in Slate are undoable. Press Cmd Z (or Ctrl Z) inside the sidebar with the tree focused to reverse the last rename, move, or trash action.

If you sent something to the trash, it is in your system trash and can be restored from there. Only the explicit Delete Permanently action (which requires holding Alt and confirming) bypasses the trash.

Slate's sidebar search has guardrails so it stays fast on huge trees. If a file is not turning up:

• Make sure it is inside one of your workspace roots. Files outside any root are not searched.
• Check whether it lives in a folder Slate skips: skipped folders.
• If you are searching contents and the file is larger than 1 MB, Slate skips its body. Search by name instead, or open the file and use Find in document.
• If the result list is at the 500-match cap, narrow your query so Slate can show the most relevant results.

Slate runs Mermaid in strict mode and then sanitizes the result. If a diagram does not render, the most common causes are:

• The fence is wrong. It must be three backticks followed by mermaid on its own line, with the diagram body underneath, and three closing backticks on a line of their own.
• The diagram uses an HTML feature that strict mode does not allow, like inline <style> blocks or foreignObject content. Stick to plain Mermaid syntax.
• The diagram has a syntax error. Mermaid surfaces an error message in place of the rendered SVG; check the message for the offending line.

Slate uses KaTeX in strict mode. Most LaTeX math works without anything special. A handful of commands are disabled because they can fire arbitrary URLs or otherwise behave outside the math sandbox; the most common one to bump into is \href.

If a block of math is not rendering:

• Confirm the delimiters: $...$ for inline, $$...$$ for block.
• For block math, the opening $$ should be on its own line.
• Check the KaTeX error message in place of the expression. It usually points right at the unknown command or mismatched brace.

If you have hit a real bug, or you want to suggest a feature, please get in touch from the contact link on the homepage. Helpful things to include:

• Your operating system and version.
• The version of Slate (under Help, About Slate).
• A short description of what you were doing.
• What you expected to happen and what happened instead.
• If you can, a small file that reproduces the issue. Markdown bug reports are dramatically easier to investigate when there is a sample.

A few things people ask about that are not in the current release:

• iOS and web builds. Both are on the roadmap; see Platforms.
• Android. Not currently planned. iOS is the mobile target.
• Cloud sync and multi-user editing. Slate works with local files only. If you want your files to live in the cloud, use a sync tool (iCloud Drive, Dropbox, OneDrive, Google Drive, Syncthing) and point Slate at the synced folder.
• Plugin marketplace. Slate does not have a third-party plugin system today.
• PDF export. HTML export is available; a styled PDF export is a likely future addition.