A simple AsciiDoc preview while editing AsciiDoc documents in Neovim.

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.

• Features
• Requirements
• Installation
• Configuration
• Usage
• FAQ

• Once started with :AsciiDocPreview, a preview of the current AsciiDoc file is shown in the web browser.
• The preview is updated every time the AsciiDoc file is saved.
• When exiting Neovim or using the :AsciiDocPreviewStop command, the preview server is terminated in the background.
• The generation of the HTML preview is done either with:
  • Asciidoctor.js (default, no local installed Asciidoctor needed)
  • Or the locally installed Asciidoctor tools (asciidoctor and asciidoctor-diagram).

• Neovim >= 0.8
• Node.js with node and npm command
• curl command

The plugin allows optionally using the local installed Asciidoctor tools.

• This requires the asciidoctor command with the asciidoctor-diagram extension.
  • Install instruction (de)

{
  'tigion/nvim-asciidoc-preview',
  cmd = { 'AsciiDocPreview' },
  ft = { 'asciidoc' },
  build = 'cd server && npm install',
  opts = {
    -- Add user configuration here
  },
}

use({
  'tigion/nvim-asciidoc-preview',
  run = 'cd server && npm install',
  config = function()
    require('asciidoc-preview').setup({
      -- Add user configuration here
    })
  end,
})

For lazy.nvim use the opts or config property.

opts = {
  server = {
    converter = 'js'
  },
  preview = {
    position = 'current',
  },
}

config = function()
  require('asciidoc-preview').setup({
    server = {
      converter = 'js'
    },
    preview = {
      position = 'current',
    },
  })
end,

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',
  },
}

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 it in after/ftplugin/asciidoc.lua. This way the keymap is only set for AsciiDoc files.

local opts = { buffer = true, silent = true }
opts.desc = 'Preview AsciiDoc document'
vim.keymap.set('n', '<Leader>cp', ':AsciiDocPreview<CR>', opts)

1. Open an AsciiDoc document in Neovim.
2. Run the :checkhealth asciidoc-preview command.
3. Open a new Issue.
4. Describe your problem and include:
   • the checkhealth output
   • the Installation/Configuration with the used package manager
   • the content of the ~/.local/state/nvim/nvim-asciidoc-preview-server.log file