Typechecked Snippets

As has been mentioned a couple of times throughout this tutorial, this plugin supports the compilation of Scala code written in markdown files. This process is now being delegated on two different sbt plugins: tut and mdoc.

Tut

Tut is the option by default, so no special action is required from your side, apart from following the guides defined in its microsite. Some recommendations:

  • Add your markdown files in this path by default: src/main/tut/.
  • If you want to place your documments in a different path, just set the sbt property tutSourceDirectory := your-path being your-path a SettingKey[File].
  • Mark the snippets that you want to compile, following this convention: ```tut or any of its modifiers

mdoc

This feature has been recently added and includes some amazing features that are explained very well. Here is some advice for using this in your microsite:

  • Add your markdown files in this path by default: docs/.
  • Set this property accordingly: micrositeCompilingDocsTool := WithMdoc
  • If you want to place your documents in a different path, just set the sbt property mdocIn := your-path being your-path a SettingKey[File].
  • Mark the snippets that you want to compile, following this convention: ```scala mdoc or any of its modifiers

Migrating from tut to mdoc

You can migrate your microsite from tut to mdoc in 3 smooth steps:

  • Set this property accordingly: micrositeCompilingDocsTool := WithMdoc
  • Set the property mdocIn := tutSourceDirectory, thus we are setting the source for mdoc as it used to be for tut.
  • Replace tut with scala mdoc in the snippets modifiers following this table of compatibilities
tut mdoc
:fail :fail for compile error, :crash for runtime error
:nofail n/a
:silent :silent
:plain n/a
:invisible :invisible
:book can be removed, mdoc uses book mode by default
:evaluated n/a
:passthrough :passthrough
:decorate(param) n/a
:reset :reset

There is also a script that does the replacement for you.