Markdown Live Preview for Neovim

Live Preview of your GitHub Flavored Markdown files & local git repositories.

Powered by Bunvim and Pantsdown.

demo.mp4

✨ Features

• 💻 Linux / macOS / WSL
• 🔴 LIVE updates
• ♻️ Synced Scrolling
• 🌈 Dark & Light modes
• 🖍️ Cursorline in Preview
• 📹 Video Support
• 🏞️ Local Image Support
• 🧜 Mermaid Support
• 📌 Single-file mode
• 📂 Repository mode

✅ Requirements

• Bun
• Neovim

📦 Installation

Using lazy.nvim

{
    "wallpants/github-preview.nvim",
    cmd = { "GithubPreviewToggle" },
    keys = { "<leader>mpt" },
    opts = {
        -- config goes here
    },
    config = function(_, opts)
        local gpreview = require("github-preview")
        gpreview.setup(opts)

        local fns = gpreview.fns
        vim.keymap.set("n", "<leader>mpt", fns.toggle)
        vim.keymap.set("n", "<leader>mps", fns.single_file_toggle)
        vim.keymap.set("n", "<leader>mpd", fns.details_tags_toggle)
    end,
}

⚙️ Configuration

I recommend you start off with the default settings and play around with the UI to figure out what settings you want to override before committing to updating your config files.

All values are optional, you can leave empty to use default values. Any values you specify will be deeply merged with this dictionary.

require("github-preview").setup({
    host = "localhost",

    -- port used by local server
    port = 6041,

    -- set to "true" to force single-file mode & disable repository mode
    single_file = false,

    theme = {
        -- "system" | "light" | "dark"
        name = "system",
        high_contrast = false,
    },

    -- define how to render <details> tags on init/content-change
    -- true: <details> tags are rendered open
    -- false: <details> tags are rendered closed
    details_tags_open = true,

    cursor_line = {
        disable = false,

        -- CSS color
        -- if you provide an invalid value, cursorline will be invisible
        color = "#c86414",
        opacity = 0.2,
    },

    scroll = {
        disable = false,

        -- Between 0 and 100
        -- VERY LOW and VERY HIGH numbers might result in cursorline out of screen
        top_offset_pct = 35,
    },

    -- for debugging
    -- nil | "debug" | "verbose"
    log_level = nil,
})

💻 Usage

🚨 The first time the plugin runs, it might take a few seconds for your browser to open as dependencies are being downloaded. This might happen again after a plugin update if there were any changes to the plugin dependencies.

:GithubPreviewToggle

Starts the plugin if not running or stops it if it's already running.

:GithubPreviewStart

Start plugin. Any previously created instances are killed.

:GithubPreviewStop

Stops the plugin. Closes browser tab as well.

🧠 Advanced Usage

This plugin also exports functions for you to set keymaps, trigger stuff in autocommands, create user commands, etc.

Available functions

local gpreview = require("github-preview")
local fns = gpreview.fns

gpreview.setup({ ... })

-- plugin start/stop
fns.toggle()
fns.start()
fns.stop()

-- clear current session's config overrides
-- and fallback to your config files
fns.clear_overrides()

-- single-file mode enable/disable
fns.single_file_toggle()
fns.single_file_on()
fns.single_file_off()

-- render <details> tags open/closed
fns.details_tags_toggle()
fns.details_tags_open()
fns.details_tags_closed()

-- synced scroll enable/disable
fns.scroll_toggle()
fns.scroll_on()
fns.scroll_off()

-- cursorline enable/disable
fns.cursorline_toggle()
fns.cursorline_on()
fns.cursorline_off()

👷 Development & Contributing

See documentation