Amazing Markdown processor

suppose we have markdown file look like this

```scala
   case class Point2d(x: Int, y: Int)
   val p = Point2d(10, 20)
``

by replacing scala with scala mdoc:

```scala mdoc
   case class Point2d(x: Int, y: Int)
   val p = Point2d(10, 20)
``

we pass this snippet over its processing engine. What it does, is:

  • compiles the snippet
  • runs it
  • attaches compiler output to the same block:
case class Point2d(x: Int, y: Int)
val p = Point2d(10, 20)
// p: Point2d = Point2d(x = 10, y = 20)

by replacing scala mdoc with scala mdoc:fail it also attaches compiler output

```scala mdoc:fail
sealed trait Color
case object Red extends Color
case object Yellow extends Color
case object Green extends Color

def show(c: Color): String = c match {
  case Red => "Red"
  case Green => "Green"
}
``

becomes

sealed trait Color
case object Red extends Color
case object Yellow extends Color
case object Green extends Color

def show(c: Color): String = c match {
  case Red => "Red"
  case Green => "Green"
}
// error: match may not be exhaustive.
// It would fail on the following input: Yellow
// Applicable -Wconf / @nowarn filters for this fatal warning: msg=<part of the message>, cat=other-match-analysis, site=repl.MdocSession.MdocApp.show
// def show(c: Color): String = c match {
//                              ^

by replacing scala mdoc with scala mdoc:crash it handles exceptions

```scala mdoc:crash
println(1/0)
``

becomes

println(1/0)
// java.lang.ArithmeticException: / by zero
// 	at repl.MdocSession$MdocApp$$anonfun$1.apply$mcV$sp(2024-03-15-why-scala.md:33)
// 	at repl.MdocSession$MdocApp$$anonfun$1.apply(2024-03-15-why-scala.md:33)
// 	at repl.MdocSession$MdocApp$$anonfun$1.apply(2024-03-15-why-scala.md:33)
  • here is the link to github
  • here is the link to documentation
  • it has an sbt plugin which can do that as a part of CI/CD pipeline

  • it has an ability to write own processors and inject whatever you need into your .md files

  • the configuration is easy:
    • add one line to plugins.sbt 
      addSbtPlugin("org.scalameta" % "sbt-mdoc" % "2.5.2")
    • add one more project to build.sbt: 
      lazy val `xyz-docs` = (project in file("xyz-docs"))
  .enablePlugins(MdocPlugin)
    • put .md file(s) into docs folder (related to the project root)
    • inside sbt shell, run xyz-docs/mdoc
    • look for processed file(s) at xyz-docs/target/mdoc folder