[vent] I really hate that most neovim plugins don't provide docs...

• panvimdoc

  14 226 8.3 CSS

  Write documentation in pandoc markdown. Generate documentation in vimdoc.

Now the issue is that I would like to avoid writing the same information in two formats (that seems just like unnecessary work). I did try some of the conversion tools (such as panvimdoc) but didn't get it working. Which one has people used successfully and could recommend?

• neovim

  1,383 76,256 10.0 Vim Script

  Vim-fork focused on extensibility and usability

  

I've tried :h *bqf* quite a few times and wished I could've used it instead of opening the README from my packpath. As others have said, it seems preferable to have the docs internal and use the README for a description of the project. I feel like there's a disadvantage to doing it in the README, that you can't access the ToC from everywhere (gO in :help), and you also can't easily link to documentation of built-in functions or options.

• InfluxDB

  www.influxdata.com sponsored

  Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.

  

• nvim-neoclip.lua

  13 881 4.4 Lua

  Clipboard manager neovim plugin with telescope integration

But maybe there is no need for duplication. In your view, just so I can get an idea, what do you think in the README of my latest (somewhat popular) plugin neoclip should move from the README to the vimdoc?

• lualine.nvim

  72 5,357 7.8 Lua

  A blazing fast and easy to configure neovim statusline plugin written in pure lua.

  

panvimdoc does a decent job at generating vimdocs . That's been handling lualines docs for a while . You could try it on your plugins 😉

• vim-remembers

  1 24 2.5 Vim Script

  A vim plugin that emulates Notepad++ "remembering" the contents of unnamed files.

No one "learns" one or the other, it's just text and it's trivial to write. And I'm not saying it's trivial out of ignorance, I published a vim plugin and wrote the doc for it vim-remembers.

• rnvimr

  28 771 4.3 Python

  Make Ranger running in a floating window to communicate with Neovim via RPC

I have a terrible experience with vim doc in my first plugin rnvimr. The vim doc is so hard to maintain and makes me unhappy to write something in it, such as align new variables. In fact, I must maintain two documents, one is Markdown, one is vim doc.

• nvim-bqf

  38 1,521 5.9 Lua

  Better quickfix window in Neovim, polish old quickfix window.

I have written nvim-bqf, nvim-hlslens and nvim-hclipboard plugins with Lua. They aren't any :h docs. I think they are simple enough and the README is also clear. If the plugin doc is written detail, I will write it under Markdown and create a command to invoke a new tab or floating window. Vim doc, R.I.P

• WorkOS

  workos.com sponsored

  The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.

  

• nvim-hlslens

  21 705 5.9 Lua

  Hlsearch Lens for Neovim

I have written nvim-bqf, nvim-hlslens and nvim-hclipboard plugins with Lua. They aren't any :h docs. I think they are simple enough and the README is also clear. If the plugin doc is written detail, I will write it under Markdown and create a command to invoke a new tab or floating window. Vim doc, R.I.P

• nvim-hclipboard

  4 19 1.2 Lua

  Discontinued Hijack your clipboard in Neovim

I have written nvim-bqf, nvim-hlslens and nvim-hclipboard plugins with Lua. They aren't any :h docs. I think they are simple enough and the README is also clear. If the plugin doc is written detail, I will write it under Markdown and create a command to invoke a new tab or floating window. Vim doc, R.I.P

• vim-sisr

  1 1 10.0 Vim Script

  Vim-plugin to be able to search in specified syntax regions

As I mentioned, I have written vimdoc before, so for example this from my very first plugin, so that's not really what's stopping me, only duplication of things.

• nvim-libmodal

  9 115 5.8 Lua

  Create new "modes" for Neovim!

Maybe I'm alone in it, but I actually have liked VimDoc so far for detailed documentation, because of its structure and conventions. You can typically just copy-paste a few templates from a register and insert your relevant data as needed. As for right-aligning new variables, there's always :h right-align or just foregoing it altogether. The spacing is for look rather than function.

• md2vim

  5 73 0.0 Go

  Discontinued Tool for automatically converting markdown to vimdoc format

There are utilities such as https://github.com/FooSoft/md2vim that can convert between markdown and vimdoc. One could keep documentation in the readme and then use this to convert to vimdoc?

• orgmode

  94 2,732 9.2 Lua

  Orgmode clone written in Lua for Neovim 0.9+.

  

I'm using this for orgmode.nvim. It works more less ok. I just update the docs markdown and generate vim doc from it.

Suggest a related project