Jekyll ScalaFiddle

Integrate ScalaFiddle easily into your Jekyll documentation using this plugin.

Installation

1. Add the following to your site's Gemfile:

gem 'jekyll-scalafiddle'

1. Add the following to your site's _config.yml:

plugins:
  - jekyll-scalafiddle

Installation for sbt-microsites

sbt-microsites is a plugin for sbt that helps Scala developers build and publish documentation for their project. It's based on Jekyll, so you can use this same plugin. Unlike regular Jekyll, you cannot use gem to install the plugin, but you must manually copy the jekyll-scalafiddle.rb file under a plugins directory in your microsite project.

$ mkdir plugins
$ cd plugins
$ curl -o jekyll-scalafiddle.rb https://raw.githubusercontent.com/scalafiddle/scalafiddle-core/master/integrations/jekyll/lib/jekyll-scalafiddle.rb

Usage

The ScalaFiddle plugin provides a tag scalafiddle which you can use to convert a code block in your documentation into an editable and runnable fiddle. Simply surround a code block with the tag as shown below.

Before:

```scala
def sum(a: Int, b: Int) = a + b

println(sum(2, 2))
```

After:

{% scalafiddle %}
```scala
def sum(a: Int, b: Int) = a + b

println(sum(2, 2))
```
{% endscalafiddle %}

This will instruct the plugin to generate a special <div> around your code which will turn it into an editable fiddle when the viewer clicks the Run button.

Parameters

Each fiddle can be further customized with parameters. These parameters are described in more detail in the main integration documentation. For example:

{% scalafiddle prefix="import scala.util.Random" theme="dark" %}

Templates

Each ScalaFiddle consists of a "user visible" part and of a template that is hidden from the user. You can use this template code to provide additional or common functionality without cluttering each of your fiddles. A template can contain code that comes before the user code, or also code that comes afterwards (separated by a line starting with four slashes ////).

The example template below wraps the user's code into a {} block, assigns it to a val and prints the result at the end.

val result = {
////
}
println(result)

Templates are stored by default under the _scalafiddle directory (which can be changed via configuration). Each template must have a .scala extension. For the example above, the correct file name would be _scalafiddle/Result.scala

Use the template in documentation

{% scalafiddle template="Result" %}
```scala
def sum(a: Int, b: Int) = a + b
sum(2, 2)
```
{% endscalafiddle %}

You will see only the user defined code in the fiddle. The result pane, however, shows you that the template code was also run.

The final code executed will actually be:

val result = {
def sum(a: Int, b: Int) = a + b
sum(2, 2)
}
println(result)

Configuration

The ScalaFiddle plugin can be configured the same as any other Jekyll plugin via _config.yaml. For example:

scalafiddle:
  dependency: io.circe %%% circe-core % 0.8.0,io.circe %%% circe-generic % 0.8.0,io.circe %%% circe-parser % 0.8.0
  scalaFiddleUrl: http://localhost:8880/

In the configuration you can provide default values for fiddle parameters such as dependency, minheight, theme etc. Typically you would use the dependency configuration in a library documentation where each code example has the same dependency to your library.

You can also configure the location of templates with templateDir and the URL for the ScalaFiddle service (if you want to run your own ScalaFiddle server, for example locally) using scalaFiddleUrl.

Configuration with sbt-microsites

To configure the ScalaFiddle plugin, use the micrositeConfigYaml option in your project definition. For example:

micrositeConfigYaml := ConfigYml(yamlInline =
"""
  |scalafiddle:
  |  dependency: io.circe %%% circe-core % 0.8.0,io.circe %%% circe-generic % 0.8.0,io.circe %%% circe-parser % 0.8.0
  |  scalaFiddleUrl: http://localhost:8880/
  """.stripMargin)