Skip to main content

Twain

Twain is a native macOS viewer for Markdown (.md) and MDX (.mdx) files. It gives you real Finder Quick Look previews, a fast in-app reader, and an optional editor, all driven by an offline rendering pipeline. No document content is ever uploaded, and no code in a document is ever executed. Remote images do load by default, so opening a document that references one contacts that host; turn off Load Remote Images in the reading settings to block them. Quick Look always blocks them, with no setting.

It is built for people who keep documentation, notes, and READMEs as files on disk: developers reading a repository's Markdown, writers working in MDX outside a dev server, and anyone who wants a proper desktop reader instead of a browser tab or a raw text editor.

What it does​

  • Renders Markdown and MDX safely. GitHub Flavoured Markdown, footnotes, tables, task lists, frontmatter, syntax highlighting, maths (KaTeX) and diagrams (Mermaid) all render offline. MDX components become formatted HTML or clearly labelled placeholders, and no JavaScript from a document runs. See Markdown and MDX.
  • Previews in Finder. Press the spacebar on a .md or .mdx file and Twain draws the same rendered preview you get in the app, except that Quick Look always blocks remote images. See Quick Look previews.
  • Reads comfortably. Choose a light or dark appearance, a serif or sans-serif font, a text size and page zoom, and a reading width: a fixed measure, full width, or a margin you drag on a ruler. Jump around with a live table of contents. See Reading settings.
  • Opens a diagram properly. Click a Mermaid diagram to open it over the window, then pan and zoom it. Zooming redraws the vectors rather than magnifying pixels. See Diagrams.
  • Works across a whole folder. Open a project folder to get a file tree, full-text search, a broken-link check, and review notes anchored to the source. See Projects.
  • Edits, when you want it. An optional editor writes back to the original file: a block editor on the rendered page for Markdown, and a highlighted source mode for both formats. Each block says what it is and what it could become, tables get row and column controls, and a code fence keeps the language its author wrote. See The editor.
  • Keeps its own history. Twain records a local revision every time a document is saved or changed underneath you, independently of Git, and keeps 30 days by default. You can read any revision and diff against it; restoring one back to the file uses the editor.
  • Talks to your other tools. A command-line tool, a read-only MCP server, and a VS Code / Cursor extension share the same render pipeline. The command line and MCP builds run without a browser, so Mermaid diagrams stay as code blocks there. See Tools.

Free and Pro​

The Markdown and MDX viewer is free and stays free. That includes rendering, all three view modes, find-in-document, reading appearance and text size, the table of contents, the document diagnostics panel, and the Show Changes diff, including the one-click diff when something else rewrites the document you have open. Snippets and the spelling, grammar and style checks sit in the Format menu and are only available while editing, so they need Pro, and folder-wide search needs Pro folder mode. The Compared to Git HEAD baseline ships in the direct download only, not in the Mac App Store build.

Twain Pro is a one-time purchase that unlocks the editor, Version History, review notes and the agent brief, PDF and HTML export, printing, folder mode, the Sepia and High Contrast reading themes, and presentation mode. A 7-day trial unlocks everything. See Twain Pro for the full split.

System requirements​

  • macOS 14 (Sonoma) or later
  • Apple Silicon or Intel (Twain ships as a universal app)
What ships today

This documentation covers Twain 1.0.0, the first public release. It is available now as a signed, notarised direct download from twain.md, and updates arrive through the app. The Mac App Store edition has not been released yet. Everything on these pages describing the direct download applies today; the pages that also describe the store edition say where it stands. See Editions.

Where to start​