Extending DocC with additional metadata to provide alternate displays for code blocks

While ```yaml,copy creates a situation where syntax highlighting is lost in a non-DocC renderer, using a directive means that the directive is just pasted wholesale into the rendered output, which i would consider to be even more disruptive.

As @Joseph_Heck said, DocC has already diverged from GitHub-Flavored Markdown with the introduction of term-definition lists, with column alignment markers in tables, and even with directives in the first place. (Tables themselves are already an extension from basic Markdown!) Expecting Markdown to be interoperable is already an uphill battle once you try to get past the modest feature set from the original Markdown.pl implementation. Adding extra information to the language tag in a fenced code block feels like the least-invasive option for simple configuration flags like this.

2 Likes