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 has been deprecated, please switch to mdoc (see next section). If for some reason you want to keep using it, here there are some recommendations:

  • Set this property accordingly: micrositeCompilingDocsTool := WithTut.
  • 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

mdoc is the option by default, so no special action is required from your side. See the scalameta site for more information here. Here is some advice for using this in your microsite:

  • Add your markdown files in this path by default: docs/.
  • By default, the setting micrositeCompilingDocsTool will be WithMdoc, so no action would be required.
  • 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 mdoc in the snippets modifiers following this migration guide.

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