Interesting point. Are you thinking about this from the parser/tooling side, or from the person writing and reviewing the file?
We intentionally started from Markdown because we wanted .void files to stay standards-compliant and not reinvent a new document format. Markdown already gives us a familiar, portable way to write docs, notes, examples, and explanations around the request.
Frontmatter handles the document-level metadata, Markdown stays the human-readable documentation layer, and the structured Voiden blocks handle the executable API parts.
We could put everything into one YAML object, but then the file becomes more like a config file than a Markdown document. The tradeoff we’re making is: keep the file readable in GitHub, PRs, and plain text editors while it still gives Voiden enough structure to execute requests reliably.
:)