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?

  • 1
    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. Commented Apr 25, 2020 at 7:12
  • 2
    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. Commented Apr 25, 2020 at 7:19
  • 2
    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. Commented Apr 25, 2020 at 9:19
  • 1
    Thanks for suggestions, code and opinions.
    – petRUShka
    Commented Apr 25, 2020 at 10:17
  • I've found another discussion: vi.stackexchange.com/questions/3752/…
    – petRUShka
    Commented Apr 25, 2020 at 14:38


Browse other questions tagged or ask your own question.