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

1. panvimdoc

   1 14 278 7.9 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?

2. CodeRabbit

   coderabbit.ai featured

   CodeRabbit: AI Code Reviews for Developers. Revolutionize your code reviews with AI. CodeRabbit offers PR summaries, code walkthroughs, 1-click suggestions, and AST-based analysis. Boost productivity and code quality across all major languages with each PR.

   

3. neovim

   2 1,421 87,095 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.

4. nvim-neoclip.lua

   3 13 1,055 6.1 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?

5. lualine.nvim

   4 73 6,703 7.9 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 😉

6. vim-remembers

   5 1 28 4.7 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.

7. rnvimr

   6 28 829 2.6 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.

8. nvim-bqf

   7 38 1,833 4.6 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

9. SaaSHub

   www.saashub.com featured

   SaaSHub - Software Alternatives and Reviews. SaaSHub helps you find the best software and product alternatives

   

10. nvim-hlslens

    8 21 809 5.1 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

11. nvim-hclipboard

    9 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

12. vim-sisr

    10 1 2 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.

13. nvim-libmodal

    11 9 122 5.6 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.

14. md2vim

    12 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?

15. orgmode

    13 94 3,252 9.5 Lua

    Orgmode clone written in Lua for Neovim 0.10.0+.

    

    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