Playground Releases Tools

Embedding Kotlin Playground

Oh yes, this is a runnable Kotlin snippet embedded right in the blog post.
Note that you can not only run it, but you can also change the code:

Cool, isn’t it? Note that completion works too.

Often you don’t want to show all the code in the snippet, but instead only the most interesting and substantial parts of it. This is possible as well.

You can also add tests:

You can use JavaScript as a target or even draw on a canvas:

Sometimes you don’t need or can’t make a runnable sample. In that case you can apply a highlight-only attribute and get the snippet exactly in the same style, but without the ability to run it.

Embedded Kotlin playground and how it’s done

Historically, thousands of newcomers used try.kotlinlang.org as an interactive way of learning the language. In particular, Kotlin Koans online have been extremely popular. More advanced users use this playground for trying small snippets without opening an IDE, for example before pasting code as an answer on StackOverflow.
Embedded Kotlin Playground works on the same technology, but lets you write and run samples on your webpages. It compiles code on our backend server and then runs either in your browser (if the target platform is JS) or on a server (if the target is set to JVM).

Frontend

Adding an embedded Kotlin playground is as easy as writing a single line in the page header:

<script src="https://unpkg.com/kotlin-playground@1" data-selector="code"></script>

Now all the code blocks on the page will be converted to runnable Kotlin snippets. Of course, data-selector is customizable and you can apply the script only to some particular class. There’s also an option to configure a Kotlin playground manually:

<script src="https://unpkg.com/kotlin-playground@1"></script>

<script>
document.addEventListener('DOMContentLoaded', function() {
  KotlinPlayground('.code-blocks-selector');
});
</script>

There’re also a lot of different installation and customization options. Read more in the documentation.

Backend

The backend part of the playground compiles the code and provides information for completion and highlighting. Generally, you shouldn’t need to bother about the backend and you may stick with our server unless you want to reference custom JVM libraries.

For writing examples that use some external library, for example when you’re creating interactive documentation for your library, you will have to configure and run your instance of the playground backend. It’s very easy to do: you’ll just need to add any dependencies, run two predefined Gradle tasks, then docker-compose up, and voila – the server is running. See these instructions for details.

Where it’s already used

  • We already extensively use this technology for writing Kotlin documentation on the official website. All new bits of documentation are written using runnable samples (see Basic syntax, What’s new in 1.1 and 1.2, Lambdas and Coroutines. For some functions from the standard library, there are live examples as well (see groupBy for example).
  • Kotlin By Example is written with Kotlin-Playground live samples.
  • We’ve also released a plugin for WordPress. It adds a [kotlin] shortcode which allows embedding an interactive Kotlin playground in any post. All the samples on this page are written with the help of this plugin.
    preview
  • On the Kotlin forum, you can use the run-kotlin language in markdown syntax to answer questions, with full correctness guaranteed.
    discuss3

Where this can be used

Kotlin Playground improves the reading experience and increases the expressiveness of code examples. It allows readers to not only see the code but also run it, change it, play with it, and run it again. We encourage all authors to use runnable Kotlin snippets, especially when creating:

  • Learning courses
  • Supplementary materials for slides and books
  • Documentation for libraries and frameworks
  • Examples in blog posts

Later we are going to support scripting in Kotlin Playground as well.

image description