feat: Generate Markdown-doc from Variantfile

[mumoshu]

As an ordinary engineer I often write documentation for my one-off scripts in GitHub Flavored Markdown. But it tends to get outdated quickly due to various reasons, including I just forget updating it, it isn't runnable hence unable to apply CI practices on it.

There's already a few task runners that tries to aid this issue, which uses markdown as the primary configuration syntax for tasks, like saku and maid. The idea of turning the documentation into a task runner is great, but none of those seems mature. Especially their syntaxes and features seems very limited.

On the other hand variant is already a feature-rich task runner. How about adding the markdown as the secondary configuration syntax for your command and tasks, and allows easy conversion between the existing YAML-based syntax and the brand-new Markdown-based syntax?

It will provide you:

1. Auto-generated doc of your command (YAML->MD
2. Runnable documentation (Run the MD file as a variant command
3. Easily switch your primary configuration syntax (YAML <-> MD conversion

[osterman]

In a similar, but related PR we added support for "man pages" to geodesic. However, we didn't want to write groff, so we used markdown with pandoc to generate the man pages.

cloudposse/geodesic#467

In my own words, do you want a way to run the variant command and have it generate markdown suitable for appending to the README.md (for example)?

[aroq]

@mumoshu,
In my opinion, it is better to generate markdown from "variant" (yaml) configuration. You can use something like "gomplate" for that, but I'm not sure about using markdown file as a "Source of truth" with actual tasks and configuration.

[osterman]

I tend to agree with @aroq on this point.

[mumoshu]

@aroq @osterman Thanks for your feedbacks!

Yep, generating md from variant yaml should work better and sounds more feasible.

Originally I wanted the md-syntax as the first-class citizen so that you can ensure that the instructions and commands written in the md document is correct and can be verified to work(by running integration tests against the commands defined in the md). But almost certainly we can ensure the md doc is correct as long as variant generates md docs from variant yaml correctly :)