Skip to main content

Troubleshooting

Quick Look previews do not appear​

Pressing the spacebar on a Markdown file shows nothing, or shows another app's preview.

  • Make sure Twain is in your Applications folder. The Quick Look extension only works from there.
  • Make Twain the default handler for the file type, with Twain ▸ Set as Default Markdown Viewer….
  • If the preview appears but does not look like Twain, another app's extension is drawing it. macOS picks the preview extension separately from the default app, so owning the file type does not settle it. Open Twain ▸ Settings ▸ Quick Look to see which other apps claim the same types, then Open Quick Look Extension Settings… and switch theirs off.

See Quick Look previews.

Local images are missing in a Quick Look preview​

A document that references a local image shows a broken-image placeholder in the Finder preview.

This is expected. macOS runs the Quick Look extension in a sandbox, and whether it may read a file sitting beside the document is decided per file, so a local image usually cannot be read. Open the document in the app to see the image. On the Mac App Store edition the app is sandboxed too: opening a single file does not grant its folder, so sibling images appear only once you have opened the enclosing folder with File ▸ Open Folder…, which needs Twain Pro. The direct download reads sibling images straight away. See Quick Look previews and Editions.

A Pro feature is locked​

Editing, export, printing, folder mode, presentation mode, and the Sepia and High Contrast themes need Twain Pro. Start the 7-day trial from Twain ▸ Enter License…, or enter a licence key you already have. The trial can be started once: while it runs the panel shows the days remaining instead of the button, and once it has run out the button does not come back. The free viewer is unaffected either way.

Show Changes says "Not tracked in Git"​

The Compared to Git HEAD baseline is offered by the direct download only, because the App Store sandbox does not allow running git. Where it is offered, it needs the file to be inside a Git repository with at least one commit. If the file is untracked, not in a repository, or the repository has no commits, there is nothing to compare against. Use the Since Last Save baseline instead, or commit the file first. See Showing changes.

The command line tool is not found​

The CLI is not yet published, so twain-md is unlikely to be on your PATH. Run it from a checkout with node cli/twain-md.mjs …, or point the VS Code extension's twain-md.cliPath setting at cli/twain-md.mjs.

Software updates​

The direct download checks for updates in the background and offers one when it finds it, and Twain ▸ Check for Updates… runs the same check on demand. Twain never downloads and installs an update by itself: accepting one is always your decision, so a future paid major version can never arrive as a silent update. Turning off the anonymous usage check-in under Settings ▸ Privacy does not stop update checks, because that is how security fixes reach you.

The Mac App Store edition has no such menu item, because the App Store delivers its updates. See Editions.

Your documents stay on your Mac​

For reassurance: Twain renders your documents on your Mac, and never sends a document anywhere. No network request is made to lay out a document. The network is used in a few places, all under your control. Two work in every edition: when you check remote links, and when a document loads a remote (https) image (on by default, switchable under Load Remote Images). The direct download adds two more: the update check, and an anonymous usage check-in. The check-in is sent at three moments (app launch, trial start, and licence activation). It reports the app version; on launch, whether Twain is running free, on trial or licensed, and during a trial which day of the 7 you are on; and on activation, a one-way tag derived from the licence key, which counts Macs per licence and cannot be traced back to the key or to you. It never sends a device identifier, your OS version, your locale, your name, your email address, or anything about your documents, and nothing it receives can affect your licence. Turn it off in Twain ▸ Settings ▸ Privacy. The Mac App Store edition sends no check-in and has no Privacy tab. See Activation is offline.