{"id":19373630,"url":"https://github.com/tigion/nvim-asciidoc-preview","last_synced_at":"2025-04-23T17:32:07.961Z","repository":{"id":66547644,"uuid":"591388768","full_name":"tigion/nvim-asciidoc-preview","owner":"tigion","description":"A Neovim plugin to preview AsciiDoc documents in the browser.","archived":false,"fork":false,"pushed_at":"2025-02-16T11:00:00.000Z","size":285,"stargazers_count":43,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-18T17:14:11.666Z","etag":null,"topics":["asciidoc","asciidoctor","lua","neovim","neovim-plugin","node-js"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tigion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-20T16:28:47.000Z","updated_at":"2025-03-15T01:41:06.000Z","dependencies_parsed_at":"2024-03-06T16:05:57.395Z","dependency_job_id":"c77f0dd5-23a9-466f-a458-23dd6435c09e","html_url":"https://github.com/tigion/nvim-asciidoc-preview","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigion%2Fnvim-asciidoc-preview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigion%2Fnvim-asciidoc-preview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigion%2Fnvim-asciidoc-preview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigion%2Fnvim-asciidoc-preview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tigion","download_url":"https://codeload.github.com/tigion/nvim-asciidoc-preview/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250480585,"owners_count":21437574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asciidoc","asciidoctor","lua","neovim","neovim-plugin","node-js"],"created_at":"2024-11-10T08:30:34.423Z","updated_at":"2025-04-23T17:32:07.945Z","avatar_url":"https://github.com/tigion.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"readme":"# nvim-asciidoc-preview\n\nA simple AsciiDoc preview while editing AsciiDoc documents in Neovim.\n\n\u003e [!WARNING]\n\u003e The plugin is ~~in an early stage~~ not fully tested.\n\u003e Use at your own risk.\n\u003e\n\u003e Works on: ✅ Linux, ✅ macOS and ✅ Windows with WSL2\n\n\u003cimg width=\"1000\" alt=\"Screenshot 2024-10-30\" src=\"https://github.com/user-attachments/assets/ac63f6df-292b-4d6d-8680-829083d0dc16\"\u003e\n\nThe plugin started as a playground for learning Neovim plugin programming\nwith Lua and a server component with Node.js.\nTherefore, many things are not solved optimally and partly implemented\ntwice (plugin and server). Helpful tips are welcome.\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [FAQ](#faq)\n\n## Features\n\n- Once started with `:AsciiDocPreview`, a preview of the current AsciiDoc\n  file is shown in the web browser.\n- The preview is updated every time the AsciiDoc file is saved or a new\n  AsciiDoc file is opened.\n  - Updating the preview while typing is currently not supported.\n    A workaround is in the [FAQ](#faq-live-preview).\n- When exiting Neovim, no open Asciidoc files exists or using the\n  `:AsciiDocPreviewStop` command, the preview server is terminated in the\n  background.\n- The generation of the HTML preview is done either with:\n  - [Asciidoctor.js](https://docs.asciidoctor.org/asciidoctor.js/latest/)\n    (default, no local installed Asciidoctor needed)\n  - Or the locally installed [Asciidoctor](https://docs.asciidoctor.org/asciidoctor/latest/)\n    tools (`asciidoctor` and `asciidoctor-diagram`).\n\n## Requirements\n\n- Neovim \u003e= 0.8\n- Node.js with `node` and `npm` command\n- `curl` command\n\nThe plugin allows optionally using the local installed Asciidoctor tools.\n\n- This requires the `asciidoctor` command with the `asciidoctor-diagram` extension.\n  - [Install instruction (de)]\n\n[Install instruction (de)]: https://www.informatik.htw-dresden.de/~zirkelba/praktika/se/arbeiten-mit-git-und-asciidoc/installation-und-konfiguration/index.html#_variante_2_asciidoctor_lokal_installiert\n\n## Installation\n\n### [lazy.nvim]\n\n[lazy.nvim]: https://github.com/folke/lazy.nvim\n\n```lua\n{\n  'tigion/nvim-asciidoc-preview',\n  ft = { 'asciidoc' },\n  build = 'cd server \u0026\u0026 npm install --omit=dev',\n  opts = {\n    -- Add user configuration here\n  },\n}\n```\n\n### [packer.nvim]\n\n[packer.nvim]: https://github.com/wbthomason/packer.nvim\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow instruction\u003c/summary\u003e\n\n```lua\nuse({\n  'tigion/nvim-asciidoc-preview',\n  run = 'cd server \u0026\u0026 npm install --omit=dev',\n  config = function()\n    require('asciidoc-preview').setup({\n      -- Add user configuration here\n    })\n  end,\n})\n```\n\n\u003c/details\u003e\n\n## Configuration\n\nFor [lazy.nvim](https://github.com/folke/lazy.nvim) use the `opts` or `config` property.\n\n```lua\nopts = {\n  server = {\n    converter = 'js'\n  },\n  preview = {\n    position = 'current',\n  },\n}\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eVariant with config\u003c/summary\u003e\n\n```lua\nconfig = function()\n  require('asciidoc-preview').setup({\n    server = {\n      converter = 'js'\n    },\n    preview = {\n      position = 'current',\n    },\n  })\nend,\n```\n\n\u003c/details\u003e\n\nFor other plugin manager, call the setup function\n`require('asciidoc-preview').setup({ ... })` directly.\n\n### Default Options\n\nCurrently available settings for the user:\n\n```lua\n{\n  server = {\n    -- Determines how the AsciiDoc file is converted to HTML for the preview.\n    -- `js`  - asciidoctor.js (no local installation needed)\n    -- `cmd` - asciidoctor command (local installation needed)\n    converter = 'js',\n\n    -- Determines the local port of the preview website.\n    -- Must be between 10000 and 65535.\n    port = 11235,\n  },\n  preview = {\n    -- Determines the scroll position of the preview website.\n    -- `current` - Keep current scroll position\n    -- `start`   - Start of the website\n    -- `sync`    - (experimental) Same (similar) position as in Neovim\n    --             =\u003e inaccurate, because very content dependent\n    position = 'current',\n  },\n}\n```\n\n## Usage\n\n| Command                  | Description                                                                                                       |\n| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |\n| `:AsciiDocPreview`       | Starts the AsciiDoc preview server in background and opens the current AsciiDoc file in the standard web browser. |\n| `:AsciiDocPreviewStop`   | (if needed) Stops the AsciiDoc preview server.                                                                    |\n| `:AsciiDocPreviewOpen`   | (if needed) (Re)Opens the current AsciiDoc file in the standard web browser.                                      |\n| `:AsciiDocPreviewNotify` | (if needed) Notifies the server to display the current AsciiDoc file in the preview.                              |\n\nA keymap suggestion:\n\n```lua\nvim.keymap.set('n', '\u003cLeader\u003ecp', ':AsciiDocPreview\u003cCR\u003e', { desc = 'Preview AsciiDoc document' })\n```\n\n- To use the same keymap for different file types and plugins (e.g. [markdown-preview.nvim](https://github.com/iamcco/markdown-preview.nvim)),\n  place the following in `after/ftplugin/asciidoc.lua`:\n\n  ```lua\n  local opts = { buffer = true, silent = true }\n  opts.desc = 'Preview AsciiDoc document'\n  vim.keymap.set('n', '\u003cLeader\u003ecp', ':AsciiDocPreview\u003cCR\u003e', opts)\n  ```\n\n  This way the keymap is only set for AsciiDoc files.\n\n## FAQ\n\n### \u003ca name=\"faq-live-preview\"\u003e\u003c/a\u003eIs there a way to update the preview as I edit the AsciiDoc document?\n\nThe plugin itself does currently not support this.\nHowever, you can use an extra plugin for automatic saving like [auto-save.nvim](https://github.com/okuuva/auto-save.nvim) or [autosave.nvim](https://github.com/brianhuster/autosave.nvim) to automatically save the AsciiDoc document after every change.\nThanks to [brianhuster](https://github.com/tigion/nvim-asciidoc-preview/issues/6#issuecomment-2370163011) for the idea.\n\nWith [auto-save.nvim](https://github.com/okuuva/auto-save.nvim) you can use the following [Condition](https://github.com/okuuva/auto-save.nvim#condition) to only automatically save AsciiDoc files:\n\n```lua\n-- Configuration part of the plugin auto-save.nvim\nopts = {\n  -- Activate automatic saving only for specified file types.\n  condition = function(buf)\n    local filetype = vim.fn.getbufvar(buf, \"\u0026filetype\")\n    local filetypes = { 'asciidoc', 'asciidoctor' } -- List of allowed file types.\n    return vim.list_contains(filetypes, filetype)\n  end,\n  -- I think a delay between 1000 and 3000 ms is okay.\n  -- To low delays might cause performance issues with\n  -- the rendering of the AsciiDoc preview!\n  debounce_delay = 2000,\n}\n```\n\n### How do I report an issue?\n\n1. Open an AsciiDoc document in Neovim.\n2. Run the `:checkhealth asciidoc-preview` command.\n3. Open a new [Issue](https://github.com/tigion/nvim-asciidoc-preview/issues/new).\n4. Describe your problem and include:\n   - the `checkhealth` output\n   - the [Installation/Configuration](#installation) with the used package manager\n   - the content of the `~/.local/state/nvim/nvim-asciidoc-preview-server.log` file\n\n\u003e [!WARNING]\n\u003e The `nvim-asciidoc-preview-server.log` file contains **private information**\n\u003e from the current/last session. These are, for example, the name of your\n\u003e **home directory** and the names of the **AsciiDoc files** used.\n\u003e\n\u003e Do **not** share this information with others.\n\u003e So please remove or anonymize this information before.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftigion%2Fnvim-asciidoc-preview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftigion%2Fnvim-asciidoc-preview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftigion%2Fnvim-asciidoc-preview/lists"}