nvim-asciidoc-preview

A simple AsciiDoc preview while editing AsciiDoc documents in Neovim.

Warning

The plugin is in an early stage not fully tested. Use at your own risk.

Works on: ✅ Linux, ✅ macOS and ✅ Windows with WSL2

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

Features

• 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).

Requirements

• 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)

Installation

lazy.nvim

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

packer.nvim

Show instruction

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

Configuration

For lazy.nvim use the opts or config property.

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

Variant with config

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.

Default Options

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

Usage

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.

FAQ

Is there a way to update the preview as I edit the AsciiDoc document?

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

How do I report an issue?

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

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.