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

• The preview is updated every time the AsciiDoc file is saved or a new

• When exiting Neovim, no open Asciidoc files exists or using the

• The generation of the HTML preview is done either with:

Requirements

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

• This requires the asciidoctor command with the asciidoctor-diagram extension.

[Install instruction (de)]: https://www.informatik.htw-dresden.de/~zirkelba/praktika/se/arbeiten-mit-git-und-asciidoc/installation-und-konfiguration/index.html#variante2asciidoctorlokal_installiert

Installation

[lazy.nvim]

[lazy.nvim]: https://github.com/folke/lazy.nvim

{
  'tigion/nvim-asciidoc-preview',
  ft = { 'asciidoc' },
  build = 'cd server && npm install --omit=dev --no-save',
  ---@module 'asciidoc-preview'
  ---@type asciidoc-preview.Config
  opts = {
    -- Add user configuration here
  },
}

[packer.nvim]

[packer.nvim]: https://github.com/wbthomason/packer.nvim

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

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 = {
    -- 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',
-- Use Asciidoctor configuration files (.asciidoctorconfig or .asciidoctorconfig.adoc).     -- The nearest configurations win over the farther ones.     -- This option is only relevant if the server converter is set to js.     useasciidoctorconfigs = false, ---@type boolean   }, }

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

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?

[auto-save.nvim]: https://github.com/okuuva/auto-save.nvim [autosave.nvim]: https://github.com/brianhuster/autosave.nvim

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

How do I report an issue?

• Open an AsciiDoc document in Neovim.
• Run the :checkhealth asciidoc-preview command.
• Open a new Issue.
• Describe your problem and include:

[!WARNING]

The nvim-asciidoc-preview-server.log file contains private information

from the current/last session. These are, for example, the (user) name of

your home directory and the file names of the AsciiDoc files used.

If you don't want to share this information with others,

remove or anonymize the relevant parts.