*live-server.txt*                          Live reload for web development

Author: Barrett Ruth <https://barrettruth.com>
Homepage: <https://github.com/barrettruth/live-server.nvim>

===============================================================================
INTRODUCTION                                                *live-server.nvim*

live-server.nvim automatically reloads HTML, CSS, and JavaScript files in the
browser via a local development server. No external dependencies required —
the server runs entirely in Lua using Neovim's built-in libuv bindings.

===============================================================================
REQUIREMENTS                                        *live-server-requirements*

- Neovim >= 0.10

===============================================================================
CONFIGURATION                                            *live-server-config*

                                                          *vim.g.live_server*
Configure via `vim.g.live_server` before the plugin loads: >lua

    vim.g.live_server = {
        port = 8080,
        browser = false,
    }
<
                                                         *live_server.Config*
Fields: ~

    {port}      (`integer?`) Port for the HTTP server. Default: `5500`
    {browser}   (`boolean?`) Auto-open browser on start. Default: `true`
    {debounce}  (`integer?`) Debounce interval in ms for file changes.
                Default: `120`
    {ignore}    (`string[]?`) Lua patterns for file paths to ignore when
                watching for changes. Default: `{}`
    {css_inject} (`boolean?`) Hot-swap CSS without full page reload.
                Default: `true`
    {debug}     (`boolean?`) Log each step of the hot-reload chain via
                |vim.notify()| at DEBUG level. Default: `false`

===============================================================================
COMMANDS                                               *live-server-commands*

                                                            *:LiveServerStart*
:LiveServerStart [dir]    Start the live server. If `dir` is provided, the
                          server starts in the specified directory. Otherwise,
                          uses the directory of the current file.

                                                             *:LiveServerStop*
:LiveServerStop [dir]     Stop the live server. If `dir` is provided, stops
                          the server running in the specified directory.

                                                           *:LiveServerToggle*
:LiveServerToggle [dir]   Toggle the live server on or off. If `dir` is
                          provided, toggles the server in that directory.

===============================================================================
MAPPINGS                                               *live-server-mappings*

                                                    *<Plug>(live-server-start)*
<Plug>(live-server-start)   Start the live server. Equivalent to
                            |:LiveServerStart| with no arguments.

                                                     *<Plug>(live-server-stop)*
<Plug>(live-server-stop)    Stop the live server. Equivalent to
                            |:LiveServerStop| with no arguments.

                                                   *<Plug>(live-server-toggle)*
<Plug>(live-server-toggle)  Toggle the live server. Equivalent to
                            |:LiveServerToggle| with no arguments.

Example configuration: >lua
    vim.keymap.set('n', '<leader>ls', '<Plug>(live-server-start)')
    vim.keymap.set('n', '<leader>lx', '<Plug>(live-server-stop)')
    vim.keymap.set('n', '<leader>lt', '<Plug>(live-server-toggle)')
<

===============================================================================
API                                                        *live-server-api*

All functions accept an optional `dir` parameter. When omitted, the directory
of the current file is used.

live_server.start({dir})                                 *live_server.start()*
    Start the live server in the specified directory.

    Parameters: ~
        {dir}  (`string?`) Directory to serve

live_server.stop({dir})                                   *live_server.stop()*
    Stop the live server running in the specified directory.

    Parameters: ~
        {dir}  (`string?`) Directory of running server

live_server.toggle({dir})                               *live_server.toggle()*
    Toggle the live server on or off.

    Parameters: ~
        {dir}  (`string?`) Directory to toggle

live_server.setup({user_config})                         *live_server.setup()*
    Deprecated: Use |vim.g.live_server| instead.

    Parameters: ~
        {user_config}  (|live_server.Config|?) Configuration table

===============================================================================
EXAMPLES                                               *live-server-examples*

Start server in project root: >vim

    :LiveServerStart ~/projects/my-website
<
Lua keybinding to toggle server: >lua

    vim.keymap.set('n', '<leader>ls', '<Plug>(live-server-toggle)')
<
Configuration with custom port and no auto-open: >lua

    vim.g.live_server = {
        port = 3000,
        browser = false,
    }
<
Ignore node_modules and dotfiles: >lua

    vim.g.live_server = {
        ignore = { 'node_modules', '^%.' },
    }
<
===============================================================================
KNOWN LIMITATIONS                                  *live-server-limitations*

No Recursive File Watching on Linux ~
                                              *live-server-linux-recursive*
libuv's `uv_fs_event` only supports recursive directory watching on macOS
(FSEvents) and Windows (ReadDirectoryChangesW). On Linux, the `recursive`
flag is silently accepted but ignored because inotify does not support it
natively. Only files directly in the served root directory trigger
hot-reload; files in subdirectories (e.g. `css/style.css`) will not be
detected.

See https://github.com/libuv/libuv/issues/1778

Enable `debug` in |live-server-config| to verify whether `fs_event`
callbacks fire for a given file change.

-------------------------------------------------------------------------------
vim:tw=78:ft=help:norl: