The autorest project uses this actually.

It works by embedding yaml code blocks into a markdown file.

It’s actually not completely awful and has proven somewhat useful to have a configuration clearly documented within the config.

https://github.com/Azure/autorest/blob/main/docs/generate/re...