✨ Links support in code samples

[CLOVIS-AI]

📝 Description

I am working on Dokka support for Material for MkDocs. One reason is to allow joining the Dokka documentation with regular tutorials, an other is to try to improve the web experience when using Dokka.

One such case is around code samples. There are three very different kinds of code samples that can appear in Dokka documentation (visible with my plugin, but also in the default HTML format):

• Header snippets
• Embedded markdown snippets
• Embedded playground samples

Playground samples are off-topic for this discussion.

Embedded markdown snippets are regular markdown documents. They feature code highlighting but no other features.

Header snippets are generated by Dokka for each symbol. For example, a class gets a small snippet at the start of its page that shows how it is declared in code. Functions, interfaces, etc all possess this header. While they look like regular markdown code snippets initially, they actually have a super-power: they can contain links. Users can click on the type of parameters and return values to navigate to their pages.

Since Samples extracts information from regular markdown snippets and pushes them through the Kotlin compiler, I wonder if it could be possible to extract type information from the Kotlin compiler to provide these additional features (embedded links) in all samples extracted by Samples.

[LVMVRQUXL]

@CLOVIS-AI For now, Kotools Samples inlines code samples, when referenced in the main sources, into regular Markdown code blocks with the corresponding language (Kotlin or Java currently). Like you know, it is not possible to provide links in Markdown code blocks.

I'm very curious about the header snippets. Do you have an example of a header snippet that can appear in the documentation generated by Dokka? I'm new to this topic, so a simple example would be very much appreciated. 😉

[CLOVIS-AI]

Open any Dokka HTML page for a class or method, and you'll see one :)

For example in the prepared documentation:

In the header comment, types are links to other pages. In the regular Markdown snippet, it's not possible to link to other places (yet? 👀)

[LVMVRQUXL]

Okay, now I see what you mean @CLOVIS-AI.

After looking at the HTML page generated by Dokka on the link that you've sent, I see that headers and Markdown code blocks are rendered differently. Maybe, Kotools Samples could generate an HTML code block instead of using Markdown code blocks. This could be possible by using the symbol CSS class, and put text having a link in brackets. Also, this change could have an impact on color rendering for languages like Java. Using a Markdown block has the advantage of supporting this right of the box.

[CLOVIS-AI]

Yeah, definitely. I'll think about it some more and maybe send it as a feature request to Dokka itself.

[LVMVRQUXL]

That would be cool @CLOVIS-AI. Don't hesitate to share this request, when available, in this issue for linking them.