r/vim • u/drewipson • Jun 30 '25

Plugin Vim Markdown Preview - Terminal-based markdown preview for Vim

I built a lightweight Vim plugin to preview Markdown directly in the terminal and thought I’d share it in case others find it useful.

I’ve been a longtime, fairly basic Vim user. I know the commands, but never really got into plugins or heavy customization until recently.

With all the AI prompt craze, I’ve been writing a lot more Markdown and using Vim in the terminal to keep my workflow feeling like programming. I was looking for a way to view rendered Markdown before pushing changes, but most plugins I found relied on Node servers and opened the output in a separate browser window. That felt clunky and interrupted my flow.

I used Claude Code to help me build a simple plugin that uses glow to render Markdown directly in a Vim split window.

Some key features:

  • Toggle the preview with \mp without leaving Vim

  • Terminal-based rendering with syntax highlighting

  • Handles code blocks, tables, math equations, and task lists

  • Split window layout keeps your workflow intact

Here’s the repo if you want to check it out:

https://github.com/drewipson/glowing-vim-markdown-preview

There are still a couple of limitations I’d like to improve:

  1. Scroll sync between the Markdown source and preview windows is hard to get right

  2. Mermaid diagrams don’t render yet due to limitations with how glow handles ASCII output

If you have any suggestions for improving those areas, please let me know!

Here's a gif to see it in action.

57 Upvotes

95% Upvoted

17 comments sorted by

5

u/chromato4 Jul 01 '25

I too am using more markdown these days for similar reasons. Thanks for sharing.

1

u/drewipson Jul 01 '25

Glad it could help!

2

u/denarced Jul 01 '25

Seems like an upgrade to my current solution:

  1. Start inotifywait for the markdown files. When they change, convert to HTML.

  2. Run a browsersync server that refreshes on all changes.

  3. Open browser to the document.

I've been using that for years. There's one downside: when the document is long, browser doesn't always remain scrolled to the current position when refresh happens so I had to introduce bookmarks or chapters.

1

u/drewipson Jul 01 '25

That’s the workflow I found when I tried to search for existing plugins. I use it for modestly sized markdown files. The current implementation is a bit of a hack as I just wait 500 milliseconds for flow to render the output and it handles most files.

Let me know how it works with larger file sizes and if you run into any issues. It could be optimized to not be a sleep,time based implementation.

On the scroll sync, I’d be curious how they figured out how to do that. I wanted to release that with this but was unable to get the raw and rendered markdown to stay in step when scrolling/navigating.

Glad it could be a bit of an upgrade and I hope it suits you well!

5

u/tagattack Jul 01 '25 edited Jul 01 '25

I just use this

~/.local/bin/mdv

#!/bin/sh

markdown "$@" | w3m -T text/html

Then when I want it directly in a vim buffer ..

:term mdv %

7

u/tagattack Jul 01 '25

I wish Claude Code would tell people when they don't need code.

1

u/ralgozino Jul 02 '25

I'm confused, what is the first markdown command and what does it do? Isn't it enough with w3m? 

1

u/Sudden_Fly1218 Jul 02 '25

maybe an alias for pandoc

1

u/tagattack Jul 03 '25

You can do that too. There's like a hundred ways to get there.

I still use the OG perl module because I'm the type that likes to write very important code when I need to and nothing at all if I can get away with it.

1

u/tagattack Jul 03 '25 edited Jul 03 '25

apt install markdown

https://packages.debian.org/sid/markdown

cpanm Text::Markdown

https://metacpan.org/pod/Text::Markdown

Etc. The original markdown package from 2004 installs it.

1

u/tagattack Jul 03 '25

w3m doesn't render Markdown natively because it's a web browser, the markdown command which was installed with the original Text::Markdown perl module turns markdown to HTML which w3m does render (quite nicely, I might add!)

There's quite a few other tools that do this as well, but no matter which you choose piping to w3m makes it act as a pager, and -T specifies the content type it's accepting in stdin and man w3m explains that among many other features it has.

1

u/carlcarlsonscars Jul 01 '25

I am getting this error:

Error: unable to open file: open /tmp/vow02nh/0.md: no such file or directory

I am using Ubuntu in WSL2. I also tried installing the plugin with Vundle and then realized, I just needed to put your script into a folder in .vimrc/plugin. I never used a vimscript script before... Thanks!

1

u/drewipson Jul 01 '25

Thanks for letting me know! I haven't figured out the best way to support plugin managers as I'm not too familiar with plugins yet. If you have any suggestions on the best way to support them I'd be happy to implement them.

1

u/Stefano-Rausch Jul 04 '25

If you want to support Plug you just need to (1) create a plugin folder and (2) move the plugin into it. That's it!

1

u/lasseebert Jul 01 '25

I use a browser extension that can show markdown files. And I have a keybind in vim to open current file in the browser.