mdoc

mdoc

  • Docs
  • Blog
  • GitHub

›Overview

Overview

  • Installation
  • Why mdoc?
  • Coming from tut
  • Changelog

Modifiers

  • JVM
  • Scala.js

Site generators

  • Docusaurus
Edit

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.

tutmdoc
:fail:fail for compile error, :crash for runtime error
:nofailn/a
:silent:silent
:plainn/a
:invisible:invisible
:bookcan be removed, mdoc uses book mode by default
:evaluatedn/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.7.1")
// build.sbt
- enablePlugins(TutPlugin)
+ enablePlugins(MdocPlugin)

The sbt-mdoc plugin exposes only one task mdoc .

tutmdoc
tutmdoc
tutQuickmdoc --watch
tutOnly path/doc.mdmdoc --include doc.md
tutSourceDirectorymdocIn
tutTargetDirectorymdocOut
tutNameFiltermdoc --include <glob> --exclude <glob>
scalacOptions in TutscalacOptions in Compile
tutPluginJarsaddCompilerPlugin()

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.

← Why mdoc?Changelog →
  • Migration script
  • sbt-tut
  • :fail
  • Double binding
mdoc
Docs
Get started
Community
Chat on Gitter
More
GitHub
Copyright © 2025 mdoc developers