Troubleshooting

Images Not Accessible

If images in your markdown files show a "Grant permission to view" or "Can't find image" placeholder, Peekdown needs permission to access the folder containing those images.

Peekdown runs in a secure macOS sandbox, which means it can only access files and folders you've explicitly granted permission to.

To fix this:

  1. Open Settings > Folders
  2. Toggle on access to common folders (Desktop, Documents, Downloads), or
  3. Click Add Folder… to grant access to a specific location

The preview reloads automatically once access is granted.

Images Not Showing in Quick Look

If images appear broken or missing when previewing a markdown file with Quick Look (pressing Space in Finder), this is a macOS limitation — not a Peekdown bug.

Quick Look extensions run in a restricted sandbox that only has access to the file being previewed. The extension cannot read other files on disk, so local images referenced with relative paths (like ![photo](./images/photo.png)) cannot be loaded.

This restriction is enforced by macOS and applies to all Quick Look extensions — Peekdown cannot work around it. To see images rendered correctly, open the file in Peekdown.

Imported Annotations Not Appearing

If you imported an annotations file but the annotations don't appear, try closing and reopening the document. Imported annotations are saved to Peekdown's internal storage and should restore automatically when the file is reopened.

If you're trying to import annotations that were exported from an older version of Peekdown (.peekdown files), rename the file to use a .json extension first — the format is the same, only the file extension has changed.

"Would Like to Access Data from Other Apps"

When you close a file that has annotations, macOS may show an alert saying "Peekdown.app would like to access data from other apps." This is a standard macOS privacy prompt, not an error.

Why this appears: Peekdown saves annotations to a shared container so the Quick Look extension can display them when you preview files in Finder. macOS Sequoia (15.0+) treats this shared container access as inter-app data sharing and shows a one-time permission prompt.

Allow (recommended): Quick Look previews will show your annotations. This prompt only appears once.

Don't Allow: The main app continues to work normally. The only effect is that Quick Look previews will not display annotations.

To change this later: Open System Settings > Privacy & Security > App Data and toggle access for Peekdown.

Changes Not Saving

If your changes aren't saving, the file may be read-only or in a protected directory:

  • Check the file's permissions in Finder: right-click the file, select Get Info, and look at Sharing & Permissions
  • Make sure you have write access to the file
  • Try saving to a different location with File > Save As

Preview Doesn't Match GitHub

Peekdown renders standard GitHub-Flavored Markdown (GFM), but GitHub applies additional processing for things like @mentions, issue links, and repository-specific features. For pure markdown content, the rendering should be identical.

Peekdown does not support GitHub-specific extensions like Mermaid diagrams or math expressions (LaTeX).

Text Size

If text appears too small or too large:

  • ⌘+ to zoom in
  • ⌘− to zoom out
  • ⌘0 to reset to default size

Zoom level is remembered per window.

Privacy

Peekdown is completely offline. It never connects to the internet — all markdown rendering happens locally on your Mac.

  • Your files are read and written directly on disk
  • Preferences are stored locally via macOS defaults
  • No cloud sync, no accounts, no telemetry
  • No data is collected or transmitted