Adding Plain text headers in API Blueprint

Question

API Blueprint appears to have an undocumented rule that prevents plain text headers below or between resource groups. I have three plain text headers above my resource group that display with no problems, but if I try to put a plain text header below it, I get the following “semantic issues” in Apiary:

unexpected header block, expected a group, resource or an definition, e.g. '# Group <name>', '# <resource name> [<URI>]' or '# <HTTP method> <URI>

dangling message-body asset, expected a pre-formatted code block, indent every of it's line by 12 spaces or 3 tabs

The documentation states "Any following resource definition is considered to be a part of this group until another group is defined", but it doesn't address other types of headers.

Can this be overcome or do I need to keep all my plain text headers above my resource group?

Answer 1

do I need to keep all my plain text headers above my resource group?

Yes. And even there it might/should fail.

Once a Resource Group section is opened in API Blueprint, only the following can follow:

• 0+ Resource Group sections
  • 0+ Resource sections
• 0+ Data Structures section

The designed space for Markdown annotations in API Blueprint are indented blocks under a documented section header (resource, group, ...). This is called a section description in the documentation.

The full structure of an API Blueprint document conforms to this grammar.