penview.nvim

Real-time Markdown preview for Neovim with GitHub Flavored Markdown styling.

Demo

penview-demo.webm

Features

• Live preview updates as you type (no save required)
• GitHub Flavored Markdown rendering
• Light/dark theme toggle
• Syntax highlighting for code blocks
• KaTeX math support
• Mermaid diagram support
• Self-contained HTML export
• Headless mode support

Requirements

• Neovim 0.9+
• curl (for downloading pre-compiled binaries)
• Rust toolchain (only if building from source)

Installation

lazy.nvim (recommended)

Pre-compiled binaries are automatically downloaded for Linux and macOS (x86_64 and aarch64):

{
  "vihu/penview.nvim",
  build = function()
    require("penview.build").install()
  end,
  ft = "markdown",
  config = function()
    require("penview").setup({
      browser = "firefox",      -- Required: your browser command
      -- debounce = 100,        -- Optional: ms to wait before updating (default: 100)
      -- port = 0,              -- Optional: server port (default: random)
      -- debug = false,         -- Optional: enable debug logging
      -- sync_scroll = true,    -- Optional: sync scroll with nvim (default: true)
      -- theme = "light/dark",  -- Optional: set theme (default: dark)
    })
  end,
  keys = {
    { "<leader>po", "<cmd>PenviewStart<cr>", desc = "[P]review [O]pen" },
    { "<leader>pc", "<cmd>PenviewStop<cr>", desc = "[P]review [C]lose" },
  },
}

packer.nvim

use {
  "vihu/penview.nvim",
  run = function()
    require("penview.build").install()
  end,
  config = function()
    require("penview").setup({
      browser = "firefox",
    })
  end,
}

vim-plug

Plug 'vihu/penview.nvim', { 'do': ':lua require("penview.build").install()' }

" In your init.vim or after/plugin:
lua require("penview").setup({ browser = "firefox" })

Building from source

If pre-compiled binaries are unavailable for your platform, or you prefer to build from source:

-- lazy.nvim
{
  "vihu/penview.nvim",
  build = "make build",  -- Requires Rust toolchain
  -- ...
}

Build dependencies:

• Rust toolchain (stable)
• libluajit (libluajit-5.1-dev on Debian/Ubuntu)
• libclang-dev
• pkg-config

Usage

1. Open a markdown file
2. Run :PenviewStart or press <leader>po
3. Browser opens with live preview
4. Edit your markdown - preview updates in real-time
5. Run :PenviewStop or press <leader>pc to stop

Headless Mode

For neovim running on Linux servers without a browser, use headless mode to expose the HTTP server for remote access.

Setup

On the remote server, configure penview with headless mode:

require("penview").setup({
  headless = true,  -- Enable headless mode (binds to 0.0.0.0), required.
  port = 9876,      -- Port for remote access, required.
})

Workflow

1. Remote server: Open a markdown file and run :PenviewStart
2. Local machine: Create an SSH tunnel to the remote server:

   ssh -L 9876:localhost:9876 remote-server
   

3. Local browser: Open the preview URL:

   http://localhost:9876?path=/path/to/file.md
   

   (use the absolute path to the file on the remote server)

The preview updates in real-time as you edit the file on the remote server.

Commands

| Command | Description | | --------------- | ----------------------------------------- | | :PenviewStart | Start the preview server and open browser | | :PenviewStop | Stop the preview server |

Credits

This plugin basically is a combination of the following original works:

• tatum: Original Markdown renderer
• websocket.nvim: WebSocket client for Neovim

License

MIT