Generating pages with code

You can make use of source generators to define code that produces pages to be included in your paradox build.

To do this you must define the sourceGenerators property for paradoxMarkdownToHtml.

The below example shows a build.sbt file that generates an extra markdown page via code:

lazy val root = (project in file(".")).
  enablePlugins(ParadoxPlugin).
  settings(
    name := "Generator Project",
    paradoxTheme := Some(builtinParadoxTheme("generic")),
    sourceGenerators in (Compile, paradoxMarkdownToHtml) += Def.task {
      val file = (sourceManaged in (Compile, paradox)).value / "generated-page.md"
    
      IO.write(file, "# Markdown generated by code!")
    
      Seq(file)
    }.taskValue
  )

Your non-generated pages can link to this generated-page.md as if it exists alongside them under src/main/paradox.

Take care to ensure files you output are created under the sourceManaged in (Compile, paradox) directory so they can be discovered and linked to from non-generated pages under src/main/paradox.

Scala code example

The following snippets show an example with the source generator function split into its own Scala file.

project/plugins.sbt:

addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.10.7")

project/SourceGenerators.scala:

import com.lightbend.paradox.sbt.ParadoxPlugin.autoImport.paradox
import sbt.Keys._
import sbt._

object SourceGenerators {
  def generatePage: Def.Initialize[Task[Seq[File]]] = Def.task {
    val generatedPage = (sourceManaged in (Compile, paradox)).value / "generated-page.md"
    IO.write(generatedPage, "Generated Page 1")

    Seq(generatedPage)
  }
}

build.sbt:

lazy val root = (project in file(".")).
  enablePlugins(ParadoxPlugin).
  settings(
    name := "Generator Project",
    paradoxTheme := Some(builtinParadoxTheme("generic")),
    sourceGenerators in (Compile, paradoxMarkdownToHtml) += SourceGenerators.generatePage.taskValue
  )