# previm previews Markdown, reStructuredText and textile inside Vim

> previm is a Vim plugin that renders the buffer you are editing in a browser and refreshes it as you type. It handles Markdown through markdown-it, reStructuredText through rst2html.py, plus textile and AsciiDoc, and it needs no dependencies except for reStructuredText.

**previm/previm** — Realtime preview by Vim. (Markdown, reStructuredText, textile)

- Repository: https://github.com/previm/previm
- Stars: 830 · Forks: 135
- Language: JavaScript
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/previm-previm

## A Vim plugin that renders the buffer you are editing

previm is a Vim plugin for previewing, and the README describes it in one line as a preview-oriented Vim plugin. In practice it does something specific: it takes the file you are editing, converts it to HTML, writes the result out and opens it in your browser, then keeps the browser in step with your edits.

The workflow described in the README is short. You define g:previm_open_cmd in your .vimrc, and that value is a command that can be executed from the command line, for example open -a Safari on a Mac. Then you start editing a file whose filetype is Markdown, run :PrevimOpen to launch the browser, switch back to the original Vim buffer and keep editing. The README states that the browser content updates every time you make a change.

That last point is the whole feature. This is not a build step and not a static site generator; there is no separate command to run and no server to start. The preview is bound to the buffer, so the loop is write, save, look at the browser, adjust.

The audience is Vim users who write documentation, README files or notes in Markdown and would rather not switch to a browser-based editor for the preview. The plugin also supports reStructuredText, textile and AsciiDoc, but Markdown is the path the README documents in detail.

## Markdown support is built on markdown-it with a specific plugin set

The Markdown support is not a hand written parser. The package metadata lists a set of markdown-it plugins as development dependencies, which tells you exactly what dialect the preview targets:

```json
  "devDependencies": {
    "markdown-it": "^14.1.1",
    "markdown-it-abbr": "^2.0.0",
    "markdown-it-checkbox": "^1.1.0",
    "markdown-it-cjk-breaks": "^2.0.0",
    "markdown-it-deflist": "^3.0.0",
    "markdown-it-footnote": "^4.0.0",
    "markdown-it-sub": "^2.0.0",
    "markdown-it-sup": "^2.0.0"
```

The README lists the same set of supported flavours and names the specification behind each one: CommonMark as the base, the PHP markdown extra style abbreviation, the Pandoc style definition list, footnote, subscript and superscript, and East Asian line breaks.

Two of these carry more weight than the rest for day to day writing. The definition list, footnote and subscript plugins follow Pandoc conventions, which is what many people mean when they write markdown these days. The East Asian line breaks plugin exists because markdown-it does not break lines between East Asian characters by default, which matters if you write Japanese or Chinese documentation.

The checkbox plugin also appears in the dependency list even though the README does not call it out separately in the format section, and it is the mechanism behind GitHub style task list checkboxes rendering as boxes rather than literal brackets.

Two diagram formats are handled beyond plain markdown, and both are called out in the README with their own examples: mermaid graphs and PlantUML.

## Only reStructuredText needs an external dependency

The dependency story is unusually tidy, and the README states it in a form that is easy to check at a glance.

For Markdown and textile, there is nothing required at all. The converter is bundled. For reStructuredText, rst2html.py is required, and installing docutils is what makes that command available:

```bash
    % pip install docutils
    % rst2html.py --version
```

The version output in the README shows Docutils 0.12 running under Python 2.7.5 on darwin, which is a snapshot of one machine rather than a requirement. There is no Python version constraint in the README, so a modern Python 3 install of docutils is the sensible reading, though the documentation does not state it.

For opening the preview, the README is equally clear that nothing is required either. open-browser.vim is listed as optional and can be used instead of configuring a command yourself.

The dependency list also explains a structural detail of the repository. The plugin code lives under autoload and plugin, the preview generation code under preview, and there are directories for doc, test and images. A package-lock.json is present, so the Node side is pinned.

Because the preview is a browser rendering of a local file, the output goes through a browser rather than a terminal renderer. That single design decision shapes most of the limitations that follow.

## The browser launch is yours to configure, and Safari has a known trap

g:previm_open_cmd is the setting that makes the whole thing work, and the README treats it as a required step rather than an optional convenience. The value must be a command that can be run from the command line, and :help g:previm_open_cmd is the reference. On a Mac the example given is open -a Safari, which is the kind of platform-specific command that makes the setting the fiddliest part of the setup.

If you use open-browser.vim, the README notes that no configuration is needed at all, which is the shortcut worth taking if you already have that plugin.

There is one documented failure mode, and it is worth knowing before you spend an afternoon on it. The README reports that with Safari 13.0.3 the browser can get stuck showing a loading state, and it gives the fix: enable the Develop menu in Safari preferences under Advanced, then choose to disable local file restrictions from that menu.

That fix is a browser security setting that affects local file access, which tells you something about the mechanism. The preview is served from a file on disk rather than over HTTP, so a browser that blocks local file loading will hang. Any browser with strict local file rules will behave the same way, whether or not it is Safari.

The README also mentions that a video of the installation was removed and the author's account blocked, and links to an install video file in the repository instead.

## Two ways to open the preview, and what each one costs you

There are two routes to a rendered preview, and the difference between them is small but concrete.

The g:previm_open_cmd route gives you full control. You write a shell command, the plugin runs it, and the browser of your choice opens the generated file. The cost is that you own the command, so you own the platform quirks, the quoting and the browser choice. On macOS that is open -a Safari; on other systems it is whatever your environment offers, and the README only illustrates the Mac case.

The open-browser.vim route hands the launching problem to another plugin. The README states that open-browser.vim can be used optionally, and that when you use it there is no setting to configure. The cost is that you now depend on that plugin's behaviour and its own requirements, which the previm README does not document.

For a reader deciding between them, the practical question is whether your browser needs a specific command to open local files at all. If it does, define g:previm_open_cmd and you keep control of the whole chain. If your setup already handles that, open-browser.vim removes a line of configuration and a class of platform-specific problem.

Neither route changes what the preview can render. The format support, the Markdown dialect and the reStructuredText dependency all stay the same either way, which is worth separating in your head before you start tuning.

## The Node side is small, and its version numbers disagree with the releases

The JavaScript half of the project is modest. The package is named previm, declares its main entry as index.js, uses commonjs modules, and the only script defined is the test runner:

```json
  "scripts": {
    "test": "node --test test/node/*.test.js"
  },
```

The test suite therefore runs on the built in node test runner, against the files in test/node, and no test framework dependency appears in the manifest. The directory list in the manifest points at doc and test, and the repository root confirms the same layout with autoload, plugin, preview, test and doc directories alongside the Vim plugin files.

Two version numbers in the repository disagree with each other, and both matter if you are pinning anything. The package.json version field reads 1.0.0, while the published releases are 2.0, 2.0.1 and 2.0.2. The tags also stop a while back: 2.0.2 was released on 2024-11-11, with 2.0.1 on 2024-05-27 and 2.0 on 2024-05-02. Meanwhile the repository is not archived and the last push was on 2026-07-23, so commits are still landing without a corresponding tag.

The manifest also carries the keywords and author fields as empty strings and points the repository URL at the GitHub project, so the metadata is partly unpopulated. For a plugin that people install from a plugin manager rather than from a registry, that inconsistency is more of a curiosity than a blocker.

## Licence, maintenance state and where previm stops

The licence needs a sentence of its own. The package metadata declares ISC, while the repository records a licence that GitHub cannot classify and points to the LICENSE file. Those are different statements, and ISC is also not the licence family that BSD and MIT belong to, so the two are not simply the same thing recorded twice. Read the LICENSE file before redistributing the plugin.

On maintenance, the honest summary is that the code is touched but the releases are not. The last push was on 2026-07-23, which is inside the last six months, so the project is not dormant, but the newest release is 2.0.2 from 2024-11-11 and there has been no tag since. If you install through a plugin manager you are likely running whatever the manager fetched, which may or may not be the tagged release.

The functional limits are worth stating plainly. The preview needs a browser, so there is no terminal rendering for a remote session over SSH. It needs a working g:previm_open_cmd unless open-browser.vim is present. reStructuredText needs docutils and a Python interpreter on the machine. The README documents the Markdown path in detail and the others only briefly, with the reStructuredText section limited to the rst2html.py dependency and the format list, so if your documents are AsciiDoc or textile you are working from less guidance than a Markdown user. Finally, the known Safari problem shows the preview sits on the browser's local file security model, which is a dependency on browser behaviour that no configuration in the plugin can fully own.

## Conclusion

Vim users who write documentation in Markdown and want a live browser preview without leaving the editor should adopt previm, because the workflow is a single :PrevimOpen command and a per-change refresh, with no runtime dependencies for Markdown or textile. It is the wrong tool for a terminal-only setup, since the preview always needs a browser and a configured g:previm_open_cmd, and it is the wrong tool for reStructuredText work unless docutils is installed. Before adopting, check that your browser will load a local file, since the README records Safari 13.0.3 hanging on a loading state, and read LICENSE and package.json together, because the package metadata declares ISC while the repository licence is recorded as unclassified.

## FAQ

### How do I open a previm preview from Vim?

Define g:previm_open_cmd in your .vimrc with a command that can be executed from the command line, open a file whose filetype is Markdown, and run :PrevimOpen. The README says the browser content updates on every change you make.

### Does previm need any dependencies for Markdown?

No. The README states that for Markdown and textile there is nothing required, and that nothing is required to open the preview either. Only reStructuredText needs rst2html.py, which comes with docutils.

### Which Markdown extensions does previm support?

The package metadata lists markdown-it together with plugins for abbreviations, checkboxes, East Asian line breaks, definition lists, footnotes, subscript and superscript. The README names CommonMark as the base and describes the Pandoc style definition list, footnote, subscript and superscript as supported.

### Why does the previm preview get stuck on a loading state in Safari?

The README reports that Safari 13.0.3 can get stuck showing a loading state, and the fix it gives is to enable the Develop menu in Safari preferences and then disable local file restrictions from that menu, because the preview is loaded from a local file.

## Sources

- [Issues](https://github.com/previm/previm/issues)
- [previm/previm on GitHub](https://github.com/previm/previm)
- [README](https://github.com/previm/previm/blob/master/README.md)
- [Releases](https://github.com/previm/previm/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/previm-previm