MarkEdit-preview: A configurable Markdown view mode extension for MarkEdit

What problem it solves and who it is for

MarkEdit-preview solves a specific gap: MarkEdit, a native macOS Markdown editor, does not ship with a built-in preview pane. This extension provides that preview, and it does so in four view modes: edit, side-by-side, overlay preview, and mixed (syntax-hidden). The intended user is someone who writes Markdown in MarkEdit and wants to see rendered output without copying text to a browser or another app. The extension is also useful for developers who build other MarkEdit extensions, because it exposes two global functions that generate HTML from the current document or from arbitrary markdown input. That makes it a building block, not just a user-facing tool. The README positions it as part of the MarkEdit ecosystem, built on the official MarkEdit API, so it is designed for that editor and nothing else.

How it works: modes, rendering, and the exposed API

The extension works by intercepting the editor's content and rendering it through markdown-it, a common Markdown parser. It then applies the github-markdown CSS for styling. The four modes are controlled by a changeMode setting that defines an ordered list of modes and a keyboard shortcut. Shift-Command-V cycles through them. The rendering pipeline is not described in detail in the README, but the presence of markdownIt.preset and markdownIt.options settings indicates that you can override the parser's preset and options directly, which gives a high degree of control over parsing behavior. The extension also exposes two global functions: MarkEditGetHtml(styled: boolean) returns rendered HTML for the current document, and MarkEditRenderHtml(markdown: string, styled: boolean) renders arbitrary markdown. This is a notable design choice: it turns the preview extension into a reusable rendering service for other extensions. The styled parameter suggests that the extension can produce both styled HTML (with the github-markdown CSS) and raw HTML, which is useful for exporting or embedding.

Getting it running: installation and build commands

The README gives two paths. For end users, you install the extension from the MarkEdit Extension Registry, which is a web page that lists extensions. There is no command-line install. For developers, the build process is straightforward: run yarn install && yarn build to build and deploy the script. There is also a lite version, built with yarn build:lite, which omits certain features (syntax auto-detect, math delimiters, hide-preview-buttons). Development tasks include yarn test for tests and yarn lint for linting, which runs automatically before build. The build output is a script that gets deployed, presumably into MarkEdit's extension directory, though the README does not specify the exact path. The settings are defined in settings.json under the node extension.markeditPreview. The default settings show a long list of options, including syncScroll, hidePreviewButtons, syntaxAutoDetect, imageHoverPreview, inlineImages, themeName, styledHtmlColorScheme, mathDelimiters, changeMode, and markdownIt. Each has a documented meaning. For example, themeName can be set to a theme from the styles/themes folder, or to "none" to disable styling and render raw HTML. styledHtmlColorScheme determines the color scheme for saving styled HTML files, with values light, dark, and auto.

Configuration depth: what the settings actually control

The settings go beyond simple toggles. syncScroll enables scroll synchronization between editor and preview, which is a common need. hidePreviewButtons hides built-in preview buttons in side-by-side mode, but only in the full build. syntaxAutoDetect enables automatic language detection for code highlighting, again only in the full build. imageHoverPreview shows a preview when hovering over an image link. inlineImages replaces image links with inline images in Mixed mode. mathDelimiters lets you customize the delimiters for KaTeX math rendering, with defaults for inline and display math. The changeMode object is particularly interesting: it defines an ordered list of modes and a hotkey. The modes are identified by IDs: edit, side-by-side, preview, syntax-hidden. If neither editor mode is included, the extension automatically adds edit. This means you can reorder or restrict the modes that appear when cycling. The hotkey specification is linked to a general MarkEdit customization page, so the format is not fully documented in the README. The markdownIt settings allow overriding the preset and options, which is a powerful escape hatch for users who need specific markdown-it behavior. This configuration depth is a strength, but it also means that users who want a simple preview might feel overwhelmed by the number of options.

Limitations and cases where it is the wrong tool

The most obvious limitation is that the built-in scroll sync is one-way, from editor to preview. The README lists a community extension, Bidirectional Preview Sync, that replaces this one-way sync. If you need to scroll in the preview and have the editor follow, the default extension will not do that. Another limitation is the lite build, which drops syntax auto-detect, math delimiters, and the hide-preview-buttons option. If you rely on math rendering, you must use the full build. Local images require MarkEdit 1.24.0 or later and a folder access grant, which is an extra step. The extension is tied to MarkEdit; it will not work in any other editor. Also, the README does not mention any performance characteristics or handling of very large documents. If you write extremely long Markdown files, you may need to test how the preview behaves. Finally, the extension depends on the MarkEdit API, so if that API changes, the extension may break until it is updated.

Alternatives and how they differ

The README itself lists two community extensions that build on or complement MarkEdit-preview. Bidirectional Preview Sync by Nigelw keeps the editor and preview synchronized in both directions, replacing the one-way sync. That is a direct alternative to the built-in syncScroll feature. Direct Preview by Squarelight-ai is a setup helper that configures a two-mode Edit/Preview toggle by setting the toolbar item and changeMode.modes for you. It does not replace the rendering engine; it simplifies configuration. Outside the MarkEdit ecosystem, there are other Markdown preview tools, but the README does not mention them. The key difference is that MarkEdit-preview is native to MarkEdit, while a generic tool like a browser-based Markdown previewer would require copy-paste or file watching. If you are not using MarkEdit, this extension is irrelevant. Within MarkEdit, the choice is between the default one-way sync and the community bidirectional sync, which is a real trade-off depending on your editing habits.

Maintenance, license, and upgrade considerations

The repository is actively maintained, with the last push on 2026-08-20 and a recent release v1.10.0 on the same date. Releases are frequent: v1.9.0 in August 2026 and v1.8.1 in June 2026. This suggests a steady maintenance cadence. The license is MIT, which is permissive and allows reuse with attribution. The project is not archived. The README mentions that pull requests are welcome but asks contributors to discuss proposals first, which indicates a maintainer who wants to avoid wasted effort. For users, the upgrade cost is low: you install from the registry and updates likely come through MarkEdit's extension mechanism, though the README does not detail that process. The build process is simple, so developers who fork the project can rebuild with yarn build. One thing to verify before upgrading is that your MarkEdit version is compatible, especially for features like Quick Look (requires 1.33.0+) and local images (requires 1.24.0+). The extension's reliance on the MarkEdit API means that major MarkEdit updates could require a corresponding extension update, but the active release history suggests that the maintainer keeps up.

Editorial conclusion

Adopt MarkEdit-preview if you use MarkEdit and want a built-in, configurable Markdown preview without leaving the editor. Do not adopt it if you need bidirectional sync, because the built-in sync is one-way from editor to preview, and you would have to rely on a community extension. Before adopting, verify that your MarkEdit version meets the requirements for local images (1.24.0+) and Quick Look (1.33.0+), and check that the lite build's limitations (no syntax auto-detect, no math delimiters, no hide-preview-buttons) are acceptable for your workflow.

Frequently asked questions

Official sources

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