livepreview.txt

*livepreview.txt*             For Nvim >=0.10.1

Author: Phạm Bình An
Upstream: https://github.com/brianhuster/live-preview.nvim
Copyright: (C) 2024 Phạm Bình An
License: GPL-3.0 <https://www.gnu.org/licenses/gpl-3.0.html>

                                      Type |gO| to see the table of contents.

==============================================================================
1. Introduction
								*livepreview*

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.

Link to repo https://github.com/brianhuster/live-preview.nvim

==============================================================================
2. Configuration
							    *livepreview-config*

`live-preview.nvim` can be configured by passing a Lua table to the function
`require('livepreview.config').set()`. Below is the default configuration: >lua
    require('livepreview.config').set({
	port = 5500,
	browser = 'default',
	dynamic_root = false,
	sync_scroll = true,
	picker = "",
    })
<

Explaination of each option:
- `port`: Port to run the live preview server on.
- `browser`: Terminal command to open the browser for live-previewing (eg.
  'firefox', 'flatpak run com.vivaldi.Vivaldi'). By default, it will use the
  system's default browser.
- `sync_scroll`: If true, the plugin will sync the scrolling in the browser as
  you scroll in the Markdown files in Neovim.
- `picker`: 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.

Note: If you wish to config the plugin in Vimscript, see |v:lua-call| for
instruction on how to call Lua function in Vimscript

See also |livepreview-checkhealth| and |LivePreview.config|

==============================================================================
3. Usage
							    *livepreview-usage*

							    *:LivePreview*
- To start the live preview, use the command: >vim
    :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 (either absolute or relative) as argument, for
example >vim
    :LivePreview start test/doc.md

- To stop the live preview server, use the command: >vim
    :LivePreview close
<
- To open a picker and select a file to preview, use the command: >vim
    :LivePreview pick
<
- To see document about each subcommand, use the command: >vim
    :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 |livepreview-config|)

							*livepreview-checkhealth*
- To run |checkhealth| for `live-preview.nvim`, use the command: >vim
    :checkhealth livepreview
<
This will check all the necessary dependencies. It also shows the full current
configuration of the plugin and validate it


PREVENT LOADING ~
							*g:loaded_livepreview*

If for some reason you don't want to load `live-preview.nvim` on startup, you
can add the following line to your Neovim configuration file:
>vim
	let g:loaded_livepreview = 1  " If you use Vimscript
< >lua
	vim.g.loaded_livepreview = 1  -- If you use Lua
<

Then, when you need to load the plugin, you can run this command: >vim
	:runtime! plugin/livepreview.lua
<
==============================================================================
4. API
							    *livepreview-api*

LIVEPREVIEW GLOBAL VARIABLE				*lua-LivePreview*

`LivePreview` is a global Lua variable that contains the API for
`live-preview.nvim` to run in |cmdline|.

It is defined when the plugin is loaded, so you shouldn't use it inside your
configuration file.

`LivePreview.config.<option>`				*LivePreview.config*

    WARNING: This feature is experimental/unstable.

    To set a configuration option for the current session, run: >vim
	:lua LivePreview.config.<option> = <value>
<
    Example: >vim
	:lua LivePreview.config.port = 8080
<
    To see the value of an option, run: >vim
	:lua =LivePreview.config.<option>
<
    Since |:=| is shorthand for |:lua=|, you can also run: >vim
	:= LivePreview.config.<option>
<
    Note: If you want to see the whole configuration, use
    `:checkhealth livepreview` instead of |LivePreview.config|
==============================================================================
4. FAQ
							    *livepreview-faq*

THIS PLUGIN DOESN'T UPDATE HTML PREVIEW AS I TYPE, WHILE IT DOES WITH MARKDOWN ~

That's true, unlike Markdown, AsciiDoc or SVG preview, `live-preview.nvim` doesn't
update the HTML preview as you type, you need to save the file to see the
change in the browser. You can add a mapping or an autocommand to make saving
the file easier. Example:
>vim
    " Map Ctrl-S to save the file
    noremap <C-s> <cmd>wa<CR>
    " Autosave the file when you leave insert mode
    au InsertLeavePre * if &modifiable | silent! write | endif
<
The above code block is in Vimscript, but you can use them in Lua configuration
file with |vim.cmd()| function.


WHY DOESN'T THE RELATIVE LINK (`../`) WORK? ~

Make sure the webroot of the server is the same as the root directory of
your project. To find the webroot of the server, run >vim
    :checkhealth livepreview
<
The result is shown in the section `Server and process` of the checkhealth
buffer.

Also, don't set `dynamic_root` to `true` when unnecessary. You can also see
live-preview.nvim config using `:checkhealth livepreview`


HOW CAN I ADD DIAGRAMS TO ASCIIDOC? ~

live-preview.nvim only supports `mermaid.js` for diagrams. You can add a `mermaid`
diagram as a `[source,mermaid]` code block to your AsciiDoc file. Example:
>asciidoc
    [source,mermaid]
    ----
    graph TD;
	A-->B;
	A-->C;
	B-->D;
	C-->D;
    ----
<==============================================================================
5. Change log
							*livepreview-change-log*
See |livepreview-changelog|


==============================================================================
6. BUY ME A COFFEE!
							    *livepreview-donate*

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

PAYPAL <https://paypal.me/brianphambinhan>

VIETQR (Việt Nam)
<https://img.vietqr.io/image/mb-9704229209586831984-print.png?addInfo=Donate%20for%20livepreview%20plugin%20nvim&accountName=PHAM%20BINH%20AN>

vim:tw=78:ts=8:noet:ft=help:norl: