I had a conversation with Jarno Elovirta and Radu Coravu about YAML headers in Markdown and when/how to use them. I am waiting to hear from George Bina, who will be presenting about Markdown and DITA at DITA NA in San Diego.
Their input was excellent and made me remember the original vision for MDITA that Michael and I talked about with Jenifer Schlotfeld and Mike Wilson back in 2014. Insert Alan Houser comment about LwDITA being slow... ;-)
The original plan was that an author could bring any well-formed Markdown file (well-formed here means following CommonMark) and MDITA will let it play with other DITA files, giving it an id attribute based on its title (Jarno mentioned that Wikipedia uses that kind of mechanism) and treating its first paragraph as a short description by default.
If the author wants DITA features like conrefs, then she needs to use raw XML (which CommonMark allows). Example:
# Basic Concepts of Network Lighting
You can network LED light bulbs together from your <ph keyref="product-name" /> to operate wirelessly from a remote control.
<p id="power-off">Make sure power to the fixture where you are installing the light bulb is turned OFF.</p>
<p conref="low-power.dita#low-power/disconnect-warning" />
If the author does not need conrefs or any other DITA-like features, then pretty much any CommonMark-friendly file will be ok.
Then we have optional (I am thinking about the conformance statements OASIS needs in the spec) features that can come in a YAML header: don't want your first paragraph to be a shortdesc? Then check it off here. Need to add more topic metadata? Do it here. Need to specify an ID attribute? Here you can do it. Example:
author: Juan Smith
Answering Keith's question: I am worried that if we make the YAML header required, nobody is going to adopt this baby.
Carlos Evia, Ph.D.
Director of Professional and Technical Writing
Associate Professor of Technical Communication
Department of English
Center for Human-Computer Interaction
Blacksburg, VA 24061-0112