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 or a new AsciiDoc file is opened.
  • Updating the preview while typing is currently not supported. A workaround is in the FAQ.
• When exiting Neovim, no open Asciidoc files exists 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.10
• 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',
  ft = { 'asciidoc' },
  build = 'cd server && npm install --omit=dev',
  ---@module 'asciidoc-preview'
  ---@type asciidoc-preview.Config
  opts = {
    -- Add user configuration here
  },
}

use({
  'tigion/nvim-asciidoc-preview',
  run = 'cd server && npm install --omit=dev',
  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 = {
    -- Specifies 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',

    -- Specifies the hostname or IP address of the preview website for the client.
    -- This is only needed if you run neovim in a remote session and
    -- want to access the preview website from another machine.
    hostname = 'localhost',

    -- Specifies the port of the preview website on the client and server side.
    -- Must be between 10000 and 65535.
    port = 11235,
  },
  preview = {
    -- Specifies 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 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.

The plugin itself does currently not support this. However, you can use an extra plugin for automatic saving like auto-save.nvim or autosave.nvim to automatically save the AsciiDoc document after every change. Thanks to brianhuster for the idea.

With auto-save.nvim you can use the following Condition to only automatically save AsciiDoc files:

-- Configuration part of the plugin auto-save.nvim
opts = {
  -- Activate automatic saving only for specified file types.
  condition = function(buf)
    local filetype = vim.fn.getbufvar(buf, "&filetype")
    local filetypes = { 'asciidoc', 'asciidoctor' } -- List of allowed file types.
    return vim.list_contains(filetypes, filetype)
  end,
  -- I think a delay between 1000 and 3000 ms is okay.
  -- To low delays might cause performance issues with
  -- the rendering of the AsciiDoc preview!
  debounce_delay = 2000,
}

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