Installation

Create a docs directory and docs/readme.md file with some basic content.

$ tree
.
└── docs
    └── readme.md
$ cat docs/readme.md
# My Project

To install my project
```scala
libraryDependencies += "com" % "lib" % "@VERSION@"
```

```scala mdoc
val x = 1
List(x, x)
```

We process the markdown with one of the following mdoc integrations:

sbt-mdoc: for usage with sbt projects.
command-line: to run from the console outside of a build tool.
library API: for programmatic usage.

The generated readme.md will look like this.

# My Project

To install my project

```scala
libraryDependencies += "com" % "lib" % "1.0.0"
```

```scala
val x = 1
// x: Int = 1
List(x, x)
// res0: List[Int] = List(1, 1)
```

Observe that VERSION has been replaced with 1.0.0 and that the scala mdoc code fence has been evaluated.

sbt

Install the sbt-mdoc plugin and create a docs project in build.sbt that enables mdoc.MdocPlugin.

// project/plugins.sbt
addSbtPlugin("org.scalameta" % "sbt-mdoc" % "1.2.3" )
// build.sbt
lazy val myproject = project  // your existing library
  .settings(...)
lazy val docs = project       // new documentation project
  .in(file("myproject-docs")) // important: it must not be docs/
  .dependsOn(myproject)
  .enablePlugins(MdocPlugin)

Next, from the sbt shell, run the docs/mdoc task to generate the documentation site. By default, the mdoc task looks for markdown sources in the toplevel docs/ directory.

// sbt shell
> docs/mdoc

Update mdocVariables to include site variables like @VERSION@.

// build.sbt
lazy val docs = project
  .in(file("myproject-docs"))
  .settings(
+   mdocVariables := Map(
+     "VERSION" -> version.value
+   )
  )
  .dependsOn(myproject)
  .enablePlugins(MdocPlugin)

The mdoc task runs the mdoc command-line interface so it's possible to pass in arguments like --watch to start file watcher with livereload. It's recommended to use --watch while writing documentation to enjoy 3-4x faster compilation performance.

> docs/mdoc --watch

See --help to learn more how to use the command-line interface.

> docs/mdoc --help

Reference

The sbt-mdoc plugin supports the following settings.

Task	Type	Description
`mdoc`	`sbt.InputTask[Unit]`	Run mdoc to generate markdown sources. Supports arguments like --watch to start the file watcher with livereload.
`mdocIn`	`java.io.File`	Input directory containing markdown sources to be processed by mdoc. Defaults to the toplevel docs/ directory.
`mdocOut`	`java.io.File`	Output directory for mdoc generated markdown. Defaults to the target/mdoc directory of this project.
`mdocVariables`	`Map[String, String]`	Site variables that can be referenced from markdown with @VERSION@.
`mdocExtraArguments`	`Seq[String]`	Additional command-line arguments to pass on every mdoc invocation. For example, add '--no-link-hygiene' to disable link hygiene.
`mdocJS`	`scala.Option[sbt.Project]`	Optional Scala.js classpath and compiler options to use for the mdoc:js modifier. To use this setting, set the value to `mdocJS := Some(jsproject)` where `jsproject` must be a Scala.js project.
`mdocJSLibraries`	`sbt.Task[Seq[sbt.internal.util.Attributed[java.io.File]]]`	Additional local JavaScript files to load before loading the mdoc compiled Scala.js bundle. If using scalajs-bundler, set this key to `webpack.in(<mdocJS project>, Compile, fullOptJS).value`.
`mdocAutoDependency`	`Boolean`	If false, do not add mdoc as a library dependency this project. Default value is true.

Command-line

Use coursier to launch mdoc outside of a build tool.

curl -L -o coursier https://git.io/coursier
chmod +x coursier
coursier launch org.scalameta:mdoc_2.12:1.2.3 -- --site.VERSION 1.0.0
info: Compiling 1 file to website/target/docs
info: Compiled in 1.2s (0 errors)

Add libraries to the launched classpath to include them for compilation.

 coursier launch \
   org.scalameta:mdoc_2.12:1.2.3 \
+  org.typelevel:cats-core_2.12:1.5.0

Use --in to customize the input directory where markdown sources are contained, by default the docs/ directory is used.

 coursier launch org.scalameta:mdoc_2.12:1.2.3 -- \
+  --in mydocs

Use --site.VARIABLE=value to add site variables that can be referenced from markdown as @VARIABLE@.

 coursier launch org.scalameta:mdoc_2.12:1.2.3 -- \
+  --site.SCALA_VERSION 2.12.8

Use --out to customize the directory where markdown sources are generated, by default the out/ directory is used.

 coursier launch org.scalameta:mdoc_2.12:1.2.3 -- \
+  --out target/docs

Use --watch to start the file watcher with livereload. It's recommended to use --watch while writing documentation to enjoy 3-4x faster compilation performance.

 coursier launch org.scalameta:mdoc_2.12:1.2.3 -- \
+  --watch

Help

Use --help to learn more how to use the command-line interface.

mdoc v1.2.3
Usage:   mdoc [<option> ...]
Example: mdoc --in <path> --out <path> (customize input/output directories)
         mdoc --watch                  (watch for file changes)
         mdoc --site.VERSION 1.0.0     (pass in site variables)
         mdoc --include **/example.md  (process only files named example.md)
         mdoc --exclude node_modules   (don't process node_modules directory)

mdoc is a documentation tool that interprets Scala code examples within markdown
code fences allowing you to compile and test documentation as part your build. 

Common options:

  --in | -i <path> (default: "docs")
    The input directory containing markdown and other documentation sources.
    Markdown files will be processed by mdoc while other files will be copied
    verbatim to the output directory.

  --out | -o <path> (default: "out")
    The output directory to generate the mdoc site.

  --watch | -w
    Start a file watcher and incrementally re-generate the site on file save.

  --check
    Instead of generating a new site, report an error if generating the site would
    produce a diff against an existing site. Useful for asserting in CI that a
    site is up-to-date.

  --no-link-hygiene
    Disable link hygiene analysis so that no warnings are reported for dead links.

  --verbose
    Include additional diagnostics for debugging potential problems.

  --site Map[String, String] (default: {})
    Key/value pairs of variables to replace through @VAR@. For example, the flag
    '--site.VERSION 1.0.0' will replace appearances of '@VERSION@' in markdown
    files with the string 1.0.0

Compiler options:

  --classpath String (default: "")
    Classpath to use when compiling Scala code examples. Defaults to the current
    thread's classpath.

  --scalac-options String (default: "")
    Compiler flags such as compiler plugins '-Xplugin:kind-projector.jar' or custom
    options '-deprecated'. Formatted as a single string with space separated
    values. To pass multiple values: --scalac-options "-Yrangepos -deprecated".
    Defaults to the value of 'scalacOptions' in the 'mdoc.properties' resource
    file, if any.

  --clean-target
    Remove all files in the output directory before generating a new site.

LiveReload options:

  --no-livereload
    Don't start a LiveReload server under --watch mode.

  --port Int (default: 4000)
    Which port the LiveReload server should listen to. If the port is not free,
    another free port close to this number is used.

  --host String (default: "localhost")
    Which hostname the LiveReload server should listen to

Less common options:

  --help
    Print out a help message and exit

  --usage
    Print out usage instructions and exit

  --version
    Print out the version number and exit

  --include [<glob> ...] (default: [])
    Glob to filter which files to process. Defaults to all files. Example: --include
    **/example.md will process only files with the name example.md.

  --exclude [<glob> ...] (default: [])
    Glob to filter which files from exclude from processing. Defaults to no files.
    Example: --include users/**.md --exclude **/example.md will process all
    files in the users/ directory excluding files named example.md.

  --report-relative-paths
    Use relative filenames when reporting error messages. Useful for producing
    consistent docs on a local machine and CI. 

  --charset Charset (default: "UTF-8")
    The encoding to use when reading and writing files.

  --cwd <path> (default: "<current working directory>")
    The working directory to use for making relative paths absolute.

Library

Add the following dependency to your build

// build.sbt
scalaVersion := "2.12.8" // Any version in 2.12.x works.
libraryDependencies += "org.scalameta" %% "mdoc" % "1.2.3"

Then write a main function that invokes mdoc as a library

It's recommended to use --watch while writing documentation to enjoy 3-4x faster compilation performance.

object Main {
  def main(args: Array[String]): Unit = {
    // build arguments for mdoc
    val settings = mdoc.MainSettings()
      .withSiteVariables(Map("VERSION" -> "1.0.0"))
      .withArgs(args.toList)
    // generate out/readme.md from working directory
    val exitCode = mdoc.Main.process(settings)
    // (optional) exit the main function with exit code 0 (success) or 1 (error)
    if (exitCode != 0) sys.exit(exitCode)
  }
}

If you use sbt-mdoc, update the mdoc task to call run instead of the default runMain mdoc.Main.

// build.sbt
lazy val docs = project
  .in(file("myproject-docs"))
  .settings(
+   mdoc := run.in(Compile).evaluated
  )
  .dependsOn(myproject)
  .enablePlugins(MdocPlugin)

Consult the mdoc source to learn more how to use the library API. Scaladocs are available here but beware there are limited docstrings for classes and methods. Keep in mind that code in the package mdoc.internal is subject to binary and source breaking changes between any release, including PATCH versions.