Convert VIM doc (vim help) to Markdown or vice versa

Question

Suppose you are writing a vim plugin hosted on Github (which seems to be a standard for now). You don't want to maintain two help files: README.md (Markdown) and doc/your_plugin.txt (vim help) with quite the same content but different markup language.

So it would be useful to have original help content in one place and automatically convert it to other. Or even better to have templates you can include in both places to have slightly different version of help to new user and search enginges (README.md) and active user (vim help).

How to make this templating or conversion?

UPD I've found another discussion: How do I generate Vim documentation from Markdown notes or inline comments, or are there better ways to add documentation?

I used to have a script for this; not sure if I have it somewhere. But it's not so easy, as some semantics are different. Especially Markdown to Vim is hard (or rather, doing it well). My suggestion is to make the Vim doc/foo.txt a reference manual, and use README as an introduction/tutorial. — Martin Tournoij, Apr 25 '20 at 07:12
Found it; it only converts Vim help to Markdown. It's doesn't really work all that well to create good-looking documents IMO, so I stopped using it years ago, but feel free to use/modify. — Martin Tournoij, Apr 25 '20 at 07:19
If a tool like this existed and worked well, then I agree it would be very useful. However, I think making this would be quite hard, as indicated by @MartinTournoij. Thus I agree with the suggestion to use the Vim doc as the main reference and instead use the README as an introduction and/or tutorial. — Karl Yngve Lervåg, Apr 25 '20 at 09:19
I've found another discussion: https://vi.stackexchange.com/questions/3752/how-do-i-generate-vim-documentation-from-markdown-notes-or-inline-comments-or-a — petRUShka, Apr 25 '20 at 14:38

Convert VIM doc (vim help) to Markdown or vice versa

0 Answers0