Preprocessing
sbt-site supports simple variable and Regular Expression substitution via the PreprocessPlugin
if for example you need to replace a version string in a source file or a generated HTML file. More advanced preprocessing, such as interpreting code snippets with [tut], is possible via additional configuration as shown below.
Substitution
The PreprocessPlugin
reads files from an input directory, substitute variables and writes them to an output directory. In addition to preprocessing static content it is also possible to use the plugin either before or after invoking a site generator. To enable, add this to your build.sbt
file:
sourceenablePlugins(PreprocessPlugin)
By default files are read from src/site-preprocess
but this is configurable by setting sourceDirectory
:
sourcePreprocess / sourceDirectory := sourceDirectory.value / "site-preprocess"
Variables are delimited by surrounding the name with @
symbols (e.g. @VERSION@
). Values are assigned to variables via the setting preprocessVars: Map[String, String]
. For example:
sourcePreprocess / preprocessVars := Map("VERSION" -> version.value, "DATE" -> new Date().toString)
The plugin will generate an error if a variable is found in the source file with no matching value in preprocessVars
.
More advanced substitution patterns can be used by providing Regular Expression rules via the setting preprocessRules: Seq[(Regex, Match => String)]
. For example Scaladoc used to (before 2.12.9 and 2.13.0) prepend “.scala” to source links of Java files. The following preprocessing rule will find and fix such links:
sourcepreprocessRules in Preprocess := Seq(
("\\.java\\.scala".r, _ => ".java")
)
The setting preprocessIncludeFilter
is used to define the filename extensions that should be processed when makeSite
is run.
sourcepreprocessIncludeFilter := "*.md" | "*.markdown"
The default filter is:
source"*.txt" | "*.html" | "*.md" | "*.rst"