Coming from tut

This is a reference guide to migrating from tut to mdoc. It's not possible to automatically migrate tut documentation to mdoc because mdoc uses program semantics while tut uses REPL semantics. This means that some tut documentation can't compile with mdoc without manual changes.

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`

Migration script

The following script can be used to translate the most basic and mechanical differences between tut and mdoc. It is normal that mdoc reports compile errors after running the migration script and you need some manual fixing to get the documents compiling.

File: migrate-tut.sh

#!/bin/bash
find . -name '*.md' -type f -exec perl -pi -e '
  s/```tut:book/```scala mdoc/g;
  s/```tut/```scala mdoc/g;
' {} +

sbt-tut

Use the sbt-mdoc plugin instead of sbt-tut and run sbt docs/mdoc instead of sbt docs/tut.

// project/plugins.sbt
- addSbtPlugin("org.tpolecat" % "tut-plugin" % "0.6.10")
+ addSbtPlugin("org.scalameta" % "sbt-mdoc" % "2.6.2")
// build.sbt
- enablePlugins(TutPlugin)
+ enablePlugins(MdocPlugin)

The sbt-mdoc plugin exposes only one task mdoc .

tut	mdoc
`tut`	`mdoc`
`tutQuick`	`mdoc --watch`
`tutOnly path/doc.md`	`mdoc --include doc.md`
`tutSourceDirectory`	`mdocIn`
`tutTargetDirectory`	`mdocOut`
`tutNameFilter`	`mdoc --include <glob> --exclude <glob>`
`scalacOptions in Tut`	`scalacOptions in Compile`
`tutPluginJars`	`addCompilerPlugin()`

Note that mdoc does not use the Scala REPL so compiler options like -Ywarn-unused work normally.

`:fail`

The tut :fail modifier is split in two separate mdoc modifiers.

:fail: for compile errors, mdoc uses a custom compilation mode for these code fences.
:crash: for runtime errors, mdoc instruments these code fences like normal except they're wrapped in try/catch blocks.

Double binding

It's not possible by default to define the same variable name twice with mdoc. In tut, the following program is valid.

```tut
val x = 1
val x = 2
```

In mdoc, that program does not compile because the document is compiled as a normal Scala program.

Before:

```scala mdoc
val x = 1
```
```scala mdoc
val x = 2
```

Error:

error: tut.md:5:5: x is already defined as value x
val x = 2
    ^

One workaround is to use the mdoc:nest modifier, which wraps subsequent code blocks in scala.Predef.locally{...}.

Before:

```scala mdoc
val x = 1
val y = 2
```
```scala mdoc:nest
val x = 3 + y
```

After:

```scala
val x = 1
// x: Int = 1
val y = 2
// y: Int = 2
```
```scala
val x = 3 + y
// x: Int = 5
```

Another workaround is to define a separate variable name.

 ```scala mdoc
-val x = 2
+val y = 2
 ```

Another workaround is to use the :reset modifier.

-```scala mdoc
+```scala mdoc:reset
 val x = 2
 ```

However, note that :reset discards all previous imports and declarations in the document.