Document status of syntax highlighting

[UppaJung]

I've spent > 4 hours trying to figure out whether I'm not getting syntax highlighting to work in dokka-generated HTML because it's unsupported or because I've configured something wrong. (It's not clear from issue #460, as I'm not sure what Markdown Key is, or from #524).

I found that HTML is generated with <code> blocks with class lang-kotlin, but no css for that class is generated.

I would expect that most other users also expect modern documentation systems to support syntax highlighting (those of us working with JNI get support for it in the ancient doxygen system) and will also spend lots of time trying to figure out what they're doing wrong.

If those css tags are being generated but there's actually no support for them, would it be possible to update the documentation explicitly report the current state of syntax highlighting support to keep users from going on a wild goose chase looking for it?

[aajtodd]

Including example code in module includes (e.g. Module.md) doesn't even render with lang-kotlin. It spits out

<div class="sample-container">
    <code theme="idea" class="">
        <pre>...</pre>
    </code>
</div>

the markdown file has sample code as:

```kt
// sample code
```

I'm not sure if this is a bug or just how it currently behaves. Would be nice to have prettier code blocks by default similar to GFM

[yalishevant]

fixed in 1.6.0