MarkEdit-preview: Markdown view modes as a MarkEdit extension

What MarkEdit-preview solves, and who it is for

MarkEdit is a macOS Markdown editor built around a CodeMirror editing surface. The editor itself is a text view; MarkEdit-preview is the companion extension that adds rendered views on top of it. The README describes it as "Markdown view modes for MarkEdit that leverage markedit-api," which places it firmly in the extension layer rather than the core app.

The audience is narrow and specific. You need to be on macOS, you need MarkEdit installed, and you need to want a rendered view of the same document you are typing. If any of those three is false, this project is not aimed at you. There is no Windows build, no Linux build, no standalone binary, and no web version. The repository is TypeScript that compiles to a single script loaded by the host application.

The value proposition is the mode list. Rather than a single preview toggle, the extension exposes four modes ordered by ID: edit (Markdown Source), side-by-side, preview (Overlay), and syntax-hidden (Mixed). The side-by-side mode puts the rendered output next to the source. The overlay mode covers the editor with the rendered view. The mixed mode hides syntax and can optionally replace image links with inline images through the inlineImages setting. That spread of modes is the actual product; the rendering itself is markdown-it plus github-markdown-css, both of which you could wire up yourself if you wanted to spend the afternoon.

How the extension renders and where the HTML goes

The build produces a script that MarkEdit loads as an extension. Inside the host, the extension registers view modes and hooks into the editor through markedit-api, the interface package pinned in devDependencies as a GitHub URL at tag v0.35.0. Rendering goes through markdown-it, with the preset and options overridable from settings. Styling comes from github-markdown-css, and the preview pane carries the markdown-body CSS class, so custom CSS targets that selector.

The extension also exposes two global functions to the surrounding script environment: MarkEditGetHtml(styled: boolean) => Promise<string> and MarkEditRenderHtml(markdown: string, styled: boolean) => Promise<string>. The first renders the current document; the second renders arbitrary Markdown passed in as a string. Both are promises and both take a styled flag that decides whether the output carries the GitHub styling. That is the extension's public surface for other scripts, and it is the part most likely to be useful outside the preview pane itself. A script that needs rendered HTML for export, for a custom panel, or for feeding another tool can call these instead of reimplementing a Markdown pipeline.

Two optional rendering features sit behind the lite build boundary. Syntax highlighting with automatic language detection (syntaxAutoDetect) and KaTeX math rendering with configurable delimiters (mathDelimiters) are both marked "not applicable for lite build" in the README. If you build with yarn build:lite, you get a smaller script and lose those two capabilities. The full build runs lint first, then vite build, then removes the previously deployed script from the MarkEdit group container before copying the new one in.

Installing MarkEdit-preview and switching modes for the first time

The README gives one supported install path: the MarkEdit Extension Registry at https://markedit-app.github.io/extensions/#markedit-preview. There is no Homebrew formula documented in the repository, and no npm package published for end users; the package.json name is markedit-preview but the install instructions do not route through a registry. Follow the registry page.

If you are building from source instead, the repository expects yarn. The README states that yarn install && yarn build builds and deploys the script, and that yarn build:lite produces the lite version. The build script also deletes the previously deployed copy from the shared scripts directory before deploying, so a rebuild replaces rather than duplicates.

yarn install && yarn build

After installing, the README says to choose a mode from Extensions > View Mode, or to press Shift-Command-V to cycle through modes. The default hotkey lives in the changeMode.hotKey setting, which defaults to key V with the Command modifier. Note that the README writes the shortcut as Shift-Command-V while the default settings block lists only Command as the modifier; check the actual menu binding in your build rather than trusting either line alone.

To change the mode order or the shortcut, define the extension.markeditPreview node in settings.json. This is the default block from the README:

{
  "extension.markeditPreview": {
    "syncScroll": true,
    "hidePreviewButtons": true,
    "syntaxAutoDetect": false,
    "imageHoverPreview": false,
    "inlineImages": false,
    "themeName": "github",
    "styledHtmlColorScheme": "auto",
    "mathDelimiters": [],
    "changeMode": {
      "modes": ["edit", "side-by-side", "preview", "syntax-hidden"],
      "hotKey": { "key": "V", "modifiers": ["Command"] }
    },
    "markdownIt": { "preset": "default", "options": {} }
  }
}

If you drop both editor modes from changeMode.modes, the README states that edit is added automatically, so you cannot lock yourself out of the source view entirely. For local images to appear, the README requires MarkEdit 1.24.0 or later plus the folder-access grant described in the MarkEdit customization wiki. Quick Look preview support requires MarkEdit 1.33.0 or later.

Scroll sync is one-way, and that is the main limitation

The syncScroll setting is described as "whether to enable scroll synchronization," and the community extensions section makes the direction explicit. The Bidirectional Preview Sync extension by @Nigelw is described as replacing "MarkEdit-preview's one-way editor→preview sync." So the built-in behaviour is editor to preview only: scrolling the source moves the preview, and scrolling the preview does not move the source. For a long document where you are reading the rendered output and want to jump back to the corresponding source line, that asymmetry is the thing you will notice first.

The remedy is another extension, which is worth saying plainly because it means the core preview feature is not self-sufficient for reading-heavy workflows. Installing Bidirectional Preview Sync is a second dependency with its own maintenance schedule. The README does not document what happens when the two extensions disagree, and it does not describe any fallback if the community extension stops working against a newer MarkEdit release.

The lite build is the second constraint. Choosing yarn build:lite removes syntax highlighting with automatic detection and KaTeX math rendering, and also removes the preview button hiding behaviour, since hidePreviewButtons is marked "not applicable for lite build." If your Markdown contains math or fenced code in languages you want highlighted, the lite build is the wrong target. The README does not explain the size difference or name a use case for lite, which leaves the choice to you.

A third boundary is platform. Everything here assumes macOS and MarkEdit. The themeName setting accepts "none" to disable preview styling and render raw HTML, which is a useful escape hatch when the GitHub styles fight your document, but it is not a substitute for a renderer you control.

MarkEdit-preview compared with a general Markdown renderer

The obvious alternative is a standalone Markdown tool such as a static site generator, a pandoc pipeline, or a browser-based previewer. The difference is architectural, not cosmetic. A standalone renderer takes a file path, produces output, and exits. MarkEdit-preview lives inside a running editor process, holds a reference to the open document, and re-renders as you type. That is why it can offer syncScroll at all, and why it can expose MarkEditGetHtml against the current document without you saving first.

The cost of that architecture is that the extension cannot exist without MarkEdit. You cannot run it in CI, you cannot call it from a shell script, and you cannot use it to convert a directory of files. If your need is batch conversion, a command-line renderer is the right tool and this extension is the wrong one. The two functions it exposes are globals inside MarkEdit's script environment, not a published API you can import from Node.

Within the MarkEdit ecosystem, the other comparison point is the Direct Preview extension by @Squarelight-ai, which the README describes as "a setup helper that provides a one-click setup for a two-mode Edit/Preview toggle by configuring the toolbar item and changeMode.modes for you." That is a configuration convenience layered on the same mechanism, not a different renderer. If you find the four-mode cycle more than you want, Direct Preview narrows it to two modes without you editing settings.json by hand. Neither is a substitute for the other; one configures, one renders.

Licence, maintenance and what an upgrade costs

The repository carries the MIT licence, and package.json declares "license": "MIT". For most users that means you can read, modify and redistribute the extension, including in commercial settings, provided you keep the copyright and permission notice. It does not grant rights to the MarkEdit application itself, which lives in a separate repository, and it does not cover the bundled dependencies. markdown-it, KaTeX, mark.js, js-yaml and github-markdown-css each ship under their own terms; if you redistribute a build, check those separately. Nothing here is legal advice.

The last push to the default branch was on 2026-08-20, and the most recent release in the listing is v1.10.0 on the same date, with v1.9.0 on 2026-08-07 and v1.8.1 on 2026-06-24. The repository is not archived. That pattern shows a project still receiving releases, but the README does not publish a support policy, a deprecation window, or a compatibility matrix beyond the two MarkEdit version floors it mentions (1.24.0 for local images, 1.33.0 for Quick Look).

Upgrade cost depends on how you installed it. Through the extension registry, an update is a registry operation and the extension's own settings node survives in settings.json. Built from source, you re-run yarn install && yarn build, and the build script removes the old deployed script from the group container before writing the new one. The markedit-api and markedit-vite dependencies are pinned to GitHub tags (v0.35.0 and v0.5.0 respectively) rather than semver ranges, so a rebuild will not silently pull a newer API. That pinning is a deliberate stability choice, and it also means you get API updates only when someone edits package.json.

Editorial conclusion

Adopt MarkEdit-preview if you already edit Markdown in MarkEdit on macOS and want a preview pane without leaving the editor; the extension registry install is the intended path, and the MIT licence keeps redistribution simple. Do not adopt it if you need a cross-platform editor, a standalone renderer, or a preview that survives without MarkEdit running. Before relying on it, verify your MarkEdit version supports the extension (1.24.0 or later for local images, 1.33.0 or later for Quick Look), confirm the mode order and hotkey you want in the extension.markeditPreview node of settings.json, and check whether the one-way editor-to-preview scroll sync is enough or whether you need a community extension for bidirectional sync.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes