Mallard allows you to declare a content type for code blocks, which can then be used for syntax highlighting. We ship a copy of the excellent highlight.js with yelp-xsl, which in turn is used by tools like Yelp, yelp-build, and Pintail. And we colorize what highlight.js gives us using the same color templates used in the rest of the stack.
With Mallard 1.0, the way to declare the content type of a code block is using a mime attribute, which takes a MIME type.
<code mime="text/x-csrc">
This seemed like a good idea at the time. MIME types are the most universal standard for identifying stuff like this, for better or for worse. In practice, it’s been pretty cumbersome. Almost none of the kinds of things you’d put in a code block have registered MIME types. You just have to look up and remember arbitrary long strings. Sad face.
In Mallard 1.1, we’re introducing the type attribute and deprecating the mime attribute. The type attribute can take a simple, short string identifier, just like other documentation formats use.
<code type="c">
The strings are shorter than ad hoc MIME types, and generally easier to remember, or even to guess. For most programming languages, both the file extension and the lowercase name of the language probably work. If they don’t, tell us. The type attribute can also take a space-separated list. So you can list a more specific type alongside a generic type you know will match. This is useful for XML vocabularies.
<code type="xml mallard">
This is also particularly useful when you’re also doing things besides syntax highlighting with code blocks of a certain type. The type attribute (and mime before it) is useful for syntax highlighting, but that’s not its only purpose. You could use it to extract code samples for linting, for example. On projectmallard.org, we automatically extract the RELAX NG schemas from the specifications using (currently) the mime attribute. So it can be useful to list multiple types.
One other really nice thing about using the type attribute is that it takes advantage of a syntax shorthand in Ducktype. Ducktype is a compact syntax designed to do everything Mallard can do. Attributes like type, style, and xref are so common that Ducktype gives you a shorthand way of writing them. For the type attribute, you just put the value there on its own. So in Ducktype, it’s as easy as this:
[code c]
Or this:
[code xml mallard]
We could always use help with testing and with updating the documentation. See my post to mallard-list for more information.
