marklit · v0.1.0

The build breaks

If the doc claims something works, the build breaks when it does not.

marklit compiles each Scala fence in a Markdown file against the real project classpath, runs it, and writes the output back. One file can hold more than one Scala version. Each fence is compiled by its own compiler.

Two compilers

MarkdownParser.parse reads the file. Each fence is compiled by the compiler for its Scala version (Compiler.compile) and then executed. MarkdownRenderer.render produces the markdown, and the run writes that one file.

markdown fileparseScala 3Scala 2executeexecuterenderrendered file

Install

The coordinate is the last published release. A build whose version contains -ci, +, or SNAPSHOT still shows that release.

addSbtPlugin("rocks.earlyeffect" % "sbt-marklit" % "0.1.0")

Compile

Compiler.compile on the companion takes the fence and its scope and asks the Compiler service to compile. It is not inline. Two parameters, so the cite is cite(Compiler.compile(_, _)). The panel is that method. The footer is the definition.

marklit.compiler.Compiler.compile
def compile(
      code: String,
      context: ScopeContext
  ): ZIO[Compiler, MarklitError, CompileResult] =
    ZIO.serviceWithZIO[Compiler](_.compile(code, context))

View source

One fence

This fence is compiled by the docs build, against marklit. It parses one markdown file and checks that the two fences name two Scala versions. If they do not, the build breaks.

{
      val source =
        """```scala marklit:scala=3.3.7
println(1 + 1)
```

```scala marklit:scala=2.13.16
println(2 + 2)
```
""".stripMargin
      MarkdownParser.parse(source, "two-compilers.md").map { doc =>
        doc.codeBlocks.map(_.requestedSpecificScalaVersion)
      }
    }
Vector(Some(3.3.7), Some(2.13.16))