Introduction 📖

live-preview.nvim is a plugin for Neovim that allows you to view Markdown, HTML (along with CSS, JavaScript) and AsciiDoc files in a web browser with live updates. No external dependencies or runtime like NodeJS or Python are required, since the backend is fully written in Lua and Neovim's built-in functions.

You can read this README in Tiếng Việt

Features ✨

• Supports markdown, HTML (with reference to CSS, JS), and AsciiDoc files 📄
• Support Katex for rendering math equations in markdown and AsciiDoc files 🧮
• Supports mermaid for rendering diagrams in markdown files 🖼️
• Syntax highlighting for code blocks in Markdown and AsciiDoc 🖍️
• Supports sync scrolling in the browser as you scroll in the Markdown files in Neovim. (You need to enable sync_scroll in setup. This feature should be used with brianhuster/autosave.nvim) 🔄
• Integration with telescope.nvim 🔭, fzf-lua and mini.pick for opening files to preview 📂

Updates 🆕

See RELEASE.md

⚠️ Important Notice: You should clear the cache of the browser after updating to ensure the plugin works correctly.

Demo video 🎥

demo.mp4

Requirements 📋

• Neovim >=0.10.0 (recommended: >=0.10.1 compiled with LuaJIT) 📟
• A modern web browser 🌐
• PowerShell (only if you use Windows) 🪟

Installation 🛠️

You can install this plugin using a plugin manager. Most plugin managers are supported. Below are some examples

Using lazy.nvim (recommended) 💤

require("lazy").setup({
    {
        'brianhuster/live-preview.nvim',
        dependencies = {
            'brianhuster/autosave.nvim'  -- Not required, but recomended for autosaving and sync scrolling

            -- You can choose one of the following pickers
            'nvim-telescope/telescope.nvim',
            'ibhagwan/fzf-lua',
            'echasnovski/mini.pick',
        },
        opts = {},
   }
})

mini.deps 📦

MiniDeps.add({
    source = 'brianhuster/live-preview.nvim',
    depends = { 
        'brianhuster/autosave.nvim'  -- Not required, but recomended for autosaving and sync scrolling

        -- You can choose one of the following pickers
        'nvim-telescope/telescope.nvim',
        'ibhagwan/fzf-lua',
        'echasnovski/mini.pick',
    }, 
})

rocks.nvim 🪨

:Rocks install live-preview.nvim

vim-plug 🔌

Plug 'brianhuster/live-preview.nvim'
Plug 'brianhuster/autosave.nvim' " Not required, but recomended for autosaving

" You can choose one of the following pickers
Plug 'nvim-telescope/telescope.nvim'
Plug 'ibhagwan/fzf-lua'
Plug 'echasnovski/mini.pick'

Native package (without a plugin manager) 📦

git clone --depth 1 https://github.com/brianhuster/live-preview.nvim ~/.local/share/nvim/site/pack/brianhuster/start/live-preview.nvim

Setup ⚙️

You can customize the plugin by passing a table to the opts variable (if you use lazy.nvim) or the function require('livepreview').setup(). Here is the default configuration:

In Lua

{
    cmd = "LivePreview", -- Main command of live-preview.nvim
    port = 5500, -- Port to run the live preview server on.
    autokill = false, -- If true, the plugin will autokill other processes running on the same port (except for Neovim) when starting the server.
    browser = 'default', -~/.co- Terminal command to open the browser for live-previewing (eg. 'firefox', 'flatpak run com.vivaldi.Vivaldi'). By default, it will use the default browser.
    dynamic_root = false, -- If true, the plugin will set the root directory to the previewed file's directory. If false, the root directory will be the current working directory (`:lua print(vim.uv.cwd())`).
    sync_scroll = false, -- If true, the plugin will sync the scrolling in the browser as you scroll in the Markdown files in Neovim.
    picker = nil, -- Picker to use for opening files. 3 choices are available: 'telescope', 'fzf-lua', 'mini.pick'. If nil, the plugin look for the first available picker when you call the `pick` command.
}

In Vimscript

call v:lua.require('livepreview').setup({
    \ 'cmd': 'LivePreview', 
    \ 'port': 5500, 
    \ 'autokill': v:false, 
    \ 'browser': 'default', 
    \ 'dynamic_root': v:false, 
    \ 'sync_scroll': v:false, 
    \ 'picker': v:false, 
\ })

Usage 🚀

For default configuration (opt.cmd = "LivePreview")

• To start the live preview, use the command:

:LivePreview start

This command will open the current Markdown or HTML file in your default web browser and update it live as you write changes to your file.

You can also parse a file path as argument, for example :LivePreview start test/doc.md

• To stop the live preview server, use the command:

:LivePreview close

• To open a picker and select a file to preview, use the command:

:LivePreview pick

• To see document about each subcommand, use the command:

:LivePreview help

This requires a picker to be installed (Telescope, fzf-lua or mini.pick). If you have multiple pickers installed, you can specify the picker to use by passing the picker name to the configuration table (see setup)

Use the command :help livepreview to see the help documentation.

Contributing 🤝

Since this is a young project, there should be a lot of rooms for improvements. If you would like to contribute to this project, please feel free to open an issue or a pull request.

TODO ✅

• Support for KaTex math in Markdown and AsciiDoc
• Support for Mermaid diagrams in Markdown and AsciiDoc
• Syntax highlighting for code blocks in Markdown and AsciiDoc
• Autoscroll in the browser as you scroll in the Markdown files in Neovim
• Autoscroll in the browser as you scroll in the AsciiDoc files in Neovim
• Integration with telescope.nvim 🔭, fzf-lua and mini.pick
• Support TUI web browsers like carbonyl, browsh

Non goals 🚫

These are not in roadmap of live-preview.nvim right now, but pull requests are welcome

• Allow users to add custom css and js files in configuration #49, #50

Acknowledgements 🙏

• Live Server and Live Preview for the idea inspiration
• glacambre/firenvim for the sha1 function reference
• sindresorhus/github-markdown-css CSS style for Markdown files
• markdown-it/markdown-it for parsing Markdown files
• asciidoctor/asciidoctor.js for parsing AsciiDoc files
• KaTeX for rendering math equations
• mermaid-js/mermaid for rendering diagrams
• digitalmoksha/markdown-it-inject-linenumbers : A markdown-it plugin for injecting line numbers into html output

Buy me a coffee ☕

Maintaining this project takes time and effort, especially as I am a student now. If you find this project helpful, please consider supporting me :>