A simple AsciiDoc preview while editing AsciiDoc documents in Neovim.
[!WARNING] The plugin is
in an early stagenot fully tested. Use at your own risk.Works on: ✅ Linux, ✅ macOS, but not yet on ❌ Windows (WSL❓)
The plugin started as a playground for learning Neovim plugin programming with Lua and a server component with Node.js. Therefore, many things are not solved optimally and partly implemented twice (plugin and server). Helpful tips are welcome.
:AsciiDocPreview
, a preview of the current AsciiDoc
file is shown in the web browser.:AsciiDocPreviewStop
command, the preview server is terminated in the
background.asciidoctor
and asciidoctor-diagram
).node
and npm
commandcurl
commandThe plugin allows optionally using the local installed Asciidoctor tools.
asciidoctor
command with the asciidoctor-diagram
extension.
{
'tigion/nvim-asciidoc-preview',
ft = { 'asciidoc' },
build = 'cd server && npm install',
opts = {
-- Add user configuration here
},
}
For lazy.nvim use the opts
or config
property.
opts = {
server = {
converter = 'js'
},
preview = {
position = 'current',
},
}
For other plugin manager, call the setup function
require('asciidoc-preview').setup({ ... })
directly.
Currently available settings for the user:
{
server = {
-- Determines how the AsciiDoc file is converted to HTML for the preview.
-- `js` - asciidoctor.js (no local installation needed)
-- `cmd` - asciidoctor command (local installation needed)
converter = 'js',
-- Determines the local port of the preview website.
-- Must be between 10000 and 65535.
port = 11235,
},
preview = {
-- Determines the scroll position of the preview website.
-- `current` - Keep current scroll position
-- `start` - Start of the website
-- `sync` - (experimental) Same (similar) position as in Neovim
-- => inaccurate, because very content dependent
position = 'current',
},
}
Command | Description |
---|---|
:AsciiDocPreview |
Starts the AsciiDoc preview server in background and opens the current AsciiDoc file in the standard web browser. |
:AsciiDocPreviewStop |
(if needed) Stops the AsciiDoc preview server. |
:AsciiDocPreviewOpen |
(if needed) (Re)Opens the current AsciiDoc file in the standard web browser. |
:AsciiDocPreviewNotify |
(if needed) Notifies the server to display the current AsciiDoc file in the preview. |
A keymap suggestion:
vim.keymap.set('n', '<Leader>cp', ':AsciiDocPreview<CR>', { desc = 'Preview AsciiDoc document' })
To use the same keymap for different file types and plugins (e.g. markdown-preview.nvim),
place the following in after/ftplugin/asciidoc.lua
:
local opts = { buffer = true, silent = true }
opts.desc = 'Preview AsciiDoc document'
vim.keymap.set('n', '<Leader>cp', ':AsciiDocPreview<CR>', opts)
This way the keymap is only set for AsciiDoc files.
:checkhealth asciidoc-preview
command.checkhealth
output~/.local/state/nvim/nvim-asciidoc-preview-server.log
file[!WARNING] The
nvim-asciidoc-preview-server.log
file contains private information from the current/last session. These are, for example, the name of your home directory and the names of the AsciiDoc files used.Do not share this information with others. So please remove or anonymize this information before.