Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

SBT highlight compiler

This SBT plugin extracts the Scala examples from a markdown/jekyllrb documentation, and compile the extracted codes, to keep the documentation valid.


Considering a documentation using a markdown format with some Scala code samples as following.

This is a markdown documentation with a code sample.

val foo = List("Bar", "Lorem", "Ipsum")

Using this SBT plugin, the code can be extracted in a generated .scala file, and then compiled to be sure it's valid.

Get started

This plugin requires SBT 0.13+.

You need to update the project/plugins.sbt.

resolvers ++= Seq(
  "Tatami Releases" at "")

addSbtPlugin("cchantep" % "sbt-hl-compiler" % "0.8")

By default, it will scan all the *.md files in the base directory.

The following options are available.

highlightStartToken := "{% highlight scala %}"
// Token to detect the start of a Scala code sample.
// Can be defined in the scope ThisBuild
// Default: "```scala"

highlightEndToken := "{% endhighlight %}"
// Token to detect the end of a Scala code sample.
// Default: "```"

highlightDirectory := baseDirectory.value / "doc"
// The directory scanned for the documentation files.
// Default: project base directory

includeFilter in doc := "*.ext"
// Default: "*.md"

excludeFilter in doc := "_excludes"
// Default: undefined

This plugin also append the highlightDirectory to the watchSources settings, so a documentation build is triggered each time a source document is updated.

See a SBT build using this plugin.

In case of SBT Multi-Project

It may be required to disable this plugin on the aggregation if some examples in files of the sub-project require some dependencies specific to the sub-project (not available at the aggregation time).

lazy val root = Project(id = "...", base = file(".")).
  aggregate(/* ... */).

Extraction behaviour

If a code sample doesn't start with a package ... statement, the .scala generated file wraps this code in a trait with a unique name.

Considering a documentation as following.

This is a markdown documentation with a code sample.
val foo = List("Bar", "Lorem", "Ipsum")

The code in the generated file will be:

package samplesY

trait SampleX {
// File '/path/to/the/', line N

val foo = List("Bar", "Lorem", "Ipsum")


All the code samples without a package in the same documentation files are also gather in a same generated package, samplesY in the previous example.

It allows to share some definitions accross the code samples of a documentation file.

This is how to create a value:

val value = createIt()

Then you can use it.



This is built using SBT.

sbt '^ publishLocal'

Build Status


⚙️ SBT plugin to extract code sample from documentation files and compile/validation them








No releases published


No packages published