Is there something like javadoc or rdoc for documenting YAML files, so that we could extract it into HTML documentation? Ideally with markdown syntax.
As it appears in the comments to the question, generally speaking, all that is necessary for documenting YAML is to create a section of the YAML content devoted specifically to documentation or metadata.
The only noteworthy challenge is determining whether you want your documentation section to conform with the conventions of any of the various syntax-styles for documenting code (e.g., Doxygen, NaturalDocs, whatever).
Creating a metadata section in YAML is very straightforward, you can do it simply by creating an inline string where you dump all your documentation as a single block.
## comments ## NOTE: YAML generally throws your comments away, so they are not very useful ## for round-trip metadata meta: | Here is all my documentation and metadata blah blah blah. data: branch_one: - caption: blah blah date: blah blah details: blah blah - caption: blah two date: blah blah details: blah blah branch_two: [..]